Come implementare l'uso degli strumenti

Scelta di un modello

Consigliamo di utilizzare il modello Claude Opus (4.6) più recente per strumenti complessi e query ambigue; gestisce meglio più strumenti e chiede 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 tools di livello superiore della richiesta API. Ogni definizione di strumento include:

Prompt di sistema per l'uso degli strumenti

Quando chiami l'API Claude 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 utilizzare gli strumenti specificati e fornire il contesto necessario affinché lo strumento funzioni correttamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

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 nelle prestazioni degli strumenti. 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à nel decidere quando e come utilizzarli. Mira a almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni, ma considera di utilizzare input_examples per strumenti complessi. Le descrizioni chiare sono più importanti, ma per strumenti con input complessi, oggetti annidati o parametri sensibili al formato, puoi utilizzare il campo input_examples per fornire esempi convalidati dallo schema. Vedi Fornire esempi di uso degli strumenti per i dettagli.

La buona descrizione spiega chiaramente cosa fa lo strumento, quando utilizzarlo, 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'utilizzo dello strumento.

Fornire esempi di uso degli strumenti

Puoi fornire esempi concreti di input di strumenti validi per aiutare Claude a capire come utilizzare i tuoi strumenti in modo più efficace. Questo è particolarmente utile per strumenti complessi con oggetti annidati, parametri facoltativi o input sensibili al formato.

Utilizzo di base

Aggiungi un campo input_examples facoltativo alla tua definizione di strumento con un array di oggetti di input di esempio. Ogni esempio deve essere valido secondo lo input_schema dello strumento:

Gli esempi sono inclusi nel prompt insieme al tuo schema dello strumento, mostrando a Claude modelli concreti per chiamate di strumenti ben formate. Questo aiuta Claude a capire quando includere parametri facoltativi, quali formati utilizzare e come strutturare input complessi.

Requisiti e limitazioni

• Convalida dello schema - Ogni esempio deve essere valido secondo lo input_schema dello strumento. Gli esempi non validi restituiscono un errore 400
• Non supportato per strumenti lato server - Solo gli strumenti definiti dall'utente possono avere esempi di input
• Costo dei token - Gli esempi si aggiungono ai token del prompt: ~20-50 token per esempi semplici, ~100-200 token per oggetti annidati complessi

Tool runner (beta)

Il tool runner fornisce una soluzione pronta all'uso per l'esecuzione di strumenti con Claude. Invece di gestire manualmente le chiamate di 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

Consigliamo di utilizzare il tool runner per la maggior parte delle implementazioni di uso degli strumenti.

Utilizzo di base

Definisci gli strumenti utilizzando gli helper SDK, quindi utilizza il tool runner per eseguirli.

La funzione dello strumento deve restituire un blocco di contenuto o un array di blocchi di contenuto, inclusi testo, immagini o blocchi di documenti. Ciò consente agli strumenti di restituire risposte ricche e multimodali. Le stringhe restituite verranno convertite in un blocco di contenuto di testo. Se desideri restituire un oggetto JSON strutturato a Claude, codificalo in una stringa JSON prima di restituirlo. I numeri, i booleani o altri primitivi non stringa devono essere convertiti anche in stringhe.

Iterazione sul tool runner

Il tool runner è un iterabile che produce messaggi da Claude. Questo è spesso indicato come un "tool call loop". Ad ogni iterazione, il runner controlla se Claude ha richiesto un uso dello strumento. Se è così, chiama lo strumento e invia il risultato a Claude automaticamente, quindi produce il messaggio successivo da Claude per continuare il tuo loop.

Puoi terminare il loop in qualsiasi iterazione con un'istruzione break. Il runner continuerà il loop fino a quando Claude non restituisce un messaggio senza un uso dello strumento.

Se non hai bisogno di messaggi intermedi, puoi ottenere il messaggio finale direttamente:

Utilizzo avanzato

All'interno del loop, puoi personalizzare completamente la richiesta successiva del tool runner all'API Messages. Il runner aggiunge automaticamente i risultati degli strumenti alla cronologia dei messaggi, quindi non devi gestirli manualmente. Puoi facoltativamente ispezionare il risultato dello strumento per la registrazione o il debug e modificare i parametri della richiesta prima della prossima chiamata API.

Debug dell'esecuzione dello strumento

