Uso parallelo degli strumenti

Per impostazione predefinita, Claude può chiamare più strumenti in una singola risposta. Questa pagina spiega come eseguire tali chiamate, come formattare la cronologia dei messaggi in modo che il parallelismo continui a funzionare e come disabilitare il "parallel tool use" (uso parallelo degli strumenti) quando necessario. Per il flusso a chiamata singola, consulta Gestire le chiamate agli strumenti.

Semantica di esecuzione

Quando Claude chiama degli strumenti, la risposta ha uno stop_reason pari a tool_use e può contenere diversi blocchi tool_use in un singolo turno dell'assistente. Come eseguire tali chiamate è una tua decisione. L'API non prescrive un ordine di esecuzione: puoi eseguire le chiamate in modo concorrente (Promise.all, asyncio.gather), in sequenza nell'ordine in cui appaiono, o in qualsiasi combinazione adatta ai tuoi strumenti.

Scegli la strategia in base a ciò che fanno i tuoi strumenti. Le operazioni indipendenti e di sola lettura sono di solito sicure da eseguire in parallelo per una "latency" (latenza) inferiore. Gli strumenti con effetti collaterali, stato condiviso o requisiti di ordinamento potrebbero essere eseguiti meglio in sequenza.

Qualunque strategia tu usi, restituisci un tool_result per ogni blocco tool_use, tutti insieme nel messaggio utente successivo. Associa ogni risultato alla sua chiamata tramite tool_use_id e inserisci ogni blocco tool_result prima di qualsiasi contenuto testuale in quel messaggio. Consulta Gestire le chiamate agli strumenti per le regole di formattazione complete. Se scegli di non eseguire una particolare chiamata (ad esempio, perché hai eseguito il batch in sequenza e una chiamata precedente è fallita), restituisci comunque un tool_result per essa con is_error: true e una breve spiegazione.

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "Not executed: the preceding write_file call failed."
}

Lo strumento computer use e lo strumento browser use sono più rigorosi. Quando Claude restituisce diverse chiamate ai loro strumenti membri in un unico turno (un'azione batch), eseguile in sequenza nell'ordine in cui appaiono e fermati al primo errore; ogni strumento definisce il testo esatto da restituire per le chiamate che salti.

Testare le chiamate parallele agli strumenti

Lo script seguente invia una richiesta che dovrebbe attivare chiamate parallele agli strumenti, verifica che la risposta le contenga e formatta i risultati degli strumenti in modo che il parallelismo continui a funzionare. Eseguilo con ANTHROPIC_API_KEY impostata nel tuo ambiente:

client = Anthropic()

# Definisci gli strumenti
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"],
        },
    },
]

# Testa la conversazione con chiamate parallele agli strumenti
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Esegui la richiesta iniziale
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)

# Verifica la presenza di chiamate parallele agli strumenti
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")

# Simula l'esecuzione degli strumenti e formatta correttamente i risultati
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}
    )

# Continua la conversazione con i risultati degli strumenti
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Ottieni la risposta finale
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)

final_text = next(
    block.text for block in final_response.content if block.type == "text"
)
print(f"\nClaude's response:\n{final_text}")

# Verifica la formattazione
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")

Le righe di riepilogo alla fine ribadiscono le due regole di formattazione che mantengono funzionante il parallelismo: ogni risultato degli strumenti viene restituito in un singolo messaggio utente e nessun contenuto testuale appare prima dei risultati degli strumenti in quel messaggio.

Massimizzare l'uso parallelo degli strumenti

I modelli Claude 4 e successivi effettuano chiamate parallele agli strumenti per impostazione predefinita quando una richiesta trae vantaggio da più strumenti. Per tutti i modelli, puoi aumentare la probabilità di chiamate parallele agli strumenti con un prompting mirato:

For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

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

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

Disabilitare l'uso parallelo degli strumenti

L'uso parallelo degli strumenti è attivo per impostazione predefinita. Per disattivarlo, imposta disable_parallel_tool_use: true all'interno dell'oggetto tool_choice. Non è un parametro di richiesta di primo livello. L'effetto dipende dal tipo di tool_choice.

Al massimo una chiamata a uno strumento

Quando il tipo di tool_choice è auto (il valore predefinito), impostare disable_parallel_tool_use: true significa che Claude chiama al massimo uno strumento per risposta. Claude può comunque rispondere in testo semplice senza chiamare alcuno strumento. Le righe evidenziate sono l'unica modifica rispetto a una richiesta standard di uso degli strumenti:

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    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"],
            },
        }
    ],
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

Esattamente una chiamata a uno strumento

Quando il tipo di tool_choice è any o tool, impostare disable_parallel_tool_use: true significa che Claude chiama esattamente uno strumento. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 non supportano questi tipi di tool_choice (consulta Forzare l'uso degli strumenti). L'esempio seguente usa any. Lo stesso campo funziona con tool:

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    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"],
            },
        }
    ],
    tool_choice={"type": "any", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

Risoluzione dei problemi

Se Claude non effettua chiamate parallele agli strumenti quando previsto, controlla questi problemi comuni:

1. Formattazione errata dei risultati degli strumenti

Il problema più comune è la formattazione errata dei risultati degli strumenti nella cronologia della conversazione. Questo "insegna" a Claude a evitare le chiamate parallele.

In particolare per l'uso parallelo degli strumenti:

• Sbagliato: un messaggio utente separato per ogni risultato degli strumenti
• Corretto: tutti i risultati degli strumenti insieme in un singolo messaggio utente

// Wrong: separate user messages reduce 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
]

// Correct: one user message with all results maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]

Consulta Gestire le chiamate agli strumenti per le altre regole di formattazione.

2. Prompting debole

Il prompting predefinito potrebbe non essere sufficiente. Usa il prompt di sistema più forte da Massimizzare l'uso parallelo degli strumenti.

3. Misurare l'uso parallelo degli strumenti

Per verificare che le chiamate parallele agli strumenti funzionino:

messages = []  # Message objects returned by client.messages.create across your run

tool_call_messages = [
    msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
    len([block for block in msg.content if block.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = (
    total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Dovrebbe essere > 1,0 se le chiamate parallele funzionano

4. Le chiamate in un batch sembrano dipendere l'una dall'altra

L'ordine di esecuzione è una tua scelta. Se i tuoi strumenti hanno dipendenze di ordinamento, eseguire il batch in sequenza e fermarsi al primo errore è una strategia valida (e quella richiesta per gli strumenti computer use e browser use): restituisci is_error: true per ogni chiamata che non hai eseguito. Se esegui in parallelo e una chiamata fallisce perché il suo prerequisito non era stato completato, restituisci is_error: true con il messaggio di errore naturale. Claude riemetterà la chiamata al turno successivo. Per ridurre la comparsa congiunta di chiamate dipendenti, aggiungi questo al tuo prompt di sistema: "Only batch tool calls that are independent of each other."

Passaggi successivi