---
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.
---

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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/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](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.

<Accordion title="Beispiel einer API-Antwort mit einem `tool_use`-Inhaltsblock">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

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](https://platform.claude.com/docs/de/build-with-claude/handling-stop-reasons#quick-reference).

Diese Schritte als vollständige Programme findest du unter [Tutorial: Einen Tool-nutzenden Agenten bauen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/build-a-tool-using-agent).

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`](https://platform.claude.com/docs/de/build-with-claude/search-results) 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 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`](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).

<Note>
  **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-Nutzungs-Nachricht des Assistenten und der Tool-Ergebnis-Nachricht des Nutzers einfügen.
  * In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die `tool_result`-Blöcke im Content-Array ZUERST kommen. 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).

  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.
</Note>

<Warning>
  Tool-Ergebnisse enthalten oft Inhalte aus Quellen außerhalb deiner Kontrolle: Webseiten, eingehende E-Mails, Benutzer-Uploads, APIs von Drittanbietern. Behandle diese Inhalte als nicht vertrauenswürdig: Ein Angreifer, der sie beeinflussen kann, könnte Anweisungen einbetten, die versuchen, Claude umzulenken (indirekte Prompt-Injektion). Belasse nicht vertrauenswürdige Inhalte in `tool_result`-Blöcken statt in `system`-Prompts oder einfachen Benutzer-`text`-Blöcken, und siehe [Jailbreaks und Prompt-Injektionen abschwächen](https://platform.claude.com/docs/de/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) für weitere Härtungsmaßnahmen.
</Warning>

<AccordionGroup>
  <Accordion title="Beispiel eines Tool-Ergebnisses mit Bildern">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Beispiel eines leeren Tool-Ergebnisses">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Beispiel eines Tool-Ergebnisses mit Dokumenten">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Beispiel für Text vor und nach einem Tool-Ergebnis">
    Zum Beispiel verursacht dies einen 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  Eine Antwort kann sowohl einen Client-`tool_use`-Block als auch einen `server_tool_use`-Block enthalten, der keinen Ergebnisblock hat. Dieser Server-Tool-Aufruf ist noch nicht abgeschlossen, und sein Ergebnisblock kommt in einer späteren Antwort. Antworte mit einer Benutzernachricht, 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).
</Note>

<Tip>
  **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 von `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.
</Tip>

## 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.

<AccordionGroup>
  <Accordion title="Fehler bei der Tool-Ausführung">
    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 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.“

    <Tip>
      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 Kontext, den es braucht, um sich zu erholen oder anzupassen, ohne raten zu müssen.
    </Tip>
  </Accordion>

  <Accordion title="Ungültiger Tool-Aufruf">
    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:

    ```json JSON
    {
      "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.

    <Tip>
      Um ungültige Tool-Aufrufe vollständig zu vermeiden, 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 Typkonflikte.
    </Tip>
  </Accordion>

  <Accordion title="Server-Tool-Fehler">
    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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

## Nächste Schritte

<CardGroup cols={3}>
  <Card title="Parallele Tool-Nutzung" icon="grid" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/parallel-tool-use">
    Verarbeite Antworten, in denen Claude mehrere Tools in einem einzigen Turn aufruft.
  </Card>

  <Card title="Tool-Runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-runner">
    Lass das SDK die `tool_use`-Schleife, die Ergebnisformatierung und Wiederholungsversuche für dich verwalten.
  </Card>

  <Card title="Tools definieren" icon="hammer" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/define-tools">
    Schreibe Schemas und Beschreibungen, die Claude zum richtigen Tool lenken.
  </Card>
</CardGroup>
