Wie man Tool-Nutzung implementiert

Ein Modell auswählen

Verwenden Sie generell Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (veraltet) oder Claude Opus 3 (veraltet) für komplexe Tools und mehrdeutige Anfragen; sie handhaben mehrere Tools besser und suchen bei Bedarf nach Klarstellung.

Verwenden Sie Claude Haiku 3.5 oder Claude Haiku 3 für einfache Tools, beachten Sie jedoch, dass sie möglicherweise fehlende Parameter ableiten.

Wenn Sie Claude Sonnet 3.7 mit Tool-Nutzung und erweitertem Denken verwenden, lesen Sie unseren Leitfaden hier für weitere Informationen.

Client-Tools spezifizieren

Client-Tools (sowohl von Anthropic definierte als auch benutzerdefinierte) werden im tools Top-Level-Parameter der API-Anfrage spezifiziert. Jede Tool-Definition umfasst:

Parameter	Beschreibung
name	Der Name des Tools. Muss dem Regex ^[a-zA-Z0-9_-]{1,64}$ entsprechen.
description	Eine detaillierte Klartextbeschreibung dessen, was das Tool tut, wann es verwendet werden sollte und wie es sich verhält.
input_schema	Ein JSON Schema Objekt, das die erwarteten Parameter für das Tool definiert.

Beispiel einer einfachen Tool-Definition

JSON

