Come implementare l'uso degli strumenti

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

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.

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

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

Utilizzo di base

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 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 utilizzare gli strumenti ogni volta che desideri che il modello restituisca un output JSON che segua uno schema fornito. Ad esempio, potresti utilizzare uno strumento record_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:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in 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ò 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=true quando il tipo di tool_choice è auto, che garantisce che Claude utilizzi al massimo uno strumento
• Impostazione di disable_parallel_tool_use=true quando il tipo di tool_choice è any o tool, che garantisce che Claude utilizzi esattamente uno strumento

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:

Gestione dei blocchi di contenuto tool use e tool result

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

Gestione dei 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 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 a input_schema dello strumento.

Quando ricevi una risposta di 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 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 tipi text, image o document.
   • is_error (facoltativo): Impostato su true se l'esecuzione dello strumento ha causato un errore.

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Text after tool_result
]}

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

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.

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.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

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:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Send the continuation request
    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 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 strumenti con Claude: