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.
Se utilizzi Claude con l’uso degli strumenti e il pensiero esteso, consulta la nostra guida qui per ulteriori informazioni.

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:
ParametroDescrizione
nameIl nome dello strumento. Deve corrispondere all’espressione regolare ^[a-zA-Z0-9_-]{1,64}$.
descriptionUna descrizione dettagliata in testo semplice di cosa fa lo strumento, quando deve essere utilizzato e come si comporta.
input_schemaUn oggetto JSON Schema che definisce i parametri previsti per lo strumento.
JSON
{
  "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, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
Questo strumento, denominato 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 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.
JSON
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
JSON
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}
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.
Il tool runner è attualmente in beta ed è disponibile solo negli SDK Python e TypeScript.

Utilizzo di base

Utilizza il decoratore @beta_tool per definire gli strumenti e client.beta.messages.tool_runner() per eseguirli.
Se stai utilizzando il client asincrono, sostituisci @beta_tool con @beta_async_tool e definisci la funzione con async def.
import anthropic
import json
from anthropic import beta_tool

# Initialize client
client = anthropic.Anthropic()

# Define tools using the decorator
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    # In a full implementation, you'd call a weather API here
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

@beta_tool
def calculate_sum(a: int, b: int) -> str:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number
    """
    return str(a + b)

# Use the tool runner
with client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[
        {"role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?"}
    ]
) as runner:
    for message in runner:
        print(message.content[0].text)
La funzione decorata deve restituire un blocco di contenuto o un array di blocchi di contenuto, inclusi blocchi di testo, immagini o 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 altre primitive non stringa devono anche essere convertiti in stringhe.Il decoratore @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:
{
  "name": "calculate_sum",
  "description": "Adds two integers together.",
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "left": {
        "description": "The first integer to add.",
        "title": "Left",
        "type": "integer"
      },
      "right": {
        "description": "The second integer to add.",
        "title": "Right",
        "type": "integer"
      }
    },
    "required": ["left", "right"],
    "type": "object"
  }
}
Il tool runner dell’SDK è in beta. Il resto di questo documento copre l’implementazione manuale 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 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.
Quando si utilizza prompt caching, le modifiche al parametro 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.
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.
Quando si utilizza extended thinking 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 valore predefinito) e tool_choice: {"type": "none"} sono compatibili con il pensiero esteso.
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:
JSON
{
  "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
Più semplice con Tool runner: L’esempio seguente mostra la gestione manuale parallela degli strumenti. Per la maggior parte dei casi d’uso, tool runner gestisce automaticamente l’esecuzione parallela degli strumenti con molto meno codice.
Ecco un esempio completo che mostra come formattare correttamente le chiamate parallele degli strumenti nella cronologia dei messaggi:
import anthropic

client = anthropic.Anthropic()

# Define tools
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"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Initial request
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in SF and NYC, and what time is it there?"
        }
    ]
)

# Claude's response with parallel tool calls
print("Claude wants to use tools:", response.stop_reason == "tool_use")
print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

# Build the conversation with tool results
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contains multiple tool_use blocks
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Must match the ID from tool_use
                "content": "San Francisco: 68°F, partly cloudy"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, clear skies"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco time: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York time: 5:30 PM EST"
            }
        ]
    }
]

# Get final response
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)
Il messaggio dell’assistente con chiamate parallele degli strumenti avrebbe questo aspetto:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather and time for both San Francisco and New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}
Ecco uno script completo e eseguibile per testare e verificare che le chiamate parallele degli strumenti funzionino correttamente:
#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Claude API"""

import os
from anthropic import Anthropic

# Initialize client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Define tools
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"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"

    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continue conversation with tool results
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # All results in one message!
])

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")
Questo script dimostra:
  • 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)
Esegui questo script per testare la tua implementazione e assicurarti che Claude stia effettuando chiamate parallele degli strumenti in modo efficace.

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:
Per i modelli Claude 4 (Opus 4.1, Opus 4 e Sonnet 4), aggiungi questo al tuo prompt di sistema:
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
Per un uso parallelo degli strumenti ancora più forte (consigliato se il valore predefinito non è sufficiente), utilizza:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>
Puoi anche incoraggiare l’uso parallelo degli strumenti all’interno di messaggi utente specifici:
# Instead of:
"What's the weather in Paris? Also check London."

