Tool-Aufrufe verarbeiten

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

Diese Seite behandelt den Lebenszyklus eines Tool-Aufrufs: das Lesen von tool_use-Blöcken aus Claudes Antwort, das Formatieren von tool_result-Blöcken in deiner Antwort und das Signalisieren von Fehlern. Für die SDK-Abstraktion, die dies automatisch übernimmt, siehe Tool Runner.

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.

Wenn du eine Tool-Use-Antwort für ein Client-Tool erhältst, solltest du:

name, id und input aus dem tool_use-Block extrahieren.
Das eigentliche Tool in deiner Codebasis ausführen, das diesem Tool-Namen entspricht, und dabei den Tool-input übergeben.
Die Konversation fortsetzen, indem du eine neue Nachricht mit der role user und einem content-Block sendest, der den Typ tool_result und die folgenden Informationen enthält:
- tool_use_id: Die id der Tool-Use-Anfrage, für die dies ein Ergebnis ist.
- content (optional): Das Ergebnis des Tools, als String (zum Beispiel "content": "15 degrees"), als Liste verschachtelter Inhaltsblöcke (zum Beispiel "content": [{"type": "text", "text": "15 degrees"}]) oder als Liste von Dokumentblöcken (zum Beispiel "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Diese Inhaltsblöcke können die Typen text, image, document oder search_result verwenden.
- is_error (optional): Auf true setzen, wenn die Tool-Ausführung zu einem Fehler geführt hat.

Wichtige Formatierungsanforderungen:

Tool-Result-Blöcke müssen im Nachrichtenverlauf unmittelbar auf ihre zugehörigen Tool-Use-Blöcke folgen. Du kannst keine Nachrichten zwischen der Tool-Use-Nachricht des Assistenten und der Tool-Result-Nachricht des Benutzers einfügen.
In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die tool_result-Blöcke ZUERST im Content-Array stehen. Jeglicher Text muss NACH allen Tool-Ergebnissen kommen.
Wenn der Assistenten-Turn auch ein Server-Tool aufgerufen hat, für das noch kein Ergebnisblock vorliegt, darf die Benutzernachricht nur tool_result-Blöcke enthalten. Text nach den Ergebnissen beendet den Turn vorzeitig; bei einem Server-Tool, das Claude direkt aufgerufen hat, schlägt die Anfrage dann mit einem 400-Fehler fehl, der das nicht aufgelöste Server-Tool benennt. Siehe Stop-Gründe und Fallback.

Dies führt zum Beispiel zu einem 400-Fehler:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

Dies ist korrekt, wenn der Assistenten-Turn nur Client-Tools aufruft:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

Wenn du einen Fehler wie „tool_use ids were found without tool_result blocks immediately after" erhältst, überprüfe, ob deine Tool-Ergebnisse korrekt formatiert sind.

Nach Erhalt des Tool-Ergebnisses verwendet Claude diese Informationen, um die Generierung einer Antwort auf den ursprünglichen Benutzer-Prompt fortzusetzen.

Ergebnisse von Server-Tools verarbeiten

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

Fehler mit is_error behandeln

Es gibt einige verschiedene Arten von Fehlern, die bei der Verwendung von Tools mit Claude auftreten können:

Nächste Schritte

Parallele Tool-Nutzung

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

Tool Runner (SDK)

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

Tools definieren

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

Was this page helpful?

MessagesTools

Tool-Aufrufe verarbeiten

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

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.

Wenn du eine Tool-Use-Antwort für ein Client-Tool erhältst, solltest du:

name, id und input aus dem tool_use-Block extrahieren.
Das eigentliche Tool in deiner Codebasis ausführen, das diesem Tool-Namen entspricht, und dabei den Tool-input übergeben.
Die Konversation fortsetzen, indem du eine neue Nachricht mit der role user und einem content-Block sendest, der den Typ tool_result und die folgenden Informationen enthält:
- tool_use_id: Die id der Tool-Use-Anfrage, für die dies ein Ergebnis ist.
- content (optional): Das Ergebnis des Tools, als String (zum Beispiel "content": "15 degrees"), als Liste verschachtelter Inhaltsblöcke (zum Beispiel "content": [{"type": "text", "text": "15 degrees"}]) oder als Liste von Dokumentblöcken (zum Beispiel "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Diese Inhaltsblöcke können die Typen text, image, document oder search_result verwenden.
- is_error (optional): Auf true setzen, wenn die Tool-Ausführung zu einem Fehler geführt hat.

Wichtige Formatierungsanforderungen:

Tool-Result-Blöcke müssen im Nachrichtenverlauf unmittelbar auf ihre zugehörigen Tool-Use-Blöcke folgen. Du kannst keine Nachrichten zwischen der Tool-Use-Nachricht des Assistenten und der Tool-Result-Nachricht des Benutzers einfügen.
In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die tool_result-Blöcke ZUERST im Content-Array stehen. Jeglicher Text muss NACH allen Tool-Ergebnissen kommen.
Wenn der Assistenten-Turn auch ein Server-Tool aufgerufen hat, für das noch kein Ergebnisblock vorliegt, darf die Benutzernachricht nur tool_result-Blöcke enthalten. Text nach den Ergebnissen beendet den Turn vorzeitig; bei einem Server-Tool, das Claude direkt aufgerufen hat, schlägt die Anfrage dann mit einem 400-Fehler fehl, der das nicht aufgelöste Server-Tool benennt. Siehe Stop-Gründe und Fallback.

Dies führt zum Beispiel zu einem 400-Fehler:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

Dies ist korrekt, wenn der Assistenten-Turn nur Client-Tools aufruft:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

Wenn du einen Fehler wie „tool_use ids were found without tool_result blocks immediately after" erhältst, überprüfe, ob deine Tool-Ergebnisse korrekt formatiert sind.

Nach Erhalt des Tool-Ergebnisses verwendet Claude diese Informationen, um die Generierung einer Antwort auf den ursprünglichen Benutzer-Prompt fortzusetzen.

Ergebnisse von Server-Tools verarbeiten

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

Fehler mit is_error behandeln

Es gibt einige verschiedene Arten von Fehlern, die bei der Verwendung von Tools mit Claude auftreten können:

Nächste Schritte

Parallele Tool-Nutzung

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

Tool Runner (SDK)

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

Tools definieren

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

Was this page helpful?

Ergebnisse von Client-Tools verarbeiten

Beispiel einer API-Antwort mit einem `tool_use`-Inhaltsblock

Beispiel eines erfolgreichen Tool-Ergebnisses

Beispiel eines Tool-Ergebnisses mit Bildern

Beispiel eines leeren Tool-Ergebnisses

Beispiel eines Tool-Ergebnisses mit Dokumenten

Ergebnisse von Server-Tools verarbeiten

Fehler mit is_error behandeln

Fehler bei der Tool-Ausführung

Ungültiger Tool-Name

Server-Tool-Fehler

Nächste Schritte

Ergebnisse von Client-Tools verarbeiten

Beispiel einer API-Antwort mit einem `tool_use`-Inhaltsblock

Beispiel eines erfolgreichen Tool-Ergebnisses

Beispiel eines Tool-Ergebnisses mit Bildern

Beispiel eines leeren Tool-Ergebnisses

Beispiel eines Tool-Ergebnisses mit Dokumenten

Ergebnisse von Server-Tools verarbeiten

Fehler mit is_error behandeln

Fehler bei der Tool-Ausführung

Ungültiger Tool-Name

Server-Tool-Fehler

Nächste Schritte

Ergebnisse von Client-Tools verarbeiten

Ergebnisse von Server-Tools verarbeiten

Fehler mit is_error behandeln

Nächste Schritte

Ergebnisse von Client-Tools verarbeiten

Ergebnisse von Server-Tools verarbeiten

Fehler mit is_error behandeln

Nächste Schritte