Auswahl eines Modells

Verwenden Sie generell Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, 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 Klarstellungen. 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.

Spezifikation von Client-Tools

Client-Tools (sowohl von Anthropic definierte als auch benutzerdefinierte) werden im tools Top-Level-Parameter der API-Anfrage spezifiziert. Jede Tool-Definition umfasst:
ParameterBeschreibung
nameDer Name des Tools. Muss dem Regex ^[a-zA-Z0-9_-]{1,64}$ entsprechen.
descriptionEine detaillierte Klartext-Beschreibung dessen, was das Tool tut, wann es verwendet werden sollte und wie es sich verhält.
input_schemaEin JSON Schema Objekt, das die erwarteten Parameter für das Tool definiert.
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 Claude 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 Skalar-Parameter 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. Fügen Sie Beispiele erst hinzu, nachdem Sie die Beschreibung vollständig ausgearbeitet haben.
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 liefert keine anderen Informationen über die Aktie oder das Unternehmen.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Das Aktien-Ticker-Symbol, z.B. AAPL für Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
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.

Kontrolle von Claudes Ausgabe

Erzwingen der Tool-Nutzung

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 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 erlaubt 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 Assistenten-Nachricht vorab ausfüllen, um die Verwendung eines Tools zu erzwingen. Das bedeutet, dass die Modelle keine natürlichsprachliche Antwort oder Erklärung vor tool_use Inhaltsblöcken ausgeben, 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 möchten, dass das Modell natürlichsprachlichen Kontext oder Erklärungen bereitstellt, während es dennoch die Verwendung eines bestimmten Tools anfordert, 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.

Modellantworten mit Tools

Bei der Verwendung von Tools wird Claude oft kommentieren, was es tut, oder natürlich auf den Benutzer antworten, bevor es Tools aufruft. Zum Beispiel, bei der Eingabe “Wie ist das Wetter in San Francisco gerade jetzt, und wie spät ist es dort?”, könnte Claude antworten mit:
JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ich helfe Ihnen dabei, das aktuelle Wetter und die Zeit in San Francisco zu überprüfen."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}
Dieser natürliche Antwortstil hilft Benutzern zu verstehen, was Claude tut, und schafft eine gesprächigere Interaktion. Sie können den Stil und Inhalt dieser Antworten durch Ihre System-Prompts und durch die Bereitstellung von <examples> in Ihren Prompts steuern. Es ist wichtig zu beachten, dass Claude verschiedene Formulierungen und Ansätze verwenden kann, wenn es seine Aktionen erklärt. Ihr Code sollte diese Antworten 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 type auto ist, was sicherstellt, dass Claude höchstens ein Tool verwendet
  • disable_parallel_tool_use=true setzen, wenn tool_choice type any oder tool ist, was sicherstellt, dass Claude genau ein Tool verwendet
Hier ist ein vollständiges Beispiel, das zeigt, wie parallele Tool-Aufrufe in der Nachrichtenhistorie korrekt formatiert werden:
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-sonnet-4-5",
    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"]))

# Das Gespräch 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-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)
Die Assistenten-Nachricht 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"}
    }
  ]
}
Hier ist ein vollständiges, ausführbares Skript zum Testen und Überprüfen, ob parallele Tool-Aufrufe korrekt funktionieren:
#!/usr/bin/env python3
"""Testskript zur Überprüfung paralleler Tool-Aufrufe mit der Claude 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"]
        }
    }
]

# Testgespräch 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-sonnet-4-5",
    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
    })

# Gespräch 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-sonnet-4-5",
    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 Content-Array")
print("✓ Gespräch korrekt für zukünftige parallele Tool-Nutzung formatiert")
Dieses Skript demonstriert:
  • Wie parallele Tool-Aufrufe und Ergebnisse korrekt 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 parallele Tool-Aufrufe effektiv macht.

Maximierung der parallelen Tool-Nutzung

Während Claude 4 Modelle standardmäßig über ausgezeichnete parallele Tool-Nutzungsfähigkeiten verfügen, können Sie die Wahrscheinlichkeit paralleler Tool-Ausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:
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 rufen Sie, wann immer Sie mehrere unabhängige Operationen durchführen müssen, alle relevanten Tools gleichzeitig und nicht 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 rufen Sie, wann immer Sie mehrere unabhängige Operationen durchführen, alle relevanten Tools gleichzeitig und nicht nacheinander auf. Priorisieren Sie das parallele 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>
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.7Claude 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 der token-effizienten Tool-Nutzung, die hilft, Claude zu ermutigen, parallele Tools zu verwenden. Diese Beta-Funktion reduziert auch die Latenz und spart durchschnittlich 14% bei Ausgabe-Tokens.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 Cookbook für die Verwendung dieser Umgehungslösung.

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.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ich werde das aktuelle Wetter in San Francisco für Sie überprüfen."
    },
    {
      "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. Das Gespräch 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 geführt hat.
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 Assistenten-Tool-Nutzungsnachricht und der Benutzer-Tool-Ergebnisnachricht einschließen.
  • In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die tool_result Blöcke ZUERST im Content-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", ...}
]}
Das 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.
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 Grad"
    }
  ]
}
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...",
          }
        }
      ]
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}
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 Information verwenden, um weiterhin eine Antwort auf die ursprüngliche Benutzeranfrage 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 APIsIm Gegensatz zu APIs, die Tool-Nutzung trennen oder spezielle Rollen wie tool oder function verwenden, integriert die Claude 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.
# Überprüfen, ob die Antwort während der Tool-Nutzung abgeschnitten wurde
if response.stop_reason == "max_tokens":
    # Überprüfen, ob der letzte Inhaltsblock eine unvollständige 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-sonnet-4-5",
            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 gehen Sie mit dem pause_turn Stop-Grund um:
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":
    # Das Gespräch 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:
  • Gespräch fortsetzen: Geben Sie die pausierte Antwort unverändert in einer nachfolgenden Anfrage zurück, um Claude seinen Turn fortsetzen zu lassen
  • Bei Bedarf modifizieren: Sie können optional den Inhalt vor der Fortsetzung modifizieren, wenn Sie das Gespräch 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:
Wenn das Tool selbst während der Ausführung einen Fehler auslöst (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: der 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 der Wetterdienst-API nicht verfügbar ist. Bitte versuchen Sie es später erneut.”
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 das Gespräch 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.
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.
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 liefern. 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: Ratenlimit ü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
Wenn Claude keine parallelen Tool-Aufrufe macht, wenn erwartet, überprüfen Sie diese häufigen Probleme:1. Falsche Tool-Ergebnis-FormatierungDas häufigste Problem ist die falsche Formatierung von Tool-Ergebnissen in der Gesprächshistorie. 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 PromptingStandard-Prompting reicht möglicherweise nicht aus. Verwenden Sie stärkere Sprache:
<use_parallel_tool_calls>
Für maximale Effizienz rufen Sie, wann immer Sie mehrere unabhängige Operationen durchführen, 
alle relevanten Tools gleichzeitig und nicht nacheinander auf. 
Priorisieren Sie das parallele Aufrufen von Tools, wann immer möglich.
</use_parallel_tool_calls>
3. Messung der parallelen Tool-NutzungUm 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