Utilizzo parallelo degli strumenti

Uso parallelo degli strumenti

Questa pagina copre le chiamate parallele degli strumenti: quando Claude chiama più strumenti in un turno, come formattare la cronologia dei messaggi affinché il parallelismo continui a funzionare e come disabilitarlo. Per il flusso a singola chiamata, vedi Gestire le chiamate 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

Esempio pratico

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 uno script completo e eseguibile per testare e verificare che le chiamate parallele degli strumenti funzionino correttamente:

# 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-opus-4-7", 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-opus-4-7", 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'utilizzo 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 le chiamate parallele degli strumenti in modo efficace.

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:

Risoluzione dei problemi

Se Claude non sta effettuando le chiamate parallele degli strumenti quando previsto, controlla questi problemi comuni:

1. Formattazione non corretta dei risultati degli strumenti

Il problema più comune è formattare in modo non corretto i risultati degli strumenti nella cronologia della conversazione. Questo "insegna" a Claude di evitare le chiamate parallele.

Specificamente per l'utilizzo parallelo degli strumenti:

❌ Sbagliato: Inviare messaggi utente separati per ogni risultato dello strumento
✅ Corretto: Tutti i risultati degli strumenti 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 Gestire le chiamate degli strumenti per altre regole di formattazione.

2. Prompt debole

Il prompt predefinito potrebbe non essere sufficiente. Usa il prompt di sistema più forte dalla sezione Massimizzare l'utilizzo parallelo degli strumenti sopra.

3. Misurazione dell'utilizzo parallelo degli strumenti

Per 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) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

Passaggi successivi

Per il flusso a singola chiamata dello strumento e le regole di formattazione di tool_result, vedi Gestire le chiamate degli strumenti.
Per l'astrazione dell'SDK che gestisce l'esecuzione parallela automaticamente, vedi Tool Runner.
Per il flusso di lavoro completo dell'utilizzo degli strumenti, vedi Definire gli strumenti.

Esempio pratico

Massimizzare l'utilizzo parallelo degli strumenti

Prompt di sistema per l'utilizzo parallelo degli strumenti

Prompt dei messaggi dell'utente

Risoluzione dei problemi

Passaggi successivi