{
  "name": "get_weather",
  "description": "Das aktuelle Wetter an einem bestimmten Ort abrufen",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Die Stadt und der Staat, z.B. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Die Temperatureinheit, entweder 'celsius' oder 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Dieses Tool namens get_weather erwartet ein Eingabeobjekt mit einem erforderlichen location String und einem optionalen unit String, der entweder “celsius” oder “fahrenheit” sein muss.

Tool-Nutzung System-Prompt

Wenn Sie die Anthropic API mit dem tools Parameter aufrufen, konstruieren wir einen speziellen System-Prompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem benutzerdefinierten System-Prompt. Der konstruierte Prompt ist darauf ausgelegt, das Modell anzuweisen, die spezifizierten Tool(s) zu verwenden und den notwendigen Kontext für das ordnungsgemäße Funktionieren des Tools bereitzustellen:

In dieser Umgebung haben Sie Zugang zu einer Reihe von Tools, die Sie verwenden können, um die Frage des Benutzers zu beantworten.
{{ FORMATIERUNGSANWEISUNGEN }}
String- und Skalarparameter sollten wie sie sind angegeben werden, während Listen und Objekte das JSON-Format verwenden sollten. Beachten Sie, dass Leerzeichen für String-Werte nicht entfernt werden. Die Ausgabe wird nicht als gültiges XML erwartet und wird mit regulären Ausdrücken geparst.
Hier sind die verfügbaren Funktionen im JSONSchema-Format:
{{ TOOL-DEFINITIONEN IM JSON SCHEMA }}
{{ BENUTZER SYSTEM PROMPT }}
{{ TOOL-KONFIGURATION }}

Best Practices für Tool-Definitionen

Um die beste Leistung von Claude bei der Verwendung von Tools zu erhalten, befolgen Sie diese Richtlinien:

• Stellen Sie extrem detaillierte Beschreibungen bereit. Dies ist bei weitem der wichtigste Faktor für die Tool-Leistung. Ihre Beschreibungen sollten jedes Detail über das Tool erklären, einschließlich:
  • Was das Tool tut
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Vorbehalte oder Einschränkungen, wie z.B. welche Informationen das Tool nicht zurückgibt, wenn der Tool-Name unklar ist. Je mehr Kontext Sie Claude über Ihre Tools geben können, desto besser wird es bei der Entscheidung sein, wann und wie sie verwendet werden. Streben Sie mindestens 3-4 Sätze pro Tool-Beschreibung an, mehr wenn das Tool komplex ist.
• Priorisieren Sie Beschreibungen über Beispiele. Während Sie Beispiele für die Verwendung eines Tools in seiner Beschreibung oder im begleitenden Prompt einschließen können, ist dies weniger wichtig als eine klare und umfassende Erklärung des Zwecks und der Parameter des Tools zu haben. Fügen Sie nur Beispiele hinzu, nachdem Sie die Beschreibung vollständig ausgearbeitet haben.

Beispiel einer guten Tool-Beschreibung

JSON

{
  "name": "get_stock_price",
  "description": "Ruft den aktuellen Aktienkurs für ein gegebenes Ticker-Symbol ab. Das Ticker-Symbol muss ein gültiges Symbol für ein börsennotiertes Unternehmen an einer großen US-Börse wie NYSE oder NASDAQ sein. Das Tool gibt den neuesten Handelspreis in USD zurück. Es sollte verwendet werden, wenn der Benutzer nach dem aktuellen oder neuesten Preis einer bestimmten Aktie fragt. Es wird keine anderen Informationen über die Aktie oder das Unternehmen bereitstellen.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Das Aktien-Ticker-Symbol, z.B. AAPL für Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Beispiel einer schlechten Tool-Beschreibung

JSON

{
  "name": "get_stock_price",
  "description": "Holt den Aktienkurs für ein Ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

Die gute Beschreibung erklärt klar, was das Tool tut, wann es verwendet werden soll, welche Daten es zurückgibt und was der ticker Parameter bedeutet. Die schlechte Beschreibung ist zu kurz und lässt Claude mit vielen offenen Fragen über das Verhalten und die Verwendung des Tools zurück.

Claudes Ausgabe kontrollieren

Tool-Nutzung erzwingen

In einigen Fällen möchten Sie möglicherweise, dass Claude ein bestimmtes Tool verwendet, um die Frage des Benutzers zu beantworten, auch wenn Claude denkt, dass es eine Antwort ohne Verwendung eines Tools geben kann. Sie können dies tun, indem Sie das Tool im tool_choice Feld wie folgt spezifizieren:

tool_choice = {"type": "tool", "name": "get_weather"}

Bei der Arbeit mit dem tool_choice Parameter haben wir vier mögliche Optionen:

• auto erlaubt es Claude zu entscheiden, ob bereitgestellte Tools aufgerufen werden sollen oder nicht. Dies ist der Standardwert, wenn tools bereitgestellt werden.
• any teilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss, aber kein bestimmtes Tool erzwingt.
• tool ermöglicht es uns, Claude zu zwingen, immer ein bestimmtes Tool zu verwenden.
• none verhindert, dass Claude Tools verwendet. Dies ist der Standardwert, wenn keine tools bereitgestellt werden.

Bei der Verwendung von Prompt-Caching werden Änderungen am tool_choice Parameter zwischengespeicherte Nachrichtenblöcke ungültig machen. Tool-Definitionen und System-Prompts bleiben zwischengespeichert, aber Nachrichteninhalte müssen erneut verarbeitet werden.

Dieses Diagramm veranschaulicht, wie jede Option funktioniert:

Beachten Sie, dass wenn Sie tool_choice als any oder tool haben, wir die Assistentennachricht vorab ausfüllen werden, um die Verwendung eines Tools zu erzwingen. Das bedeutet, dass die Modelle keinen Chain-of-Thought text Inhaltsblock vor tool_use Inhaltsblöcken ausgeben werden, auch wenn explizit darum gebeten wird.

Bei der Verwendung von erweitertem Denken mit Tool-Nutzung werden tool_choice: {"type": "any"} und tool_choice: {"type": "tool", "name": "..."} nicht unterstützt und führen zu einem Fehler. Nur tool_choice: {"type": "auto"} (der Standard) und tool_choice: {"type": "none"} sind mit erweitertem Denken kompatibel.

Unsere Tests haben gezeigt, dass dies die Leistung nicht reduzieren sollte. Wenn Sie Chain-of-Thought (insbesondere mit Opus) beibehalten möchten, während Sie dennoch verlangen, dass das Modell ein bestimmtes Tool verwendet, können Sie {"type": "auto"} für tool_choice (der Standard) verwenden und explizite Anweisungen in einer user Nachricht hinzufügen. Zum Beispiel: Wie ist das Wetter in London? Verwenden Sie das get_weather Tool in Ihrer Antwort.

JSON-Ausgabe

Tools müssen nicht unbedingt Client-Funktionen sein — Sie können Tools jederzeit verwenden, wenn Sie möchten, dass das Modell JSON-Ausgabe zurückgibt, die einem bereitgestellten Schema folgt. Zum Beispiel könnten Sie ein record_summary Tool mit einem bestimmten Schema verwenden. Siehe Tool-Nutzung mit Claude für ein vollständiges funktionierendes Beispiel.

Chain of Thought

Bei der Verwendung von Tools zeigt Claude oft seine “Chain of Thought”, d.h. die schrittweise Argumentation, die es verwendet, um das Problem zu zerlegen und zu entscheiden, welche Tools verwendet werden sollen. Das Claude Opus 3 (veraltet) Modell wird dies tun, wenn tool_choice auf auto gesetzt ist (dies ist der Standardwert, siehe Tool-Nutzung erzwingen), und Sonnet und Haiku können dazu veranlasst werden, es zu tun.

Zum Beispiel, bei dem Prompt “Wie ist das Wetter in San Francisco gerade jetzt, und wie spät ist es dort?”, könnte Claude mit folgendem antworten:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Um diese Frage zu beantworten, werde ich: 1. Das get_weather Tool verwenden, um das aktuelle Wetter in San Francisco zu erhalten. 2. Das get_time Tool verwenden, um die aktuelle Zeit in der America/Los_Angeles Zeitzone zu erhalten, die San Francisco, CA abdeckt."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Diese Chain of Thought gibt Einblick in Claudes Denkprozess und kann Ihnen helfen, unerwartetes Verhalten zu debuggen.

Es ist wichtig zu beachten, dass Claude verschiedene Formate verwenden kann, um seine Chain of Thought zu kennzeichnen. Ihr Code sollte die Chain of Thought wie jeden anderen von einem Assistenten generierten Text behandeln und sich nicht auf spezifische Formatierungskonventionen verlassen.

Parallele Tool-Nutzung

Standardmäßig kann Claude mehrere Tools verwenden, um eine Benutzeranfrage zu beantworten. Sie können dieses Verhalten deaktivieren, indem Sie:

• disable_parallel_tool_use=true setzen, wenn tool_choice Typ auto ist, was sicherstellt, dass Claude höchstens ein Tool verwendet
• disable_parallel_tool_use=true setzen, wenn tool_choice Typ any oder tool ist, was sicherstellt, dass Claude genau ein Tool verwendet

Vollständiges Beispiel für parallele Tool-Nutzung

Hier ist ein vollständiges Beispiel, das zeigt, wie parallele Tool-Aufrufe in der Nachrichtenhistorie richtig formatiert werden:

Python

import anthropic

client = anthropic.Anthropic()

# Tools definieren
tools = [
    {
        "name": "get_weather",
        "description": "Das aktuelle Wetter an einem bestimmten Ort abrufen",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "Die Stadt und der Staat, z.B. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Die aktuelle Zeit in einer bestimmten Zeitzone abrufen",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Die Zeitzone, z.B. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Erste Anfrage
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "Wie ist das Wetter in SF und NYC, und wie spät ist es dort?"
        }
    ]
)

# Claudes Antwort mit parallelen Tool-Aufrufen
print("Claude möchte Tools verwenden:", response.stop_reason == "tool_use")
print("Anzahl der Tool-Aufrufe:", len([c for c in response.content if c.type == "tool_use"]))

# Die Unterhaltung mit Tool-Ergebnissen aufbauen
messages = [
    {
        "role": "user",
        "content": "Wie ist das Wetter in SF und NYC, und wie spät ist es dort?"
    },
    {
        "role": "assistant",
        "content": response.content  # Enthält mehrere tool_use Blöcke
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Muss mit der ID von tool_use übereinstimmen
                "content": "San Francisco: 68°F, teilweise bewölkt"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, klarer Himmel"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco Zeit: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York Zeit: 5:30 PM EST"
            }
        ]
    }
]

