Scegliere un modello

In generale, usa Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 o Claude Opus 3 per strumenti complessi e query ambigue; gestiscono meglio più strumenti e cercano chiarimenti quando necessario.

Usa Claude Haiku 3.5 o Claude Haiku 3 per strumenti semplici, ma nota che potrebbero inferire parametri mancanti.

Se usi Claude Sonnet 3.7 con l’uso di strumenti e il pensiero esteso, consulta la nostra guida qui per maggiori informazioni.

Specificare gli strumenti client

Gli strumenti client (sia definiti da Anthropic che dall’utente) sono specificati nel parametro di livello superiore tools della richiesta API. Ogni definizione di strumento include:

ParametroDescrizione
nameIl nome dello strumento. Deve corrispondere alla regex ^[a-zA-Z0-9_-]{1,64}$.
descriptionUna descrizione dettagliata in testo semplice di cosa fa lo strumento, quando dovrebbe essere usato e come si comporta.
input_schemaUn oggetto JSON Schema che definisce i parametri attesi per lo strumento.

Prompt di sistema per l’uso degli strumenti

Quando chiami l’API Anthropic con il parametro tools, costruiamo un prompt di sistema speciale dalle definizioni degli strumenti, dalla configurazione degli strumenti e da qualsiasi prompt di sistema specificato dall’utente. Il prompt costruito è progettato per istruire il modello a usare gli strumenti specificati e fornire il contesto necessario per il corretto funzionamento dello strumento:

In questo ambiente hai accesso a un set di strumenti che puoi usare per rispondere alla domanda dell'utente.
{{ ISTRUZIONI DI FORMATTAZIONE }}
I parametri stringa e scalari dovrebbero essere specificati così come sono, mentre liste e oggetti dovrebbero usare il formato JSON. Nota che gli spazi per i valori stringa non vengono rimossi. L'output non è previsto che sia XML valido e viene analizzato con espressioni regolari.
Ecco le funzioni disponibili in formato JSONSchema:
{{ DEFINIZIONI DEGLI STRUMENTI IN JSON SCHEMA }}
{{ PROMPT DI SISTEMA UTENTE }}
{{ CONFIGURAZIONE DEGLI STRUMENTI }}

Migliori pratiche per le definizioni degli strumenti

Per ottenere le migliori prestazioni da Claude quando usi gli strumenti, segui queste linee guida:

  • Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante nelle prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, incluso:
    • Cosa fa lo strumento
    • Quando dovrebbe essere usato (e quando non dovrebbe)
    • Cosa significa ogni parametro e come influisce sul comportamento dello strumento
    • Eventuali avvertenze o limitazioni importanti, come quali informazioni lo strumento non restituisce se il nome dello strumento non è chiaro. Più contesto puoi dare a Claude sui tuoi strumenti, meglio sarà nel decidere quando e come usarli. Punta ad almeno 3-4 frasi per descrizione di strumento, di più se lo strumento è complesso.
  • Dai priorità alle descrizioni rispetto agli esempi. Mentre puoi includere esempi di come usare uno strumento nella sua descrizione o nel prompt di accompagnamento, questo è meno importante di avere una spiegazione chiara e completa dello scopo e dei parametri dello strumento. Aggiungi esempi solo dopo aver completamente sviluppato la descrizione.

La buona descrizione spiega chiaramente cosa fa lo strumento, quando usarlo, quali dati restituisce e cosa significa il parametro ticker. La descrizione scadente è troppo breve e lascia Claude con molte domande aperte sul comportamento e l’uso dello strumento.

Controllare l’output di Claude

Forzare l’uso degli strumenti

In alcuni casi, potresti voler che Claude usi uno strumento specifico per rispondere alla domanda dell’utente, anche se Claude pensa di poter fornire una risposta senza usare uno strumento. Puoi farlo specificando lo strumento nel campo tool_choice così:

tool_choice = {"type": "tool", "name": "get_weather"}

Quando lavori con il parametro tool_choice, abbiamo quattro opzioni possibili:

  • auto permette a Claude di decidere se chiamare qualsiasi strumento fornito o no. Questo è il valore predefinito quando vengono forniti tools.
  • any dice a Claude che deve usare uno degli strumenti forniti, ma non forza uno strumento particolare.
  • tool ci permette di forzare Claude a usare sempre uno strumento particolare.
  • none impedisce a Claude di usare qualsiasi strumento. Questo è il valore predefinito quando non vengono forniti tools.

Quando usi la cache dei prompt, le modifiche al parametro tool_choice invalideranno i blocchi di messaggi memorizzati nella cache. Le definizioni degli strumenti e i prompt di sistema rimangono nella cache, ma il contenuto dei messaggi deve essere rielaborato.

Questo diagramma illustra come funziona ogni opzione:

