Come implementare l'uso degli strumenti
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:
Parametro | Descrizione |
---|---|
name | Il nome dello strumento. Deve corrispondere alla regex ^[a-zA-Z0-9_-]{1,64}$ . |
description | Una descrizione dettagliata in testo semplice di cosa fa lo strumento, quando dovrebbe essere usato e come si comporta. |
input_schema | Un 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:
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ì:
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 fornititools
.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 fornititools
.
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:
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
otool
, 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:
- Estrarre
name
,id
einput
dal bloccotool_use
. - Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome dello strumento, passando l’
input
dello strumento. - Continuare la conversazione inviando un nuovo messaggio con il
role
diuser
, e un bloccocontent
contenente il tipotool_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 tipitext
oimage
.is_error
(opzionale): Imposta sutrue
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:
Questo è corretto:
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.
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
:
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: