Claude Platform Docs
MessagesTools

Tool-Aufrufe verarbeiten

tool_use-Blöcke parsen, tool_result-Antworten formatieren und Fehler mit is_error behandeln.

Wenn Claudes Antwort tool_use-Blöcke enthält, führt dein Code jedes Tool aus und sendet tool_result-Blöcke zurück, einschließlich etwaiger Fehler. Schreibe diesen Code selbst, wenn du individuelle Kontrolle über die Tool-Ausführung benötigst. Andernfalls verwende den Tool Runner des SDK, der die Tools ausführt und die Ergebnisse für dich sendet.

Claudes Antwort unterscheidet sich je nachdem, ob ein Client- oder Server-Tool verwendet wird.

Ergebnisse von Client-Tools verarbeiten

Die Antwort hat einen stop_reason von tool_use und einen oder mehrere tool_use-Inhaltsblöcke, die Folgendes enthalten:

  • id: Eine eindeutige Kennung für diesen bestimmten Tool-Use-Block. Diese wird später verwendet, um die Tool-Ergebnisse zuzuordnen.
  • name: Der Name des verwendeten Tools.
  • input: Ein Objekt mit der Eingabe, die an das Tool übergeben wird, entsprechend dem input_schema des Tools.

Ein tool_use-Block für ein Mitglied des Toolsets Computer Use oder Browser Use trägt zusätzlich ein Feld toolset_name ("computer" oder "browser"). Sein name ist das Mitglieds-Tool, das Claude aufruft, etwa screenshot oder navigate; verteile diese Blöcke daher anhand beider Felder.

Wenn du eine Tool-Nutzungs-Antwort für ein Client-Tool erhältst, folge diesen Schritten:

  1. Führe für jeden tool_use-Block das Tool aus, das der Block benennt, und übergib dabei dessen input.
  2. Behalte in einer neuen Anfrage die früheren Nachrichten bei und füge den content der Antwort unverändert als assistant-Nachricht hinzu.
  3. Füge eine user-Nachricht mit einem tool_result-Block für jeden tool_use-Block in diesem Inhalt hinzu, auch wenn das Tool fehlgeschlagen ist.
  4. Sende die Anfrage mit denselben tools wie die erste Anfrage. Claude verwendet die Tool-Ergebnisse, um seine Antwort fortzusetzen.
  5. Wenn der stop_reason der nächsten Antwort ebenfalls tool_use ist, wiederhole diese Schritte. Für andere Werte siehe die Kurzreferenz zu Stop-Gründen.

Diese Schritte als vollständige Programme findest du unter Tutorial: Einen Tool-nutzenden Agenten bauen.

Bei jedem tool_result-Block ist type auf tool_result gesetzt, dazu kommen diese Felder:

  • tool_use_id: Die id des tool_use-Blocks, auf den dieses Ergebnis antwortet.
  • content (optional): Das Ergebnis des Tools als String oder als Liste von Inhaltsblöcken. Diese Inhaltsblöcke können die Typen text, image, document oder search_result verwenden.
  • is_error (optional): Auf true setzen, wenn das Tool fehlgeschlagen ist oder der Aufruf ungültig war.

Ein erfolgreiches Tool-Ergebnis sieht zum Beispiel so aus:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Ein tool_result, das auf einen Mitgliedsblock von Computer Use oder Browser Use antwortet, muss außerdem denselben toolset_name-Wert wie der tool_use-Block zurückgeben; ein Mitgliedsergebnis, das ihn weglässt, wird abgelehnt. Sein content ist zudem enger gefasst: Ein Mitgliedsergebnis darf nur text- und image-Blöcke enthalten, und ein Browser-Use-Ergebnis darf einen browser_state-Block hinzufügen (die Mitglieder zur Tab-Verwaltung geben nur diesen Block zurück).

Ergebnisse von Server-Tools verarbeiten

Claude führt das Tool intern aus und integriert die Ergebnisse direkt in seine Antwort, ohne dass eine zusätzliche Benutzerinteraktion erforderlich ist.

Fehler mit is_error behandeln

Wenn ein Client-Tool fehlschlägt oder ein Aufruf ungültig ist, sende einen tool_result-Block, bei dem is_error auf true gesetzt ist. Claude ruft das Tool dann möglicherweise mit einem neuen tool_use-Block erneut auf; begrenze daher, wie viele Wiederholungsversuche deine Schleife zulässt.

Nächste Schritte

Verarbeite Antworten, in denen Claude mehrere Tools in einem einzigen Turn aufruft.

Lass das SDK die tool_use-Schleife, die Ergebnisformatierung und Wiederholungsversuche für dich verwalten.

Schreibe Schemas und Beschreibungen, die Claude zum richtigen Tool lenken.

War diese Seite hilfreich?