Nota che quando hai tool_choice come any o tool, precompileremo il messaggio dell’assistente per forzare l’uso di uno strumento. Questo significa che i modelli non emetteranno un blocco di contenuto text di catena di pensiero prima dei blocchi di contenuto tool_use, anche se esplicitamente richiesto di farlo.

Quando usi il pensiero esteso con l’uso degli strumenti, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} non sono supportati e risulteranno in un errore. Solo tool_choice: {"type": "auto"} (il predefinito) e tool_choice: {"type": "none"} sono compatibili con il pensiero esteso.

I nostri test hanno mostrato che questo non dovrebbe ridurre le prestazioni. Se vuoi mantenere la catena di pensiero (particolarmente con Opus) mentre richiedi ancora che il modello usi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il predefinito) e aggiungere istruzioni esplicite in un messaggio user. Per esempio: Com'è il tempo a Londra? Usa lo strumento get_weather nella tua risposta.

Output JSON

Gli strumenti non devono necessariamente essere funzioni client — puoi usare gli strumenti ogni volta che vuoi che il modello restituisca output JSON che segue uno schema fornito. Per esempio, potresti usare uno strumento record_summary con uno schema particolare. Vedi Uso degli strumenti con Claude per un esempio funzionante completo.

Catena di pensiero

Quando usa gli strumenti, Claude mostrerà spesso la sua “catena di pensiero”, cioè il ragionamento passo dopo passo che usa per scomporre il problema e decidere quali strumenti usare. Il modello Claude Opus 3 farà questo se tool_choice è impostato su auto (questo è il valore predefinito, vedi Forzare l’uso degli strumenti), e Sonnet e Haiku possono essere spinti a farlo.

Per esempio, dato il prompt “Com’è il tempo a San Francisco adesso, e che ora è lì?”, Claude potrebbe rispondere con:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Per rispondere a questa domanda, farò: 1. Usare lo strumento get_weather per ottenere il meteo attuale a San Francisco. 2. Usare lo strumento get_time per ottenere l'ora attuale nel fuso orario America/Los_Angeles, che copre San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Questa catena di pensiero fornisce intuizioni sul processo di ragionamento di Claude e può aiutarti a debuggare comportamenti inaspettati.

Con il modello Claude Sonnet 3, la catena di pensiero è meno comune per impostazione predefinita, ma puoi spingere Claude a mostrare il suo ragionamento aggiungendo qualcosa come "Prima di rispondere, spiega il tuo ragionamento passo dopo passo in tag." al messaggio utente o al prompt di sistema.

È importante notare che mentre i tag <thinking> sono una convenzione comune che Claude usa per denotare la sua catena di pensiero, il formato esatto (come il nome di questo tag XML) potrebbe cambiare nel tempo. Il tuo codice dovrebbe trattare la catena di pensiero come qualsiasi altro testo generato dall’assistente, e non fare affidamento sulla presenza o formattazione specifica dei tag <thinking>.

Uso parallelo degli strumenti

Per impostazione predefinita, Claude può usare più strumenti per rispondere a una query utente. Puoi disabilitare questo comportamento:

  • Impostando disable_parallel_tool_use=true quando il tipo tool_choice è auto, il che assicura che Claude usi al massimo uno strumento
  • Impostando disable_parallel_tool_use=true quando il tipo tool_choice è any o tool, il che assicura che Claude usi esattamente uno strumento

Massimizzare l’uso parallelo degli strumenti

Mentre i modelli Claude 4 hanno eccellenti capacità di uso parallelo degli strumenti per impostazione predefinita, puoi aumentare la probabilità di esecuzione parallela degli strumenti su tutti i modelli con prompt mirati:

Uso parallelo degli strumenti con Claude Sonnet 3.7

Claude Sonnet 3.7 potrebbe essere meno propenso a fare chiamate di strumenti paralleli in una risposta, anche quando non hai impostato disable_parallel_tool_use. Per aggirare questo, raccomandiamo di abilitare l’uso efficiente dei token degli strumenti, che aiuta a incoraggiare Claude a usare strumenti paralleli. Questa funzionalità beta riduce anche la latenza e risparmia in media il 14% nei token di output.

Se preferisci non optare per la beta dell’uso efficiente dei token degli strumenti, puoi anche introdurre uno “strumento batch” che può agire come meta-strumento per avvolgere invocazioni ad altri strumenti simultaneamente. Troviamo che se questo strumento è presente, il modello lo userà per chiamare simultaneamente più strumenti in parallelo per te.

Vedi questo esempio nel nostro cookbook per come usare questa soluzione alternativa.

Gestire i blocchi di contenuto tool use e tool result

La risposta di Claude differisce in base al fatto che usi uno strumento client o server.

Gestire i risultati dagli strumenti client