Quando uno strumento genera un'eccezione, il tool runner la cattura e restituisce l'errore a Claude come risultato dello strumento con is_error: true. Per impostazione predefinita, è incluso solo il messaggio di eccezione, non l'intera traccia dello stack.

Per visualizzare tracce dello stack complete e informazioni di debug, imposta la variabile di ambiente ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Quando abilitato, l'SDK registra i dettagli completi dell'eccezione (utilizzando il modulo logging di Python, la console in TypeScript o il logger di Ruby), inclusa la traccia dello stack completa quando uno strumento non riesce.

Intercettazione degli errori degli strumenti

Per impostazione predefinita, gli errori degli strumenti vengono passati a Claude, che può quindi rispondere in modo appropriato. Tuttavia, potresti voler rilevare gli errori e gestirli diversamente, ad esempio per interrompere l'esecuzione in anticipo o implementare la gestione degli errori personalizzata.

Utilizza il metodo di risposta dello strumento per intercettare i risultati dello strumento e verificare la presenza di errori prima che vengano inviati a Claude:

Modifica dei risultati degli strumenti

Puoi modificare i risultati degli strumenti prima che vengano inviati a Claude. Questo è utile per aggiungere metadati come cache_control per abilitare il caching dei prompt sui risultati degli strumenti, o per trasformare l'output dello strumento.

Utilizza il metodo di risposta dello strumento per ottenere il risultato dello strumento, modificarlo, quindi aggiungere la tua versione modificata ai messaggi:

Streaming

Abilita lo streaming per ricevere gli eventi man mano che arrivano. Ogni iterazione produce un oggetto stream che puoi iterare per gli eventi.

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 campo tool_choice come segue:

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

Quando si lavora con il parametro tool_choice, abbiamo quattro opzioni possibili:

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

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. 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.

I nostri test hanno dimostrato che questo non dovrebbe ridurre le prestazioni. Se desideri che il modello fornisca contesto in linguaggio naturale o spiegazioni mentre richiedi comunque che il modello utilizzi uno strumento specifico, puoi utilizzare {"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 usare gli strumenti ogni volta che desideri che il modello restituisca un output JSON che segua uno schema fornito. Ad esempio, potresti usare uno strumento record_summary con uno schema particolare. Vedi Utilizzo degli strumenti con Claude per un esempio di lavoro completo.

Risposte del modello con gli strumenti

Quando si utilizzano gli strumenti, Claude spesso commenterà quello che sta facendo o risponderà naturalmente all'utente prima di invocare gli strumenti.

Ad esempio, dato il prompt "Qual è il meteo a San Francisco in questo momento e che ora è lì?", Claude potrebbe rispondere con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ti aiuterò a controllare il meteo attuale e l'ora a San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Questo stile di risposta naturale aiuta gli utenti a capire cosa sta facendo Claude e crea un'interazione più conversazionale. Puoi guidare lo stile e il contenuto di queste risposte attraverso i tuoi prompt di sistema e fornendo <examples> nei tuoi prompt.

È importante notare che Claude può usare 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.

Utilizzo parallelo degli strumenti

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

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

Massimizzare l'utilizzo parallelo degli strumenti

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

Gestione dei blocchi di contenuto tool use e tool result

La risposta di Claude differisce a seconda che usi uno strumento client o server.

Gestione dei risultati degli 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 univoco per questo particolare blocco tool_use. Questo verrà utilizzato per abbinare i risultati degli strumenti in seguito.
• name: Il nome dello strumento utilizzato.
• input: Un oggetto contenente l'input passato allo strumento, conforme a input_schema dello strumento.

Quando ricevi una risposta tool use 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 di 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 tool use per cui questo è un risultato.
   • content: Il risultato dello strumento, come una stringa (ad esempio, ), un elenco di blocchi di contenuto annidati (ad esempio, ), o un elenco di blocchi di documento (ad esempio, ). Questi blocchi di contenuto possono usare i tipi , o .

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

Dopo aver ricevuto il risultato dello strumento, Claude utilizzerà queste informazioni per continuare a generare una risposta al prompt utente originale.

Gestione dei risultati degli strumenti server

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

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 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:

Quando gestisci pause_turn:

• Continua la conversazione: Passa la risposta in pausa così com'è in una richiesta successiva per consentire 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

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

Questo è corretto:

Se ricevi un errore come "tool_use ids were found without tool_result blocks immediately after", controlla che i tuoi risultati degli strumenti siano formattati correttamente.