Tool Runner (SDK)

Tool Runner verwaltet die agentengesteuerte Schleife, Fehlerbehandlung und Typsicherheit, damit Sie das nicht tun müssen. Verwenden Sie die manuelle Schleife nur, wenn Sie eine Genehmigung durch einen Menschen, benutzerdefinierte Protokollierung oder bedingte Ausführung benötigen. Verfügbar in Python-, TypeScript- und Ruby-SDKs.

Der Tool Runner bietet eine sofort einsatzbereite Lösung für die Ausführung von Tools mit Claude. Anstatt Tool-Aufrufe, Tool-Ergebnisse und Gesprächsverwaltung manuell zu handhaben, führt der Tool Runner automatisch folgende Aufgaben aus:

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

Verwenden Sie den Tool Runner für die meisten Tool-Use-Implementierungen.

Grundlegende Verwendung

Definieren Sie Tools mit den SDK-Helfern und verwenden Sie dann den Tool Runner, um sie auszuführen.

Die Tool-Funktion muss einen Content-Block oder ein Content-Block-Array zurückgeben, einschließlich Text-, Bild- oder Dokument-Blöcke. Dies ermöglicht es Tools, umfangreiche, multimodale Antworten zurückzugeben. Zurückgegebene Strings werden in einen Text-Content-Block konvertiert. Wenn Sie ein strukturiertes JSON-Objekt an Claude zurückgeben möchten, codieren Sie es vor der Rückgabe als JSON-String. Zahlen, Boolesche Werte oder andere nicht-String-Primitive müssen ebenfalls in Strings konvertiert werden.

Iteration über den Tool Runner

Der Tool Runner ist ein iterierbares Objekt, das Nachrichten von Claude liefert. Dies wird oft als "Tool-Call-Schleife" bezeichnet. Bei jeder Iteration prüft der Runner, ob Claude einen Tool-Use angefordert hat. Wenn ja, ruft er das Tool auf und sendet das Ergebnis automatisch an Claude zurück, dann liefert er die nächste Nachricht von Claude, um Ihre Schleife fortzusetzen.

Sie können die Schleife bei jeder Iteration mit einer break-Anweisung beenden. Der Runner wird in einer Schleife ausgeführt, bis Claude eine Nachricht ohne Tool-Use zurückgibt.

Wenn Sie keine Zwischennachrichten benötigen, können Sie die endgültige Nachricht direkt abrufen:

Erweiterte Verwendung

Innerhalb der Schleife können Sie die nächste Anfrage des Tool Runners an die Messages API vollständig anpassen. Der Runner hängt Tool-Ergebnisse automatisch an den Nachrichtenverlauf an, daher müssen Sie diese nicht manuell verwalten. Sie können das Tool-Ergebnis optional zur Protokollierung oder zum Debuggen inspizieren und die Request-Parameter vor dem nächsten API-Aufruf ändern.

Debuggen der Tool-Ausführung

Wenn ein Tool eine Ausnahme wirft, fängt der Tool Runner sie ab und gibt den Fehler an Claude als Tool-Ergebnis mit is_error: true zurück. Standardmäßig wird nur die Fehlermeldung einbezogen, nicht die vollständige Stack-Trace.

Um vollständige Stack-Traces und Debug-Informationen anzuzeigen, setzen Sie die Umgebungsvariable ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Wenn aktiviert, protokolliert das SDK vollständige Ausnahmeinformationen (mit Pythons logging-Modul, der Konsole in TypeScript oder Rubys Logger), einschließlich der vollständigen Stack-Trace, wenn ein Tool fehlschlägt.

Abfangen von Tool-Fehlern

Standardmäßig werden Tool-Fehler an Claude zurückgegeben, der dann angemessen reagieren kann. Möglicherweise möchten Sie jedoch Fehler erkennen und anders handhaben, z. B. um die Ausführung früh zu beenden oder benutzerdefinierte Fehlerbehandlung zu implementieren.

Verwenden Sie die Tool-Response-Methode, um Tool-Ergebnisse abzufangen und auf Fehler zu prüfen, bevor sie an Claude gesendet werden:

Ändern von Tool-Ergebnissen

Sie können Tool-Ergebnisse ändern, bevor sie an Claude zurückgesendet werden. Dies ist nützlich, um Metadaten wie cache_control hinzuzufügen, um Prompt-Caching auf Tool-Ergebnisse zu aktivieren, oder um die Tool-Ausgabe zu transformieren.

Verwenden Sie die Tool-Response-Methode, um das Tool-Ergebnis zu erhalten, ändern Sie es dann, bevor der Runner fortfährt. Ob Sie das geänderte Ergebnis explizit anhängen oder es an Ort und Stelle mutieren, hängt vom SDK ab; siehe die Code-Kommentare in jedem Tab.

Streaming

Aktivieren Sie Streaming, um Ereignisse zu empfangen, sobald sie ankommen. Jede Iteration liefert ein Stream-Objekt, das Sie für Ereignisse iterieren können.

Nächste Schritte

• Für manuelle Kontrolle über die Tool-Call-Schleife siehe Tool-Aufrufe handhaben.
• Für die Ausführung mehrerer Tools gleichzeitig siehe Parallele Tool-Nutzung.
• Für den vollständigen Tool-Use-Workflow siehe Tools definieren.