# Endgültige Antwort erhalten
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

Die Assistentennachricht mit parallelen Tool-Aufrufen würde so aussehen:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ich werde das Wetter und die Zeit für San Francisco und New York City überprüfen."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

Vollständiges Testskript für parallele Tools

Hier ist ein vollständiges, ausführbares Skript zum Testen und Überprüfen, ob parallele Tool-Aufrufe korrekt funktionieren:

Python

#!/usr/bin/env python3
"""Testskript zur Überprüfung paralleler Tool-Aufrufe mit der Anthropic API"""

import os
from anthropic import Anthropic

# Client initialisieren
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Tools definieren
tools = [
    {
        "name": "get_weather",
        "description": "Das aktuelle Wetter an einem bestimmten Ort abrufen",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "Die Stadt und der Staat, z.B. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Die aktuelle Zeit in einer bestimmten Zeitzone abrufen",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Die Zeitzone, z.B. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Testunterhaltung mit parallelen Tool-Aufrufen
messages = [
    {
        "role": "user",
        "content": "Wie ist das Wetter in SF und NYC, und wie spät ist es dort?"
    }
]

# Erste Anfrage stellen
print("Parallele Tool-Aufrufe anfordern...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Auf parallele Tool-Aufrufe prüfen
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude hat {len(tool_uses)} Tool-Aufrufe gemacht")

if len(tool_uses) > 1:
    print("✓ Parallele Tool-Aufrufe erkannt!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ Keine parallelen Tool-Aufrufe erkannt")

# Tool-Ausführung simulieren und Ergebnisse korrekt formatieren
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, teilweise bewölkt"
        else:
            result = "New York: 45°F, klarer Himmel"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Unterhaltung mit Tool-Ergebnissen fortsetzen
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # Alle Ergebnisse in einer Nachricht!
])

# Endgültige Antwort erhalten
print("\nEndgültige Antwort erhalten...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaudes Antwort:\n{final_response.content[0].text}")

# Formatierung überprüfen
print("\n--- Überprüfung ---")
print(f"✓ Tool-Ergebnisse in einer einzigen Benutzernachricht gesendet: {len(tool_results)} Ergebnisse")
print("✓ Kein Text vor Tool-Ergebnissen im Inhalts-Array")
print("✓ Unterhaltung korrekt für zukünftige parallele Tool-Nutzung formatiert")

Dieses Skript demonstriert:

• Wie parallele Tool-Aufrufe und -Ergebnisse richtig formatiert werden
• Wie überprüft wird, dass parallele Aufrufe gemacht werden
• Die korrekte Nachrichtenstruktur, die zukünftige parallele Tool-Nutzung fördert
• Häufige Fehler, die vermieden werden sollten (wie Text vor Tool-Ergebnissen)

Führen Sie dieses Skript aus, um Ihre Implementierung zu testen und sicherzustellen, dass Claude effektiv parallele Tool-Aufrufe macht.

Parallele Tool-Nutzung maximieren

Während Claude 4 Modelle standardmäßig ausgezeichnete parallele Tool-Nutzungsfähigkeiten haben, können Sie die Wahrscheinlichkeit paralleler Tool-Ausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:

System-Prompts für parallele Tool-Nutzung

Für Claude 4 Modelle (Opus 4.1, Opus 4 und Sonnet 4), fügen Sie dies zu Ihrem System-Prompt hinzu:

Für maximale Effizienz, wann immer Sie mehrere unabhängige Operationen durchführen müssen, rufen Sie alle relevanten Tools gleichzeitig statt nacheinander auf.

Für noch stärkere parallele Tool-Nutzung (empfohlen, wenn der Standard nicht ausreicht), verwenden Sie:

<use_parallel_tool_calls>
Für maximale Effizienz, wann immer Sie mehrere unabhängige Operationen durchführen, rufen Sie alle relevanten Tools gleichzeitig statt nacheinander auf. Priorisieren Sie das gleichzeitige Aufrufen von Tools, wann immer möglich. Zum Beispiel, beim Lesen von 3 Dateien, führen Sie 3 Tool-Aufrufe parallel aus, um alle 3 Dateien gleichzeitig in den Kontext zu lesen. Beim Ausführen mehrerer schreibgeschützter Befehle wie `ls` oder `list_dir`, führen Sie immer alle Befehle parallel aus. Tendieren Sie dazu, parallele Tool-Aufrufe zu maximieren, anstatt zu viele Tools nacheinander auszuführen.
</use_parallel_tool_calls>

Benutzernachrichten-Prompting

Sie können auch parallele Tool-Nutzung innerhalb spezifischer Benutzernachrichten fördern:

# Anstatt:
"Wie ist das Wetter in Paris? Überprüfen Sie auch London."

# Verwenden Sie:
"Überprüfen Sie das Wetter in Paris und London gleichzeitig."

# Oder seien Sie explizit:
"Bitte verwenden Sie parallele Tool-Aufrufe, um das Wetter für Paris, London und Tokio gleichzeitig zu erhalten."

Parallele Tool-Nutzung mit Claude Sonnet 3.7

Claude Sonnet 3.7 macht möglicherweise weniger wahrscheinlich parallele Tool-Aufrufe in einer Antwort, auch wenn Sie disable_parallel_tool_use nicht gesetzt haben. Um dies zu umgehen, empfehlen wir die Aktivierung von token-effizienter Tool-Nutzung, was hilft, Claude zu ermutigen, parallele Tools zu verwenden. Diese Beta-Funktion reduziert auch die Latenz und spart durchschnittlich 14% bei Ausgabe-Token.

Wenn Sie es vorziehen, sich nicht für die token-effiziente Tool-Nutzung Beta anzumelden, können Sie auch ein “Batch-Tool” einführen, das als Meta-Tool fungieren kann, um Aufrufe an andere Tools gleichzeitig zu umhüllen. Wir stellen fest, dass wenn dieses Tool vorhanden ist, das Modell es verwenden wird, um gleichzeitig mehrere Tools parallel für Sie aufzurufen.

Siehe dieses Beispiel in unserem Kochbuch für die Verwendung dieser Umgehung.

Umgang mit Tool-Nutzung und Tool-Ergebnis-Inhaltsblöcken

Claudes Antwort unterscheidet sich je nachdem, ob es ein Client- oder Server-Tool verwendet.

Umgang mit Ergebnissen von Client-Tools

Die Antwort wird einen stop_reason von tool_use und einen oder mehrere tool_use Inhaltsblöcke haben, die Folgendes enthalten:

• id: Eine eindeutige Kennung für diesen bestimmten Tool-Nutzungsblock. Diese wird verwendet, um die Tool-Ergebnisse später zuzuordnen.
• name: Der Name des verwendeten Tools.
• input: Ein Objekt, das die an das Tool übergebene Eingabe enthält, entsprechend dem input_schema des Tools.

Beispiel API-Antwort mit einem `tool_use` Inhaltsblock

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ich muss das get_weather verwenden, und der Benutzer möchte SF, was wahrscheinlich San Francisco, CA ist."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Wenn Sie eine Tool-Nutzungsantwort für ein Client-Tool erhalten, sollten Sie:

1. Den name, die id und die input aus dem tool_use Block extrahieren.
2. Das tatsächliche Tool in Ihrer Codebasis ausführen, das diesem Tool-Namen entspricht, und die Tool-input übergeben.
3. Die Unterhaltung fortsetzen, indem Sie eine neue Nachricht mit der role von user und einem content Block senden, der den tool_result Typ und die folgenden Informationen enthält:
   • tool_use_id: Die id der Tool-Nutzungsanfrage, für die dies ein Ergebnis ist.
   • content: Das Ergebnis des Tools, als String (z.B. "content": "15 Grad"), eine Liste verschachtelter Inhaltsblöcke (z.B. "content": [{"type": "text", "text": "15 Grad"}]), oder eine Liste von Dokumentblöcken (z.B. "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 Grad"}]). Diese Inhaltsblöcke können die Typen text, image oder document verwenden.
   • is_error (optional): Auf true setzen, wenn die Tool-Ausführung zu einem Fehler führte.

Wichtige Formatierungsanforderungen:

• Tool-Ergebnisblöcke müssen unmittelbar auf ihre entsprechenden Tool-Nutzungsblöcke in der Nachrichtenhistorie folgen. Sie können keine Nachrichten zwischen der Tool-Nutzungsnachricht des Assistenten und der Tool-Ergebnisnachricht des Benutzers einfügen.
• In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die tool_result Blöcke ZUERST im Inhalts-Array stehen. Jeder Text muss NACH allen Tool-Ergebnissen kommen.

Zum Beispiel wird dies einen 400-Fehler verursachen:

{"role": "user", "content": [
  {"type": "text", "text": "Hier sind die Ergebnisse:"},  // ❌ Text vor tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Dies ist korrekt:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "Was soll ich als nächstes tun?"}  // ✅ Text nach tool_result
]}

Wenn Sie einen Fehler wie “tool_use ids were found without tool_result blocks immediately after” erhalten, überprüfen Sie, ob Ihre Tool-Ergebnisse korrekt formatiert sind.

Beispiel eines erfolgreichen Tool-Ergebnisses

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 Grad"
    }
  ]
}

Beispiel eines Tool-Ergebnisses mit Bildern

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 Grad"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Beispiel eines leeren Tool-Ergebnisses

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Beispiel eines Tool-Ergebnisses mit Dokumenten

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "Das Wetter ist"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 Grad"
          }
        }
      ]
    }
  ]
}

