Tool-Aufrufe verarbeiten

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.

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-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 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-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": "15 degrees"
    }
  ]
}

{
  "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"
          }
        }
      ]
    }
  ]
}

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.

Fehler mit is_error behandeln

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

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Nächste Schritte