Ein Modell auswählen

Verwenden Sie generell Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 oder Claude Opus 3 für komplexe Tools und mehrdeutige Anfragen; sie handhaben mehrere Tools besser und suchen bei Bedarf 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:

ParameterBeschreibung
nameDer Name des Tools. Muss dem Regex ^[a-zA-Z0-9_-]{1,64}$ entsprechen.
descriptionEine detaillierte Klartextbeschreibung 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.

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, wann und wie sie zu verwenden sind. 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.

Die gute Beschreibung erklärt klar, was das Tool tut, wann es zu verwenden ist, 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 Claude zu entscheiden, ob es bereitgestellte Tools aufruft 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 Assistentennachricht vorab ausfüllen, um die Verwendung eines Tools zu erzwingen. Das bedeutet, dass die Modelle keinen Chain-of-Thought text Inhaltsblock 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 Chain-of-Thought (besonders mit Opus) beibehalten möchten, während Sie trotzdem anfordern, 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 zu verwenden sind. Das Claude Opus 3 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 aufgefordert werden.

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": "<thinking>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.</thinking>"
    },
    {
      "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.

Mit dem Claude Sonnet 3 Modell ist Chain of Thought standardmäßig weniger häufig, aber Sie können Claude dazu auffordern, seine Argumentation zu zeigen, indem Sie etwas wie "Bevor Sie antworten, erklären Sie Ihre Argumentation Schritt für Schritt in Tags." zur Benutzernachricht oder zum System-Prompt hinzufügen.

Es ist wichtig zu beachten, dass obwohl die <thinking> Tags eine gängige Konvention sind, die Claude verwendet, um seine Chain of Thought zu kennzeichnen, das genaue Format (wie z.B. wie dieser XML-Tag benannt ist) sich im Laufe der Zeit ändern kann. Ihr Code sollte die Chain of Thought wie jeden anderen assistenten-generierten Text behandeln und sich nicht auf das Vorhandensein oder die spezifische Formatierung der <thinking> Tags 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

Parallele Tool-Nutzung maximieren

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

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, token-effiziente Tool-Nutzung zu aktivieren, was 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, nicht in die token-effiziente Tool-Nutzung Beta einzusteigen, 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 mehrere Tools gleichzeitig parallel für Sie aufzurufen.

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

Behandlung von Tool-Nutzung und Tool-Ergebnis-Inhaltsblöcken

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

Behandlung von 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: Ein eindeutiger Identifikator für diesen bestimmten Tool-Nutzungsblock. Dieser wird verwendet, um die Tool-Ergebnisse später zuzuordnen.
  • name: Der Name des verwendeten Tools.
  • input: Ein Objekt, das die Eingabe enthält, die an das Tool weitergegeben wird, entsprechend dem input_schema des Tools.

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

  1. Den name, id und 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") oder Liste von verschachtelten Inhaltsblöcken (z.B. "content": [{"type": "text", "text": "15 Grad"}]). Diese Inhaltsblöcke können die Typen text oder image 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 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", ...}
]}

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.

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

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

Behandlung des max_tokens Stop-Grundes

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 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-20250514",
            max_tokens=4096,  # Erhöhtes Limit
            messages=messages,
            tools=tools
        )

Behandlung des pause_turn Stop-Grundes

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

So behandeln Sie den pause_turn Stop-Grund:

import anthropic

client = anthropic.Anthropic()

# Erste Anfrage mit Web-Suche
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, um Claude seinen Turn fortsetzen zu lassen
  • 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: