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 deminput_schemades 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.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}Wenn du eine Tool-Nutzungs-Antwort für ein Client-Tool erhältst, folge diesen Schritten:
- Führe für jeden
tool_use-Block das Tool aus, das der Block benennt, und übergib dabei desseninput. - Behalte in einer neuen Anfrage die früheren Nachrichten bei und füge den
contentder Antwort unverändert alsassistant-Nachricht hinzu. - Füge eine
user-Nachricht mit einemtool_result-Block für jedentool_use-Block in diesem Inhalt hinzu, auch wenn das Tool fehlgeschlagen ist. - Sende die Anfrage mit denselben
toolswie die erste Anfrage. Claude verwendet die Tool-Ergebnisse, um seine Antwort fortzusetzen. - Wenn der
stop_reasonder nächsten Antwort ebenfallstool_useist, 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: Dieiddestool_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 Typentext,image,documentodersearch_resultverwenden.is_error(optional): Auftruesetzen, wenn das Tool fehlgeschlagen ist oder der Aufruf ungültig war.
Ein erfolgreiches Tool-Ergebnis sieht zum Beispiel so aus:
{
"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).
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}Zum Beispiel verursacht dies einen 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
]
}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.
Wenn das Tool selbst während der Ausführung einen Fehler wirft (zum Beispiel einen Netzwerkfehler beim Abrufen von Wetterdaten), kannst du die Fehlermeldung im content zusammen mit "is_error": true zurückgeben:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}Claude kann das Tool dann erneut aufrufen oder dem Nutzer mitteilen, was passiert ist. Claude könnte zum Beispiel sagen: „Es tut mir leid, ich konnte das aktuelle Wetter nicht abrufen, da die API des Wetterdienstes nicht verfügbar ist. Bitte versuche es später erneut.“
Wenn Claudes versuchte Verwendung eines Tools ungültig ist (zum Beispiel wegen fehlender erforderlicher Parameter), bedeutet das in der Regel, dass Claude nicht genügend Informationen hatte, um das Tool korrekt zu verwenden. Der beste Ansatz während der Entwicklung ist, die Anfrage mit detaillierteren description-Werten in deinen Tool-Definitionen erneut zu versuchen.
Du kannst die Konversation jedoch auch mit einem tool_result fortsetzen, das den Fehler angibt:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude kann das Tool dann erneut mit den ergänzten fehlenden Informationen aufrufen.
Im Gegensatz zu Client-Tools sendest du für Server-Tools keine is_error-Ergebnisse. Wenn bei einem Server-Tool ein Fehler auftritt, etwa ein Netzwerkproblem bei der Websuche, gibt die API den Fehler im Ergebnisblock des Tools zurück. In den meisten Fällen fährt Claude dann mit einem anderen Ansatz oder einer Erklärung für den Benutzer fort.
Fehlercodes der Websuche findest du unter Fehler des Websuche-Tools.
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?