Nach Erhalt des Tool-Ergebnisses wird Claude diese Informationen verwenden, um eine Antwort auf den ursprünglichen Benutzer-Prompt zu generieren.

Umgang mit Ergebnissen von Server-Tools

Claude führt das Tool intern aus und integriert die Ergebnisse direkt in seine Antwort, ohne zusätzliche Benutzerinteraktion zu erfordern.

Unterschiede zu anderen APIs

Im Gegensatz zu APIs, die Tool-Nutzung trennen oder spezielle Rollen wie tool oder function verwenden, integriert Anthropics API Tools direkt in die user und assistant Nachrichtenstruktur.

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.

Umgang mit dem max_tokens Stop-Grund

Wenn Claudes Antwort aufgrund des Erreichens des max_tokens Limits abgeschnitten wird und die abgeschnittene Antwort einen unvollständigen Tool-Nutzungsblock enthält, müssen Sie die Anfrage mit einem höheren max_tokens Wert wiederholen, um die vollständige Tool-Nutzung zu erhalten.

Python

# Überprüfen, ob die Antwort während der Tool-Nutzung abgeschnitten wurde
if response.stop_reason == "max_tokens":
    # Überprüfen, ob der letzte Inhaltsblock ein unvollständiger tool_use ist
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Die Anfrage mit höherem max_tokens senden
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # Erhöhtes Limit
            messages=messages,
            tools=tools
        )

