Paralleles Tool-Calling: Latenz reduzieren

Die Demo in diesem Video wurde im September 2026 aufgezeichnet. Sie lief auf Claude Sonnet 5 (claude-sonnet-5). Bei neueren Modellen können die Ergebnisse abweichen.

Wenn Tool-Aufrufe nacheinander ausgeführt werden, muss dein Nutzer auf jeden einzelnen warten.

Wenn die Tools, die Claude benötigt, nicht voneinander abhängen, kann es alle in einer einzigen Antwort anfordern. Claude macht das standardmäßig, daher muss deine Schleife jeden Tool-Aufruf verarbeiten und für jeden ein Ergebnis zurücksenden.

Drei Tool-Aufrufe in einer Antwort

Parallele Tool-Nutzung bedeutet, dass eine Antwort mehrere tool_use-Blöcke enthält.

Meridian hat ein Python-Skript, das prüft, ob eine Baustelle bereit für den Außeneinsatz ist. Die Standortprüfung benötigt drei voneinander unabhängige Abfragen: den Projektstatus, das Wetter am Standort und den Status der Genehmigung.

Hier ist Claudes Antwort auf Meridians Standortprüfung, mit einem tool_use-Block für jedes gewünschte Tool.

{
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {"type": "tool_use", "id": "toolu_01", "name": "get_project_status",
     "input": {"job_number": "MEG-2026-0142"}},
    {"type": "tool_use", "id": "toolu_02", "name": "get_site_weather",
     "input": {"site": "Riverside"}},
    {"type": "tool_use", "id": "toolu_03", "name": "get_permit_state",
     "input": {"permit_id": "P-88213"}}
  ]
}

Der stop_reason der Antwort ist tool_use, und jeder Tool-Aufruf hat seine eigene id.

Führe jeden Tool-Aufruf aus

Eine Schleife, die für einen einzelnen Tool-Aufruf geschrieben wurde, liest nur den ersten tool_use-Block. Sie sendet ein Ergebnis zurück, zwei Tool-Aufrufe erhalten nie ihres, und die API weist die Anfrage ab. Erfasse daher jeden tool_use-Block in der Antwort.

calls = [b for b in resp.content if b.type == "tool_use"]

Führe diese Tool-Aufrufe als Nächstes gleichzeitig aus. Jede Abfrage verbringt die meiste Zeit mit Warten auf ein anderes System. Gib jeder einen eigenen Thread, dann überlappen sich die drei Wartezeiten, statt sich zu addieren.

with ThreadPoolExecutor() as pool:
    results = list(pool.map(run_tool, calls))

run_tool führt einen Tool-Aufruf aus und gibt dessen Ergebnis zurück, und die nächsten beiden Abschnitte bauen es auf.

Tool-Aufrufe gleichzeitig auszuführen ist in der Regel sicher, wenn sie nur Daten lesen und nicht voneinander abhängen, wie bei Meridians Abfragen. Wenn Tools Daten verändern oder in einer festgelegten Reihenfolge ablaufen müssen, ist es möglicherweise besser, sie nacheinander auszuführen.

Sende jedes Ergebnis in einer einzigen Nachricht zurück

Sobald die drei Tool-Aufrufe ausgeführt wurden, wartet Claude auf deren Ergebnisse. Jedes Ergebnis geht in einem tool_result-Block zurück, und dessen tool_use_id enthält die id des Tool-Aufrufs, den es beantwortet.

result = {"type": "tool_result", "tool_use_id": call.id}

Jeder tool_use-Block erhält ein tool_result, und alle kommen in die nächste Nutzernachricht.

messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": results})



Wenn deine Schleife stattdessen jedes Ergebnis in einer eigenen Nachricht sendet, liest sich die Konversation so, als hätte Claude jeweils nur ein Tool angefordert. Das ist ein häufiger Grund, warum Claude weniger parallele Tool-Aufrufe macht.

Gib ein Fehlerergebnis für einen fehlgeschlagenen Tool-Aufruf zurück

Drei Tool-Aufrufe gleichzeitig auszuführen bedeutet, dass einer fehlschlagen kann, während die anderen beiden erfolgreich sind. Wenn dein Code eine Exception auslöst und diese nicht abgefangen wird, stoppt deine Schleife, und die beiden guten Ergebnisse gehen mit ihr verloren.

Sende den Fehler daher als Ergebnis zurück. Es ist ein gewöhnliches tool_result mit der Fehlermeldung als content, plus is_error: true. Die Nachricht sollte angeben, was schiefgelaufen ist und was Claude als Nächstes versuchen sollte.

try:
    result["content"] = HANDLERS[call.name](**call.input)
except Exception as exc:
    result["content"] = f"{call.name} failed: {exc}"
    result["is_error"] = True

HANDLERS ist ein Dict, das Tool-Namen auf die Python-Funktionen abbildet, die die jeweilige Tool-Arbeit erledigen. Jede Funktion gibt einen String zurück, da der content eines tool_result ein String oder eine Liste von Content-Blöcken ist.

Füge die Schleife zusammen

Die obigen Snippets fügen sich in Meridians Schleife unten ein. Das Skript hat bereits client, tools, prompt und HANDLERS eingerichtet.

Wichtige Erkenntnisse

• Führe jeden Tool-Aufruf in einer Antwort aus, und führe sie gleichzeitig aus, wenn sie nicht voneinander abhängen.
• Sende für jeden Tool-Aufruf ein tool_result zurück, und packe sie alle in eine Nutzernachricht.
• Sende nicht jedes Ergebnis in einer eigenen Nachricht, da das die parallele Tool-Nutzung verringert.
• Sende einen Fehler als Ergebnis mit is_error: true zurück, damit ein fehlgeschlagener Tool-Aufruf die Schleife nicht stoppt.