La risposta avrà un stop_reason di tool_use e uno o più blocchi di contenuto tool_use che includono:

  • id: Un identificatore unico per questo particolare blocco di uso dello strumento. Questo sarà usato per abbinare i risultati dello strumento più tardi.
  • name: Il nome dello strumento che viene usato.
  • input: Un oggetto contenente l’input che viene passato allo strumento, conforme all’input_schema dello strumento.

Quando ricevi una risposta di uso dello strumento per uno strumento client, dovresti:

  1. Estrarre name, id e input dal blocco tool_use.
  2. Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome dello strumento, passando l’input dello strumento.
  3. Continuare la conversazione inviando un nuovo messaggio con il role di user, e un blocco content contenente il tipo tool_result e le seguenti informazioni:
    • tool_use_id: L’id della richiesta di uso dello strumento per cui questo è un risultato.
    • content: Il risultato dello strumento, come stringa (ad es. "content": "15 gradi") o lista di blocchi di contenuto annidati (ad es. "content": [{"type": "text", "text": "15 gradi"}]). Questi blocchi di contenuto possono usare i tipi text o image.
    • is_error (opzionale): Imposta su true se l’esecuzione dello strumento ha risultato in un errore.

Requisiti di formattazione importanti:

  • I blocchi di risultato dello strumento devono seguire immediatamente i loro corrispondenti blocchi di uso dello strumento nella cronologia dei messaggi. Non puoi includere messaggi tra il messaggio di uso dello strumento dell’assistente e il messaggio di risultato dello strumento dell’utente.
  • Nel messaggio utente contenente i risultati dello strumento, i blocchi tool_result devono venire PRIMA nell’array content. Qualsiasi testo deve venire DOPO tutti i risultati dello strumento.

Per esempio, questo causerà un errore 400:

{"role": "user", "content": [
  {"type": "text", "text": "Ecco i risultati:"},  // ❌ Testo prima di tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Questo è corretto:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "Cosa dovrei fare dopo?"}  // ✅ Testo dopo tool_result
]}

Se ricevi un errore come “tool_use ids were found without tool_result blocks immediately after”, controlla che i tuoi risultati dello strumento siano formattati correttamente.

Dopo aver ricevuto il risultato dello strumento, Claude userà quell’informazione per continuare a generare una risposta al prompt utente originale.

Gestire i risultati dagli strumenti server

Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriore interazione dell’utente.

Differenze da altre API

A differenza delle API che separano l’uso degli strumenti o usano ruoli speciali come tool o function, l’API di Anthropic integra gli strumenti direttamente nella struttura dei messaggi user e assistant.

I messaggi contengono array di blocchi text, image, tool_use e tool_result. I messaggi user includono contenuto client e tool_result, mentre i messaggi assistant contengono contenuto generato dall’AI e tool_use.

Gestire il motivo di arresto max_tokens

Se la risposta di Claude viene troncata a causa del raggiungimento del limite max_tokens, e la risposta troncata contiene un blocco di uso dello strumento incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere l’uso completo dello strumento.

# Controllare se la risposta è stata troncata durante l'uso dello strumento
if response.stop_reason == "max_tokens":
    # Controllare se l'ultimo blocco di contenuto è un tool_use incompleto
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Inviare la richiesta con max_tokens più alto
        response = client.messages.create(
            model="claude-opus-4-20250514",
            max_tokens=4096,  # Limite aumentato
            messages=messages,
            tools=tools
        )

Gestire il motivo di arresto pause_turn

Quando usi strumenti server come la ricerca web, l’API potrebbe restituire un motivo di arresto pause_turn, indicando che l’API ha messo in pausa un turno di lunga durata.

Ecco come gestire il motivo di arresto pause_turn:

import anthropic

client = anthropic.Anthropic()

# Richiesta iniziale con ricerca web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Cerca informazioni complete sui progressi del quantum computing nel 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Controllare se la risposta ha il motivo di arresto pause_turn
if response.stop_reason == "pause_turn":
    # Continuare la conversazione con il contenuto in pausa
    messages = [
        {"role": "user", "content": "Cerca informazioni complete sui progressi del quantum computing nel 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Inviare la richiesta di continuazione
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Quando gestisci pause_turn:

  • Continua la conversazione: Passa la risposta in pausa così com’è in una richiesta successiva per permettere a Claude di continuare il suo turno
  • Modifica se necessario: Puoi opzionalmente modificare il contenuto prima di continuare se vuoi interrompere o reindirizzare la conversazione
  • Preserva lo stato dello strumento: Includi gli stessi strumenti nella richiesta di continuazione per mantenere la funzionalità

Risoluzione degli errori

Ci sono alcuni tipi diversi di errori che possono verificarsi quando usi gli strumenti con Claude: