Tool Runner (SDK)

Der Tool Runner übernimmt die agentische Schleife, die Fehlerbehandlung und die Typsicherheit, sodass du dich nicht darum kümmern musst. Wenn du Human-in-the-Loop-Freigaben, benutzerdefiniertes Logging oder bedingte Ausführung benötigst, verwende stattdessen die manuelle Schleife.

Anstatt Tool-Aufrufe, Tool-Ergebnisse und die Konversationsverwaltung manuell zu handhaben, erledigt der Tool Runner automatisch Folgendes:

• Führt Tools aus, wenn Claude sie aufruft
• Handhabt den Request/Response-Zyklus
• Verwaltet den Konversationszustand
• Bietet Typsicherheit und Validierung



Grundlegende Verwendung

Definiere Tools mit den SDK-Helpern und verwende dann den Tool Runner, um sie auszuführen.

Abhängig von der Tool-Signatur des SDK gibt ein Tool sein Ergebnis als String oder als Content-Blöcke (Text-, Bild- oder Dokument-Blöcke) zurück, sodass ein Tool multimodale Ergebnisse zurückgeben kann. Ein zurückgegebener String wird zu einem einzelnen Text-Content-Block. Um strukturierte Daten wie ein JSON-Objekt oder eine Zahl zurückzugeben, kodiere sie zuerst als String.



Über den Tool Runner iterieren

Der Tool Runner ist ein Iterable, das Nachrichten von Claude liefert. Bei jeder Iteration prüft der Runner, ob Claude eine Tool-Nutzung angefordert hat. Falls ja, führt er das Tool aus, sendet das Ergebnis automatisch an Claude zurück und liefert dann die nächste Nachricht von Claude, um deine Schleife fortzusetzen.

Du kannst die Schleife bei jeder Iteration mit einer break-Anweisung beenden. Der Runner läuft in einer Schleife, bis Claude eine Nachricht ohne Tool-Nutzung zurückgibt oder bis max_iterations erreicht ist, falls du es gesetzt hast.

Wenn du keine Zwischennachrichten benötigst, kannst du die finale Nachricht direkt abrufen:



Erweiterte Verwendung

Innerhalb der Schleife kannst du jede Antwortnachricht lesen und den Zustand des Runners vor dem nächsten API-Aufruf ändern. Jede Iteration folgt diesem Lebenszyklus:

1. Der Runner sendet eine Anfrage an die Messages API mit seinem aktuellen Zustand.
2. Der Runner liefert die Antwortnachricht an deinen Schleifenkörper.
3. Dein Schleifenkörper wird ausgeführt. Du kannst die Nachricht lesen und optional den Zustand des Runners ändern.
4. Wenn dein Schleifenkörper zurückkehrt, prüft der Runner, ob du seinen Nachrichtenverlauf geändert hast.
   • Wenn du den Nachrichtenverlauf nicht geändert hast: Der Runner hängt die Assistant-Nachricht an seinen Zustand an. Wenn die Nachricht Tool-Aufrufe enthält, führt der Runner sie aus und hängt die Ergebnisse an. Wenn es keine Tool-Aufrufe gibt, wird die Schleife beendet.
   • Wenn du den Nachrichtenverlauf geändert hast: Der Runner überspringt sein automatisches Anhängen und verwendet deinen Zustand unverändert. Siehe Nachrichtenverlauf übernehmen.



Nachrichtenverlauf übernehmen

Standardmäßig verwaltet der Runner den Konversationszustand für dich: Nach jedem Turn hängt er die Assistant-Nachricht und alle Tool-Ergebnisse an seinen eigenen Nachrichtenverlauf an. Du übernimmst den Nachrichtenverlauf, wenn du einen Turn wiederholen möchtest (die Antwort verwerfen und erneut senden), eine Folgenachricht einfügen oder das Tool-Ergebnis selbst erstellen möchtest.

Du übernimmst, indem du die Nachrichten des Runners innerhalb des Schleifenkörpers änderst. Die genaue Methode hängt vom SDK ab. Siehe die folgenden sprachspezifischen Tabs.