Umgang mit dem pause_turn Stop-Grund

Bei der Verwendung von Server-Tools wie Websuche kann die API einen pause_turn Stop-Grund zurückgeben, der anzeigt, dass die API einen lang laufenden Turn pausiert hat.

So handhaben Sie den pause_turn Stop-Grund:

Python

import anthropic

client = anthropic.Anthropic()

# Erste Anfrage mit Websuche
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Suchen Sie nach umfassenden Informationen über Quantencomputing-Durchbrüche in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Überprüfen, ob die Antwort pause_turn Stop-Grund hat
if response.stop_reason == "pause_turn":
    # Die Unterhaltung mit dem pausierten Inhalt fortsetzen
    messages = [
        {"role": "user", "content": "Suchen Sie nach umfassenden Informationen über Quantencomputing-Durchbrüche in 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Die Fortsetzungsanfrage senden
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Bei der Behandlung von pause_turn:

• Unterhaltung fortsetzen: Geben Sie die pausierte Antwort unverändert in einer nachfolgenden Anfrage zurück, damit Claude seinen Turn fortsetzen kann
• Bei Bedarf modifizieren: Sie können optional den Inhalt vor der Fortsetzung modifizieren, wenn Sie die Unterhaltung unterbrechen oder umleiten möchten
• Tool-Status beibehalten: Schließen Sie dieselben Tools in die Fortsetzungsanfrage ein, um die Funktionalität aufrechtzuerhalten

Fehlerbehebung

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

Tool-Ausführungsfehler

Wenn das Tool selbst während der Ausführung einen Fehler wirft (z.B. ein Netzwerkfehler beim Abrufen von Wetterdaten), können Sie die Fehlermeldung im content zusammen mit "is_error": true zurückgeben:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: die Wetterdienst-API ist nicht verfügbar (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude wird dann diesen Fehler in seine Antwort an den Benutzer einbauen, z.B. “Es tut mir leid, ich konnte das aktuelle Wetter nicht abrufen, weil die Wetterdienst-API nicht verfügbar ist. Bitte versuchen Sie es später erneut.”

Ungültiger Tool-Name

Wenn Claudes versuchte Verwendung eines Tools ungültig ist (z.B. fehlende erforderliche Parameter), bedeutet das normalerweise, dass nicht genügend Informationen vorhanden waren, damit Claude das Tool korrekt verwenden konnte. Ihr bester Ansatz während der Entwicklung ist es, die Anfrage erneut mit detaillierteren description Werten in Ihren Tool-Definitionen zu versuchen.

Sie können jedoch auch die Unterhaltung mit einem tool_result fortsetzen, das den Fehler anzeigt, und Claude wird versuchen, das Tool erneut mit den fehlenden Informationen zu verwenden:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Fehler: Erforderlicher 'location' Parameter fehlt",
      "is_error": true
    }
  ]
}

Wenn eine Tool-Anfrage ungültig ist oder Parameter fehlen, wird Claude 2-3 Mal mit Korrekturen wiederholen, bevor es sich beim Benutzer entschuldigt.

<search_quality_reflection> Tags

Um zu verhindern, dass Claude über die Qualität der Suchergebnisse mit <search_quality_reflection> Tags reflektiert, fügen Sie “Reflektieren Sie nicht über die Qualität der zurückgegebenen Suchergebnisse in Ihrer Antwort” zu Ihrem Prompt hinzu.

Server-Tool-Fehler

Wenn Server-Tools auf Fehler stoßen (z.B. Netzwerkprobleme bei der Websuche), wird Claude diese Fehler transparent behandeln und versuchen, eine alternative Antwort oder Erklärung für den Benutzer zu geben. Im Gegensatz zu Client-Tools müssen Sie keine is_error Ergebnisse für Server-Tools behandeln.

Für Websuche speziell umfassen mögliche Fehlercodes:

• too_many_requests: Rate-Limit überschritten
• invalid_input: Ungültiger Suchanfrage-Parameter
• max_uses_exceeded: Maximale Websuche-Tool-Nutzungen überschritten
• query_too_long: Anfrage überschreitet maximale Länge
• unavailable: Ein interner Fehler ist aufgetreten

Parallele Tool-Aufrufe funktionieren nicht

Wenn Claude nicht die erwarteten parallelen Tool-Aufrufe macht, überprüfen Sie diese häufigen Probleme:

1. Falsche Tool-Ergebnis-Formatierung

Das häufigste Problem ist die falsche Formatierung von Tool-Ergebnissen in der Unterhaltungshistorie. Dies “lehrt” Claude, parallele Aufrufe zu vermeiden.

Speziell für parallele Tool-Nutzung:

• ❌ Falsch: Separate Benutzernachrichten für jedes Tool-Ergebnis senden
• ✅ Richtig: Alle Tool-Ergebnisse müssen in einer einzigen Benutzernachricht sein

// ❌ Dies reduziert parallele Tool-Nutzung
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate Nachricht
]

// ✅ Dies erhält parallele Tool-Nutzung
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Einzelne Nachricht
]

Siehe die allgemeinen Formatierungsanforderungen oben für andere Formatierungsregeln.

2. Schwaches Prompting

Standard-Prompting ist möglicherweise nicht ausreichend. Verwenden Sie stärkere Sprache:

<use_parallel_tool_calls>
Für maximale Effizienz, wann immer Sie mehrere unabhängige Operationen durchführen, 
rufen Sie alle relevanten Tools gleichzeitig statt nacheinander auf. 
Priorisieren Sie das gleichzeitige Aufrufen von Tools, wann immer möglich.
</use_parallel_tool_calls>

3. Parallele Tool-Nutzung messen

Um zu überprüfen, ob parallele Tool-Aufrufe funktionieren:

# Durchschnittliche Tools pro Tool-aufrufender Nachricht berechnen
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Durchschnittliche Tools pro Nachricht: {avg_tools_per_message}")
# Sollte > 1.0 sein, wenn parallele Aufrufe funktionieren

4. Modellspezifisches Verhalten

• Claude Opus 4.1, Opus 4 und Sonnet 4: Exzellent bei paralleler Tool-Nutzung mit minimalem Prompting
• Claude Sonnet 3.7: Benötigt möglicherweise stärkeres Prompting oder token-effiziente Tool-Nutzung
• Claude Haiku: Weniger wahrscheinlich, parallele Tools ohne explizites Prompting zu verwenden