Scelta di un modello
Consigliamo di utilizzare il modello Claude Sonnet (4.5) o Claude Opus (4.1) più recente per strumenti complessi e query ambigue; gestiscono meglio più strumenti e cercano chiarimenti quando necessario. Utilizza i modelli Claude Haiku per strumenti semplici, ma tieni presente che potrebbero dedurre parametri mancanti.Specifica degli strumenti client
Gli strumenti client (sia definiti da Anthropic che definiti dall’utente) sono specificati nel parametro di primo livellotools della richiesta API. Ogni definizione di strumento include:
| Parametro | Descrizione |
|---|---|
name | Il nome dello strumento. Deve corrispondere all’espressione regolare ^[a-zA-Z0-9_-]{1,64}$. |
description | Una descrizione dettagliata in testo semplice di cosa fa lo strumento, quando deve essere utilizzato e come si comporta. |
input_schema | Un oggetto JSON Schema che definisce i parametri previsti per lo strumento. |
Esempio di definizione di strumento semplice
Esempio di definizione di strumento semplice
get_weather, prevede un oggetto di input con una stringa location obbligatoria e una stringa unit facoltativa che deve essere “celsius” o “fahrenheit”.Prompt di sistema per l’uso degli strumenti
Quando chiami l’API Claude con il parametrotools, 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 utilizzare gli strumenti specificati e fornire il contesto necessario affinché lo strumento funzioni correttamente:
Best practice per le definizioni degli strumenti
Per ottenere le migliori prestazioni da Claude quando utilizzi gli strumenti, segui queste linee guida:- Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante per le prestazioni dello strumento. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, incluso:
- Cosa fa lo strumento
- Quando deve essere utilizzato (e quando non deve)
- 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 fornire a Claude sui tuoi strumenti, meglio sarà in grado di decidere quando e come utilizzarli. Punta a almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
- Dai priorità alle descrizioni rispetto agli esempi. Sebbene tu possa includere esempi di come utilizzare uno strumento nella sua descrizione o nel prompt di accompagnamento, questo è meno importante che avere una spiegazione chiara e completa dello scopo e dei parametri dello strumento. Aggiungi esempi solo dopo aver completamente sviluppato la descrizione.
Esempio di una buona descrizione dello strumento
Esempio di una buona descrizione dello strumento
Esempio di descrizione dello strumento scadente
Esempio di descrizione dello strumento scadente
ticker. La descrizione scadente è troppo breve e lascia Claude con molte domande aperte sul comportamento e l’utilizzo dello strumento.
Tool runner (beta)
Il tool runner fornisce una soluzione pronta all’uso per eseguire strumenti con Claude. Invece di gestire manualmente le chiamate degli strumenti, i risultati degli strumenti e la gestione della conversazione, il tool runner automaticamente:- Esegue gli strumenti quando Claude li chiama
- Gestisce il ciclo di richiesta/risposta
- Gestisce lo stato della conversazione
- Fornisce sicurezza dei tipi e convalida
Utilizzo di base
@beta_tool per definire gli strumenti e client.beta.messages.tool_runner() per eseguirli.@beta_tool con @beta_async_tool e definisci la funzione con async def.@beta_tool ispezionerà gli argomenti della funzione e la docstring per estrarre una rappresentazione dello schema json della funzione data, nell’esempio sopra calculate_sum verrà trasformato in:Controllo dell’output di Claude
Forzare l’uso degli strumenti
In alcuni casi, potresti voler che Claude utilizzi uno strumento specifico per rispondere alla domanda dell’utente, anche se Claude pensa di poter fornire una risposta senza utilizzare uno strumento. Puoi farlo specificando lo strumento nel campotool_choice come segue:
autoconsente a Claude di decidere se chiamare uno degli strumenti forniti o meno. Questo è il valore predefinito quando vengono fornititools.anydice a Claude che deve utilizzare uno degli strumenti forniti, ma non forza uno strumento particolare.toolci consente di forzare Claude a utilizzare sempre uno strumento particolare.noneimpedisce a Claude di utilizzare qualsiasi strumento. Questo è il valore predefinito quando non vengono fornititools.
tool_choice invalideranno i blocchi di messaggi memorizzati nella cache. Le definizioni degli strumenti e i prompt di sistema rimangono memorizzati nella cache, ma il contenuto del messaggio deve essere rielaborato.
tool_choice come any o tool, precompileremo il messaggio dell’assistente per forzare l’uso di uno strumento. Ciò significa che i modelli non emetteranno una risposta in linguaggio naturale o una spiegazione prima dei blocchi di contenuto tool_use, anche se esplicitamente richiesto di farlo.
tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} non sono supportati e risulteranno in un errore. Solo tool_choice: {"type": "auto"} (il valore predefinito) e tool_choice: {"type": "none"} sono compatibili con il pensiero esteso.{"type": "auto"} per tool_choice (il valore predefinito) e aggiungere istruzioni esplicite in un messaggio user. Ad esempio: What's the weather like in London? Use the get_weather tool in your response.
Output JSON
Gli strumenti non devono necessariamente essere funzioni client — puoi utilizzare gli strumenti ogni volta che desideri che il modello restituisca un output JSON che segua uno schema fornito. Ad esempio, potresti utilizzare uno strumentorecord_summary con uno schema particolare. Vedi Tool use with Claude per un esempio di lavoro completo.
Risposte del modello con strumenti
Quando si utilizzano gli strumenti, Claude spesso commenterà cosa sta facendo o risponderà naturalmente all’utente prima di invocare gli strumenti. Ad esempio, data la richiesta “What’s the weather like in San Francisco right now, and what time is it there?”, Claude potrebbe rispondere con:<examples> nei tuoi prompt.
È importante notare che Claude può utilizzare varie formulazioni e approcci quando spiega le sue azioni. Il tuo codice dovrebbe trattare queste risposte come qualsiasi altro testo generato dall’assistente e non fare affidamento su convenzioni di formattazione specifiche.
Uso parallelo degli strumenti
Per impostazione predefinita, Claude può utilizzare più strumenti per rispondere a una query dell’utente. Puoi disabilitare questo comportamento da:- Impostazione di
disable_parallel_tool_use=truequando il tipo di tool_choice èauto, che garantisce che Claude utilizzi al massimo uno strumento - Impostazione di
disable_parallel_tool_use=truequando il tipo di tool_choice èanyotool, che garantisce che Claude utilizzi esattamente uno strumento
Esempio completo di uso parallelo degli strumenti
Esempio completo di uso parallelo degli strumenti
Script di test completo per strumenti paralleli
Script di test completo per strumenti paralleli
- Come formattare correttamente le chiamate parallele degli strumenti e i risultati
- Come verificare che le chiamate parallele vengono effettuate
- La struttura corretta dei messaggi che incoraggia l’uso parallelo futuro degli strumenti
- Gli errori comuni da evitare (come il testo prima dei risultati degli strumenti)
Massimizzazione dell’uso parallelo degli strumenti
Sebbene i modelli Claude 4 abbiano 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:Prompt di sistema per l'uso parallelo degli strumenti
Prompt di sistema per l'uso parallelo degli strumenti
Prompt del messaggio utente
Prompt del messaggio utente
disable_parallel_tool_use. Per aggirare questo, consigliamo di abilitare token-efficient tool use, che aiuta a incoraggiare Claude a utilizzare strumenti paralleli. Questa funzione beta riduce anche la latenza e risparmia in media il 14% nei token di output.Se preferisci non optare per il beta di token-efficient tool use, puoi anche introdurre uno “strumento batch” che può agire come meta-strumento per avvolgere le invocazioni ad altri strumenti contemporaneamente. Scopriamo che se questo strumento è presente, il modello lo utilizzerà per chiamare simultaneamente più strumenti in parallelo per te.Vedi questo esempio nel nostro cookbook per come utilizzare questo workaround.Gestione dei blocchi di contenuto tool use e tool result
Gestione dei risultati dagli strumenti client
La risposta avrà unstop_reason di tool_use e uno o più blocchi di contenuto tool_use che includono:
id: Un identificatore univoco per questo particolare blocco di tool use. Questo verrà utilizzato per abbinare i risultati dello strumento in seguito.name: Il nome dello strumento utilizzato.input: Un oggetto contenente l’input passato allo strumento, conforme ainput_schemadello strumento.
Esempio di risposta API con un blocco di contenuto `tool_use`
Esempio di risposta API con un blocco di contenuto `tool_use`
- Estrarre
name,ideinputdal bloccotool_use. - Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome di strumento, passando l’
inputdello strumento. - Continuare la conversazione inviando un nuovo messaggio con il
rolediusere un bloccocontentcontenente il tipotool_resulte le seguenti informazioni:tool_use_id: L’iddella richiesta di tool use per cui questo è un risultato.content: Il risultato dello strumento, come stringa (ad es."content": "15 degrees"), un elenco di blocchi di contenuto annidati (ad es."content": [{"type": "text", "text": "15 degrees"}]), o un elenco di blocchi di documenti (ad es."content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Questi blocchi di contenuto possono utilizzare i tipitext,imageodocument.is_error(facoltativo): Impostato sutruese l’esecuzione dello strumento ha causato un errore.
- I blocchi di risultato dello strumento devono seguire immediatamente i loro corrispondenti blocchi di tool use nella cronologia dei messaggi. Non puoi includere alcun messaggio tra il messaggio di tool use 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 di contenuto. Qualsiasi testo deve venire DOPO tutti i risultati dello strumento.
Esempio di risultato dello strumento riuscito
Esempio di risultato dello strumento riuscito
Esempio di risultato dello strumento con immagini
Esempio di risultato dello strumento con immagini
Esempio di risultato dello strumento vuoto
Esempio di risultato dello strumento vuoto
Esempio di risultato dello strumento con documenti
Esempio di risultato dello strumento con documenti
Gestione dei risultati dagli strumenti server
Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriore interazione dell’utente.tool o function, l’API Claude 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’IA e tool_use.Gestione del motivo di arresto max_tokens
Se la risposta di Claude viene interrotta a causa del raggiungimento del limite max_tokens e la risposta troncata contiene un blocco di tool use incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere il tool use completo.
Gestione del motivo di arresto pause_turn
Quando si utilizzano strumenti server come la ricerca web, l’API può 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:
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 facoltativamente modificare il contenuto prima di continuare se desideri interrompere o reindirizzare la conversazione
- Preserva lo stato dello strumento: Includi gli stessi strumenti nella richiesta di continuazione per mantenere la funzionalità
Risoluzione dei problemi degli errori
Errore di esecuzione dello strumento
Errore di esecuzione dello strumento
content insieme a "is_error": true:Nome dello strumento non valido
Nome dello strumento non valido
description più dettagliati nelle tue definizioni di strumento.Tuttavia, puoi anche continuare la conversazione in avanti con un tool_result che indica l’errore, e Claude proverà a utilizzare lo strumento di nuovo con le informazioni mancanti compilate:Tag <search_quality_reflection>
Tag <search_quality_reflection>
Errori degli strumenti server
Errori degli strumenti server
is_error per gli strumenti server.Per la ricerca web in particolare, i possibili codici di errore includono:too_many_requests: Limite di velocità superatoinvalid_input: Parametro di query di ricerca non validomax_uses_exceeded: Massimo utilizzo dello strumento di ricerca web superatoquery_too_long: La query supera la lunghezza massimaunavailable: Si è verificato un errore interno
Le chiamate parallele degli strumenti non funzionano
Le chiamate parallele degli strumenti non funzionano
- ❌ Sbagliato: Invio di messaggi utente separati per ogni risultato dello strumento
- ✅ Corretto: Tutti i risultati dello strumento devono essere in un singolo messaggio utente
- Claude Opus 4.1, Opus 4 e Sonnet 4: Eccellono nell’uso parallelo degli strumenti con prompt minimo
- Claude Sonnet 3.7: Potrebbe aver bisogno di prompt più forti o token-efficient tool use
- Claude Haiku: Meno propenso a utilizzare strumenti paralleli senza prompt esplicito