Wenn du für eine Iteration übernimmst, hängt der Runner die Assistant-Nachricht oder Tool-Ergebnisse dieses Turns nicht an. Du bist dafür verantwortlich, die Konversation gültig zu halten: Hänge die Assistant-Nachricht und ein Tool-Ergebnis selbst an (wenn der Turn zählen soll), ändere den Zustand bedingt, damit die Schleife weiterhin beendet werden kann, wenn es keine Tool-Aufrufe gibt, und übergib max_iterations, um die Schleife zu begrenzen. Alle sieben SDKs unterstützen max_iterations.



Automatische Kontextverwaltung

Für langlaufende agentische Aufgaben unterstützen die Python-, TypeScript- und Ruby-Tool-Runner automatische Compaction (Kompaktierung), die Zusammenfassungen generiert, wenn die Token-Nutzung einen Schwellenwert überschreitet, sodass die Konversation über die Grenzen des Kontextfensters hinaus fortgesetzt werden kann. Alle drei SDKs haben diese clientseitige Option zugunsten des serverseitigen Context Editing als veraltet markiert, das in jedem SDK verfügbar ist. Die Go-, Java-, C#- und PHP-Tool-Runner enthalten keine clientseitige Compaction.



Debugging der Tool-Ausführung

Wenn ein Tool eine Exception wirft, fängt der Tool Runner sie ab und gibt den Fehler als Tool-Ergebnis mit is_error: true an Claude zurück. Das Tool-Ergebnis enthält die Nachricht der Exception (in Python ihren Typ und ihre Nachricht), nicht den vollständigen Stack-Trace.

Was das SDK loggt, ist sprachspezifisch. Das Python SDK loggt die vollständige Exception einschließlich ihres Stack-Traces über das Standard-logging-Modul, wenn ein Tool eine unbehandelte Exception auslöst. Die Python-, TypeScript- und Java-SDKs lesen die Umgebungsvariable ANTHROPIC_LOG, um das Logging des SDK zu aktivieren, das Request- und Response-Details enthält:

# Logge auf Info-Ebene
export ANTHROPIC_LOG=info

# Logge auf Debug-Ebene für ausführlichere Ausgabe
export ANTHROPIC_LOG=debug

Die Go-, Ruby-, C#- und PHP-SDKs lesen ANTHROPIC_LOG nicht. Außerhalb von Python loggt kein SDK ein fehlgeschlagenes Tool: Um zu sehen, warum ein Tool fehlgeschlagen ist, fange die Exception innerhalb der Tool-Funktion ab und logge sie, bevor du sie zurückgibst oder erneut wirfst.



Tool-Fehler abfangen

Standardmäßig werden Tool-Fehler an Claude zurückgegeben, der dann entsprechend reagieren kann. Du möchtest jedoch möglicherweise Fehler erkennen und anders behandeln, zum Beispiel um die Ausführung frühzeitig zu beenden oder eine benutzerdefinierte Fehlerbehandlung zu implementieren.

In den Python- und TypeScript-SDKs verwendest du die Tool-Response-Methode (generate_tool_call_response() in Python, generateToolResponse() in TypeScript), um Tool-Ergebnisse abzufangen und auf Fehler zu prüfen, bevor sie an Claude gesendet werden. Die anderen SDKs stellen diesen Hook nicht bereit. Ihre Tabs beschreiben die nächstbeste Alternative:



Tool-Ergebnisse ändern

Du kannst Tool-Ergebnisse ändern, bevor sie an Claude zurückgesendet werden. Dies ist nützlich, um Metadaten wie cache_control hinzuzufügen, um Prompt-Caching für Tool-Ergebnisse zu aktivieren, oder um die Tool-Ausgabe zu transformieren.

In den Python- und TypeScript-SDKs verwendest du die Tool-Response-Methode, um das Tool-Ergebnis zu erhalten, und änderst es dann, bevor der Runner fortfährt. Ob du das geänderte Ergebnis explizit anhängst oder es direkt mutierst, hängt vom SDK ab. Siehe die Code-Kommentare in jedem Tab.



Streaming

Aktiviere Streaming, um die Antwort jedes Turns inkrementell zu verarbeiten. Jede Iteration liefert ein Stream-Objekt, über das du für Events iterieren kannst.



Nächste Schritte