Wie man Tool-Nutzung implementiert

​

Auswahl eines Modells

Generell sollte man 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 verwenden; sie handhaben mehrere Tools besser und bitten bei Bedarf um Klärung.

Verwende Claude Haiku 3.5 oder Claude Haiku 3 für unkomplizierte Tools, beachte jedoch, dass sie fehlende Parameter ableiten können.

​

Spezifizierung von Client-Tools

Client-Tools (sowohl von Anthropic definierte als auch benutzerdefinierte) werden im tools-Parameter auf oberster Ebene der API-Anfrage spezifiziert. Jede Tool-Definition enthält:

​

System-Prompt für Tool-Nutzung

Wenn du die Anthropic-API mit dem tools-Parameter aufrufst, erstellen wir einen speziellen System-Prompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem vom Benutzer angegebenen System-Prompt. Der erstellte Prompt ist so konzipiert, dass er das Modell anweist, das angegebene Tool bzw. die angegebenen Tools zu verwenden und den notwendigen Kontext für den ordnungsgemäßen Betrieb des Tools bereitzustellen:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

Best Practices für Tool-Definitionen

Um die beste Leistung von Claude bei der Verwendung von Tools zu erzielen, befolge diese Richtlinien:

• Stelle äußerst detaillierte Beschreibungen bereit. Dies ist bei weitem der wichtigste Faktor für die Tool-Leistung. Deine 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 du Claude über deine Tools geben kannst, desto besser wird es bei der Entscheidung sein, wann und wie sie zu verwenden sind. Strebe mindestens 3-4 Sätze pro Tool-Beschreibung an, mehr wenn das Tool komplex ist.
• Priorisiere Beschreibungen gegenüber Beispielen. Während du Beispiele für die Verwendung eines Tools in seiner Beschreibung oder im begleitenden Prompt einfügen kannst, ist dies weniger wichtig als eine klare und umfassende Erklärung des Zwecks und der Parameter des Tools. Füge Beispiele erst hinzu, nachdem du die Beschreibung vollständig ausgearbeitet hast.

Die gute Beschreibung erklärt deutlich, 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 zum Verhalten und zur Verwendung des Tools zurück.

​

Steuerung der Ausgabe von Claude

​

Erzwingen der Tool-Nutzung

In einigen Fällen möchtest du vielleicht, 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. Du kannst dies tun, indem du das Tool im Feld tool_choice wie folgt angibst:

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 eines der bereitgestellten Tools aufrufen soll oder nicht. Dies ist der Standardwert, wenn tools bereitgestellt werden.
• any teilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss, erzwingt aber kein bestimmtes Tool.
• 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.

Dieses Diagramm veranschaulicht, wie jede Option funktioniert:

Beachte, dass wenn du tool_choice als any oder tool einstellst, wir die Assistentennachricht vorausfü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, selbst wenn sie ausdrücklich dazu aufgefordert werden.

Unsere Tests haben gezeigt, dass dies die Leistung nicht beeinträchtigen sollte. Wenn du Chain-of-Thought (besonders mit Opus) beibehalten möchtest, während du immer noch anforderst, dass das Modell ein bestimmtes Tool verwendet, kannst du {"type": "auto"} für tool_choice (den Standardwert) verwenden und explizite Anweisungen in einer user-Nachricht hinzufügen. Zum Beispiel: What's the weather like in London? Use the get_weather tool in your response.

​

JSON-Ausgabe

Tools müssen nicht unbedingt Client-Funktionen sein — du kannst Tools jederzeit verwenden, wenn du möchtest, dass das Modell eine JSON-Ausgabe zurückgibt, die einem bereitgestellten Schema folgt. Du könntest beispielsweise ein record_summary-Tool mit einem bestimmten Schema verwenden. Siehe Tool-Nutzungsbeispiele für ein vollständiges Arbeitsbeispiel.

​

Chain of Thought

Bei der Verwendung von Tools zeigt Claude oft seinen “Gedankengang”, 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 Erzwingen der Tool-Nutzung), und Sonnet und Haiku können dazu aufgefordert werden.

Zum Beispiel könnte Claude auf den Prompt “What’s the weather like in San Francisco right now, and what time is it there?” wie folgt antworten:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Dieser Gedankengang gibt Einblick in Claudes Denkprozess und kann dir helfen, unerwartetes Verhalten zu debuggen.

Beim Claude Sonnet 3-Modell ist der Gedankengang standardmäßig weniger üblich, aber du kannst Claude auffordern, seine Argumentation zu zeigen, indem du etwas wie "Before answering, explain your reasoning step-by-step in tags." zur Benutzernachricht oder zum System-Prompt hinzufügst.

Es ist wichtig zu beachten, dass, während die <thinking>-Tags eine gängige Konvention sind, die Claude verwendet, um seinen Gedankengang zu kennzeichnen, das genaue Format (wie der Name dieses XML-Tags) sich im Laufe der Zeit ändern kann. Dein Code sollte den Gedankengang wie jeden anderen vom 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. Du kannst dieses Verhalten deaktivieren, indem du:

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

​

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 später verwendet, um die Tool-Ergebnisse zuzuordnen.
• name: Der Name des verwendeten Tools.
• input: Ein Objekt, das die an das Tool übergebene Eingabe enthält, die dem input_schema des Tools entspricht.

Wenn du eine Tool-Nutzungsantwort für ein Client-Tool erhältst, solltest du:

1. Den name, die id und den input aus dem tool_use-Block extrahieren.
2. Das tatsächliche Tool in deinem Codebase ausführen, das diesem Tool-Namen entspricht, und dabei den Tool-input übergeben.
3. Das Gespräch fortsetzen, indem du eine neue Nachricht mit der role des user sendest und einen content-Block, 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 degrees") oder Liste von verschachtelten Inhaltsblöcken (z.B. "content": [{"type": "text", "text": "15 degrees"}]). Diese Inhaltsblöcke können die Typen text oder image verwenden.
   • is_error (optional): Auf true gesetzt, wenn die Tool-Ausführung zu einem Fehler führte.

Nach Erhalt des Tool-Ergebnisses wird Claude diese Informationen verwenden, um die Generierung einer Antwort auf den ursprünglichen Benutzer-Prompt fortzusetzen.

​

Umgang mit Ergebnissen von Server-Tools

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

​

Umgang mit dem pause_turn-Stop-Grund

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

So gehst du mit dem pause_turn-Stop-Grund um:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Send the continuation request
    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)

Beim Umgang mit pause_turn:

• Setze das Gespräch fort: Gib die pausierte Antwort unverändert in einer nachfolgenden Anfrage zurück, damit Claude seinen Durchgang fortsetzen kann
• Modifiz iere bei Bedarf: Du kannst optional den Inhalt vor dem Fortsetzen modifizieren, wenn du das Gespräch unterbrechen oder umleiten möchtest
• Bewahre den Tool-Status: Füge die gleichen Tools in der Fortsetzungsanfrage hinzu, um die Funktionalität aufrechtzuerhalten

​

Fehlerbehebung

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