Wie man Tool-Nutzung implementiert

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.

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:

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.

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.

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.

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:

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

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:

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.

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.

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

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

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.

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: