Parallele Tool-Nutzung

Standardmäßig kann Claude in einer einzigen Antwort mehrere Tools aufrufen. Diese Seite behandelt, wie du diese Aufrufe ausführst, wie du den Nachrichtenverlauf formatierst, damit die Parallelität weiterhin funktioniert, und wie du die parallele „tool use“ (Tool-Nutzung) deaktivierst, wenn du das brauchst. Für den Ablauf mit einem einzelnen Aufruf siehe Tool-Aufrufe verarbeiten.

Ausführungssemantik

Wenn Claude Tools aufruft, hat die Antwort einen stop_reason von tool_use und kann mehrere tool_use-Blöcke in einem einzigen Assistant-Turn enthalten. Wie du diese Aufrufe ausführst, ist deine Entscheidung. Die API schreibt keine Ausführungsreihenfolge vor: Du kannst die Aufrufe nebenläufig ausführen (Promise.all, asyncio.gather), sequenziell in der Reihenfolge, in der sie erscheinen, oder in jeder Kombination, die zu deinen Tools passt.

Wähle die Strategie danach, was deine Tools tun. Unabhängige, rein lesende Operationen lassen sich in der Regel sicher parallel ausführen, um die Latenz zu senken. Tools mit Seiteneffekten, gemeinsamem Zustand oder Anforderungen an die Reihenfolge führst du möglicherweise besser sequenziell aus.

Welche Strategie du auch verwendest: Gib für jeden tool_use-Block genau ein tool_result zurück, alle zusammen in der nächsten User-Nachricht. Ordne jedes Ergebnis über tool_use_id seinem Aufruf zu und platziere jeden tool_result-Block vor jeglichem Textinhalt in dieser Nachricht. Die vollständigen Formatierungsregeln findest du unter Tool-Aufrufe verarbeiten. Wenn du dich entscheidest, einen bestimmten Aufruf nicht auszuführen (zum Beispiel, weil du den Batch sequenziell ausgeführt hast und ein früherer Aufruf fehlgeschlagen ist), gib trotzdem ein tool_result dafür zurück, mit is_error: true und einer kurzen Erklärung.

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

Das Computer-Use-Tool und das Browser-Use-Tool sind strenger. Wenn Claude mehrere ihrer zugehörigen Tool-Aufrufe in einem Turn zurückgibt (eine Batch-Aktion), führe sie sequenziell in der Reihenfolge aus, in der sie erscheinen, und stoppe beim ersten Fehler; jedes Tool definiert den genauen Text, den du für die übersprungenen Aufrufe zurückgeben musst.

Parallele Tool-Aufrufe testen

Das folgende Skript sendet eine Anfrage, die parallele Tool-Aufrufe auslösen sollte, überprüft, ob die Antwort sie enthält, und formatiert die Tool-Ergebnisse so, dass die Parallelität weiterhin funktioniert. Führe es mit gesetztem ANTHROPIC_API_KEY in deiner Umgebung aus:

client = Anthropic()

# Tools definieren
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"],
        },
    },
]

# Konversation mit parallelen Tool-Aufrufen testen
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Erste Anfrage senden
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)

# Auf parallele Tool-Aufrufe prüfen
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")

# Tool-Ausführung simulieren und Ergebnisse korrekt formatieren
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}
    )

# Konversation mit Tool-Ergebnissen fortsetzen
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Finale Antwort abrufen
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}")

# Formatierung überprüfen
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")

Die Zusammenfassungszeilen am Ende wiederholen die beiden Formatierungsregeln, die die Parallelität am Laufen halten: Alle Tool-Ergebnisse werden in einer einzigen User-Nachricht zurückgegeben, und in dieser Nachricht erscheint kein Textinhalt vor den Tool-Ergebnissen.

Parallele Tool-Nutzung maximieren

Claude 4 und neuere Modelle führen standardmäßig parallele Tool-Aufrufe aus, wenn eine Anfrage von mehreren Tools profitiert. Bei allen Modellen kannst du die Wahrscheinlichkeit paralleler Tool-Aufrufe durch gezieltes Prompting erhöhen:

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

Parallele Tool-Nutzung deaktivieren

Parallele Tool-Nutzung ist standardmäßig aktiviert. Um sie auszuschalten, setze disable_parallel_tool_use: true innerhalb des tool_choice-Objekts. Es handelt sich nicht um einen Anfrageparameter auf oberster Ebene. Die Wirkung hängt vom tool_choice-Typ ab.

Höchstens ein Tool-Aufruf

Wenn der tool_choice-Typ auto ist (der Standard), bedeutet das Setzen von disable_parallel_tool_use: true, dass Claude höchstens ein Tool pro Antwort aufruft. Claude kann weiterhin in reinem Text antworten, ohne ein Tool aufzurufen. Die hervorgehobenen Zeilen sind die einzige Änderung gegenüber einer Standardanfrage mit Tool-Nutzung:

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)

Genau ein Tool-Aufruf

Wenn der tool_choice-Typ any oder tool ist, bedeutet das Setzen von disable_parallel_tool_use: true, dass Claude genau ein Tool aufruft. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 und Claude Mythos 5.1 unterstützen diese tool_choice-Typen nicht (siehe Tool-Nutzung erzwingen). Das folgende Beispiel verwendet any. Dasselbe Feld funktioniert auch mit 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)

Fehlerbehebung

Wenn Claude nicht wie erwartet parallele Tool-Aufrufe ausführt, prüfe diese häufigen Probleme:

1. Falsche Formatierung der Tool-Ergebnisse

Das häufigste Problem ist eine falsche Formatierung der Tool-Ergebnisse im Gesprächsverlauf. Das „lehrt“ Claude, parallele Aufrufe zu vermeiden.

Speziell für parallele Tool-Nutzung:

• Falsch: eine separate User-Nachricht für jedes Tool-Ergebnis
• Richtig: alle Tool-Ergebnisse zusammen in einer einzigen User-Nachricht

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

Weitere Formatierungsregeln findest du unter Tool-Aufrufe verarbeiten.

2. Schwaches Prompting

Das Standard-Prompting reicht möglicherweise nicht aus. Verwende den stärkeren System-Prompt aus Parallele Tool-Nutzung maximieren.

3. Parallele Tool-Nutzung messen

Um zu überprüfen, ob parallele Tool-Aufrufe funktionieren:

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}")
# Sollte > 1,0 sein, wenn parallele Aufrufe funktionieren

4. Aufrufe in einem Batch scheinen voneinander abzuhängen

Die Ausführungsreihenfolge ist deine Wahl. Wenn deine Tools Abhängigkeiten in der Reihenfolge haben, ist es eine gültige Strategie, den Batch sequenziell auszuführen und beim ersten Fehler zu stoppen (und die vorgeschriebene für die Tools Computer Use und Browser Use): Gib is_error: true für jeden Aufruf zurück, den du nicht ausgeführt hast. Wenn du parallel ausführst und ein Aufruf fehlschlägt, weil seine Voraussetzung noch nicht abgeschlossen war, gib is_error: true mit der natürlichen Fehlermeldung zurück. Claude wird den Aufruf im nächsten Turn erneut ausgeben. Um zu verringern, dass abhängige Aufrufe gemeinsam erscheinen, füge Folgendes zu deinem System-Prompt hinzu: „Only batch tool calls that are independent of each other.“

Nächste Schritte