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 tools di primo livello 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à in grado di decidere quando e come utilizzarli. Mira ad almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni, ma considera l'utilizzo di 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 (beta) 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 definizione dello strumento con un array di oggetti di input di esempio. Ogni esempio deve essere valido secondo l'input_schema dello strumento:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature"
                    }
                },
                "required": ["location"]
            },
            "input_examples": [
                {
                    "location": "San Francisco, CA",
                    "unit": "fahrenheit"
                },
                {
                    "location": "Tokyo, Japan",
                    "unit": "celsius"
                },
                {
                    "location": "New York, NY"  # 'unit' is optional
                }
            ]
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
)

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 l'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 di 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.

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 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 Uso degli strumenti con Claude per un esempio di lavoro completo.

Risposte del modello con 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ò 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.

Utilizzo parallelo degli strumenti

Per impostazione predefinita, Claude può utilizzare 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 utilizzi al massimo uno strumento
• Impostando disable_parallel_tool_use=true quando il tipo di tool_choice è any o tool, il che garantisce che Claude utilizzi 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 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 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 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 stringa (ad es. "content": "15 gradi"), un elenco di blocchi di contenuto annidati (ad es. "content": [{"type": "text", "text": "15 gradi"}]), o un elenco di blocchi di documento (ad es. "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 gradi"}]). Questi blocchi di contenuto possono utilizzare i tipi text, image o document.
   • is_error (facoltativo): Impostare su true se l'esecuzione dello strumento ha generato un errore.

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

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "Cosa dovrei fare dopo?"}  // ✅ Testo dopo 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 tool use incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere il tool use completo.

# Verifica se la risposta è stata troncata durante l'utilizzo dello strumento
if response.stop_reason == "max_tokens":
    # Verifica se l'ultimo blocco di contenuto è un tool_use incompleto
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Invia la richiesta con max_tokens più alto
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Limite aumentato
            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()

# 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 calcolo quantistico nel 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Verifica se la risposta ha il motivo di arresto pause_turn
if response.stop_reason == "pause_turn":
    # Continua la conversazione con il contenuto messo in pausa
    messages = [
        {"role": "user", "content": "Cerca informazioni complete sui progressi del calcolo quantistico nel 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Invia 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 messa 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 vuoi 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: