--- title: Tool-Aufrufe verarbeiten url: https://platform.claude.com/docs/de/agents-and-tools/tool-use/handle-tool-calls description: 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-runner). **Einfacher mit Tool Runner:** Die auf dieser Seite beschriebene manuelle Tool-Verarbeitung wird von [Tool Runner](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-runner) automatisch verwaltet. Verwende diese Seite, wenn du individuelle Kontrolle über die Tool-Ausführung benötigst. Claudes Antwort unterscheidet sich je nachdem, ob ein [Client- oder Server-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/overview#how-tool-use-works) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool) oder [Browser Use](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool) 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. ```json JSON { "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-Use-Antwort für ein Client-Tool erhältst, solltest du: 1. `name`, `id` und `input` aus dem `tool_use`-Block extrahieren. 2. Das eigentliche Tool in deiner Codebasis ausführen, das diesem Tool-Namen entspricht, und dabei den Tool-`input` übergeben. 3. 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`](https://platform.claude.com/docs/de/build-with-claude/search-results) verwenden. * `is_error` (optional): Auf `true` setzen, wenn die Tool-Ausführung zu einem Fehler geführt hat. 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`](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state)-Block hinzufügen (die [Mitglieder zur Tab-Verwaltung](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool#tab-management-results) geben nur diesen Block zurück). **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 Nutzers einfügen. * In der Nutzernachricht mit den Tool-Ergebnissen müssen die tool\_result-Blöcke im content-Array ZUERST stehen. Jeglicher Text muss NACH allen Tool-Ergebnissen kommen. * Wenn der Assistenten-Turn zusätzlich ein [Server-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/server-tools) aufgerufen hat, für das noch kein Ergebnisblock vorliegt, darf die Nutzernachricht 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](https://platform.claude.com/docs/de/build-with-claude/handling-stop-reasons#tool-use). Dies führt zum Beispiel zu einem 400-Fehler: ```json { "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: ```json { "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, prüfe, ob deine Tool-Ergebnisse korrekt formatiert sind. Tool-Ergebnisse enthalten häufig Inhalte aus Quellen außerhalb deiner Kontrolle: Webseiten, eingehende E-Mails, Nutzer-Uploads, Drittanbieter-APIs. Behandle diese Inhalte als nicht vertrauenswürdig: Ein Angreifer, der sie beeinflussen kann, könnte Anweisungen einbetten, die versuchen, Claude umzulenken („indirect prompt injection“, indirekte Prompt-Injection). Halte nicht vertrauenswürdige Inhalte in `tool_result`-Blöcken statt in `system`-Prompts oder einfachen `text`-Blöcken des Nutzers, und siehe [Jailbreaks und Prompt-Injections abschwächen](https://platform.claude.com/docs/de/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) für weitere Härtungsmaßnahmen. ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "15 degrees" } ] } ``` ```json JSON { "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..." } } ] } ] } ``` ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9" } ] } ``` ```json JSON { "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" } } ] } ] } ``` Nach Erhalt des Tool-Ergebnisses verwendet Claude diese Informationen, um die Generierung einer Antwort auf den ursprünglichen Nutzer-Prompt fortzusetzen. ## 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 Nutzerinteraktion erforderlich ist. Eine Antwort kann sowohl einen Client-`tool_use`-Block als auch einen `server_tool_use`-Block ohne Ergebnisblock enthalten. Dieser Server-Tool-Aufruf ist noch nicht abgeschlossen, und sein Ergebnisblock kommt in einer späteren Antwort. Antworte mit einer Nutzernachricht, die nur die `tool_result`-Blöcke für die Client-Tools enthält, und behalte dasselbe `tools`-Array bei; bei einem Server-Tool, das Claude direkt aufgerufen hat, führt die API es bei dieser Anfrage aus, und die nächste Antwort beginnt mit seinem Ergebnisblock. Siehe [Stop-Gründe und Fallback](https://platform.claude.com/docs/de/build-with-claude/handling-stop-reasons#tool-use). **Unterschiede zu anderen APIs** Anders als APIs, die Tool-Nutzung separieren oder spezielle Rollen wie `tool` oder `function` verwenden, integriert die Claude API Tools direkt in die Nachrichtenstruktur von `user` und `assistant`. Nachrichten enthalten Arrays aus `text`-, `image`-, `tool_use`- und `tool_result`-Blöcken. `user`-Nachrichten enthalten Client-Inhalte und `tool_result`, während `assistant`-Nachrichten KI-generierte Inhalte und `tool_use` enthalten. ## Fehler mit is\_error behandeln Es gibt einige verschiedene Arten von Fehlern, die bei der Verwendung von Tools mit Claude auftreten können: 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: ```json JSON { "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 wird diesen Fehler dann in seine Antwort an den Nutzer einbeziehen. Zum Beispiel: „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.“ Schreibe aussagekräftige Fehlermeldungen. Statt generischer Fehler wie `"failed"` gib an, was schiefgelaufen ist und was Claude als Nächstes versuchen sollte (zum Beispiel `"Rate limit exceeded. Retry after 60 seconds."`). So erhält Claude den nötigen Kontext, um sich zu erholen oder anzupassen, ohne raten zu müssen. Wenn Claudes versuchte Nutzung eines Tools ungültig ist (zum Beispiel fehlende erforderliche Parameter), bedeutet das in der Regel, dass Claude nicht genügend Informationen hatte, um das Tool korrekt zu verwenden. Während der Entwicklung ist es am besten, 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, und Claude wird versuchen, das Tool erneut mit den ergänzten fehlenden Informationen zu verwenden: ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Missing required 'location' parameter", "is_error": true } ] } ``` Wenn eine Tool-Anfrage ungültig ist oder Parameter fehlen, versucht Claude es 2–3 Mal mit Korrekturen erneut, bevor es sich beim Nutzer entschuldigt. Um ungültige Tool-Aufrufe vollständig auszuschließen, verwende [strikte Tool-Nutzung](https://platform.claude.com/docs/de/agents-and-tools/tool-use/strict-tool-use) mit `strict: true` in deinen Tool-Definitionen. Dies garantiert, dass Tool-Eingaben immer exakt deinem Schema entsprechen, und verhindert fehlende Parameter und Typabweichungen. Wenn Server-Tools auf Fehler stoßen (zum Beispiel Netzwerkprobleme bei der Websuche), behandelt Claude diese Fehler transparent und versucht, dem Nutzer eine alternative Antwort oder Erklärung zu geben. Anders als bei Client-Tools musst du für Server-Tools keine `is_error`-Ergebnisse behandeln. Speziell für die Websuche sind folgende Fehlercodes möglich: * `too_many_requests`: Ratenlimit überschritten * `invalid_input`: Ungültiger Suchanfrage-Parameter * `max_uses_exceeded`: Maximale Anzahl an Websuche-Tool-Nutzungen überschritten * `query_too_long`: Anfrage überschreitet die maximale Länge * `unavailable`: Ein interner Fehler ist aufgetreten ## 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.