# Use:
"Check the weather in Paris and London simultaneously."

# Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."
Uso parallelo degli strumenti con Claude Sonnet 3.7Claude Sonnet 3.7 potrebbe essere meno propenso a effettuare chiamate parallele degli strumenti in una risposta, anche quando non hai impostato 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

Più semplice con Tool runner: La gestione manuale degli strumenti descritta in questa sezione è gestita automaticamente da tool runner. Utilizza questa sezione quando hai bisogno di un controllo personalizzato sull’esecuzione degli strumenti.
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.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}
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.
Requisiti di formattazione importanti:
  • 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.
Ad esempio, questo causerà un errore 400:
{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}
Questo è corretto:
{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Text after tool_result
]}
Se ricevi un errore come “tool_use ids were found without tool_result blocks immediately after”, controlla che i risultati dello strumento siano formattati correttamente.
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "The weather is"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}
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.
Differenze da altre APIA differenza delle API che separano l’uso dello strumento o utilizzano ruoli speciali come 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.
# 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

Gestione degli errori integrata: Tool runner fornisce gestione automatica degli errori per la maggior parte degli scenari comuni. Questa sezione copre la gestione manuale degli errori per casi d’uso avanzati.
Ci sono alcuni diversi tipi di errori che possono verificarsi quando si utilizzano strumenti con Claude:
Se lo strumento stesso genera un errore durante l’esecuzione (ad es. un errore di rete durante il recupero dei dati meteorologici), puoi restituire il messaggio di errore in content insieme a "is_error": true:
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}
Claude incorporerà quindi questo errore nella sua risposta all’utente, ad es. “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”
Se il tentativo di Claude di utilizzare uno strumento non è valido (ad es. parametri obbligatori mancanti), di solito significa che non c’era abbastanza informazione per Claude per utilizzare lo strumento correttamente. La tua migliore scommessa durante lo sviluppo è provare di nuovo la richiesta con valori 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:
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}
Se una richiesta di strumento non è valida o mancano parametri, Claude riproverà 2-3 volte con correzioni prima di scusarsi con l’utente.
Per impedire a Claude di riflettere sulla qualità dei risultati della ricerca con tag <search_quality_reflection>, aggiungi “Do not reflect on the quality of the returned search results in your response” al tuo prompt.
Quando gli strumenti server incontrano errori (ad es., problemi di rete con Web Search), Claude gestirà questi errori in modo trasparente e tenterà di fornire una risposta alternativa o una spiegazione all’utente. A differenza degli strumenti client, non è necessario gestire i risultati is_error per gli strumenti server.Per la ricerca web in particolare, i possibili codici di errore includono:
  • too_many_requests: Limite di velocità superato
  • invalid_input: Parametro di query di ricerca non valido
  • max_uses_exceeded: Massimo utilizzo dello strumento di ricerca web superato
  • query_too_long: La query supera la lunghezza massima
  • unavailable: Si è verificato un errore interno
Se Claude non sta effettuando chiamate parallele degli strumenti quando previsto, controlla questi problemi comuni:1. Formattazione non corretta dei risultati dello strumentoIl problema più comune è formattare in modo non corretto i risultati dello strumento nella cronologia della conversazione. Questo “insegna” a Claude di evitare le chiamate parallele.Specificamente per l’uso parallelo degli strumenti:
  • Sbagliato: Invio di messaggi utente separati per ogni risultato dello strumento
  • Corretto: Tutti i risultati dello strumento devono essere in un singolo messaggio utente
// ❌ This reduces parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// ✅ This maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]
Vedi i requisiti di formattazione generali sopra per altre regole di formattazione.2. Prompt deboleIl prompt predefinito potrebbe non essere sufficiente. Utilizza un linguaggio più forte:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations,
invoke all relevant tools simultaneously rather than sequentially.
Prioritize calling tools in parallel whenever possible.
</use_parallel_tool_calls>
3. Misurazione dell’utilizzo parallelo degli strumentiPer verificare che le chiamate parallele degli strumenti funzionino:
# Calculate average tools per tool-calling message
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working
4. Comportamento specifico del modello
  • 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