Wie man Tool-Nutzung implementiert

Auswahl eines Modells

Wir empfehlen die Verwendung des neuesten Claude Sonnet (4.5) oder Claude Opus (4.1) Modells für komplexe Tools und mehrdeutige Anfragen; sie handhaben mehrere Tools besser und bitten um Klarstellung, wenn nötig.

Verwenden Sie Claude Haiku Modelle für unkomplizierte Tools, beachten Sie aber, dass sie möglicherweise fehlende Parameter ableiten.

Angeben von Client-Tools

Client-Tools (sowohl von Anthropic definiert als auch benutzerdefiniert) werden im tools Top-Level-Parameter der API-Anfrage angegeben. Jede Tool-Definition enthält:

Tool-Nutzungs-Systemprompt

Wenn Sie die Claude API mit dem tools Parameter aufrufen, erstellen wir einen speziellen Systemprompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem benutzerdefinierten Systemprompt. Der konstruierte Prompt ist so gestaltet, dass er das Modell anweist, 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 erhalten, befolgen Sie diese Richtlinien:

• Bieten Sie äußerst detaillierte Beschreibungen. 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 verwendet werden. Streben Sie nach mindestens 3-4 Sätzen pro Tool-Beschreibung an, mehr wenn das Tool komplex ist.
• Priorisieren Sie Beschreibungen, erwägen Sie aber die Verwendung von input_examples für komplexe Tools. Klare Beschreibungen sind am wichtigsten, aber für Tools mit komplexen Eingaben, verschachtelten Objekten oder formatempfindlichen Parametern können Sie das Feld input_examples (Beta) verwenden, um schemavalidierte Beispiele bereitzustellen. Siehe Bereitstellung von Tool-Nutzungsbeispielen für Details.

Die gute Beschreibung erklärt klar, was das Tool tut, wann es verwendet wird, 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.

Bereitstellung von Tool-Nutzungsbeispielen

Sie können konkrete Beispiele gültiger Tool-Eingaben bereitstellen, um Claude zu helfen, Ihre Tools effektiver zu verwenden. Dies ist besonders nützlich für komplexe Tools mit verschachtelten Objekten, optionalen Parametern oder formatempfindlichen Eingaben.

Grundlegende Verwendung

Fügen Sie ein optionales input_examples Feld zu Ihrer Tool-Definition mit einem Array von Beispiel-Eingabeobjekten hinzu. Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein:

Beispiele sind im Prompt neben Ihrem Tool-Schema enthalten und zeigen Claude konkrete Muster für gut geformte Tool-Aufrufe. Dies hilft Claude zu verstehen, wann optionale Parameter einzubeziehen sind, welche Formate zu verwenden sind und wie komplexe Eingaben strukturiert werden.

Anforderungen und Einschränkungen

• Schema-Validierung - Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein. Ungültige Beispiele geben einen 400 Fehler zurück
• Nicht unterstützt für serverseitige Tools - Nur benutzerdefinierte Tools können Eingabebeispiele haben
• Token-Kosten - Beispiele addieren sich zu Prompt-Tokens: ~20-50 Tokens für einfache Beispiele, ~100-200 Tokens für komplexe verschachtelte Objekte

Tool Runner (Beta)

Der Tool Runner bietet eine sofort einsatzbereite Lösung für die Ausführung von Tools mit Claude. Anstatt Tool-Aufrufe, Tool-Ergebnisse und Gesprächsverwaltung manuell zu handhaben, führt der Tool Runner automatisch aus:

• Führt Tools aus, wenn Claude sie aufruft
• Verwaltet den Request/Response-Zyklus
• Verwaltet den Gesprächszustand
• Bietet Typsicherheit und Validierung

Wir empfehlen, dass Sie den Tool Runner für die meisten Tool-Nutzungsimplementierungen verwenden.

Steuern der Ausgabe von Claude

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 die Verwendung eines Tools geben kann. Sie können dies tun, indem Sie das Tool im tool_choice Feld wie folgt angeben:

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 eines der bereitgestellten Tools aufgerufen werden 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 erlaubt 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 zeigt, wie jede Option funktioniert:

Beachten Sie, dass wenn Sie tool_choice als any oder tool haben, wir die Assistant-Nachricht vorab ausfüllen, um zu erzwingen, dass ein Tool verwendet wird. Dies bedeutet, dass die Modelle keine natürlichsprachige Antwort oder Erklärung vor tool_use Content Blöcken ausgeben, auch wenn explizit danach gefragt wird.

Unsere Tests haben gezeigt, dass dies die Leistung nicht verringern sollte. Wenn Sie möchten, dass das Modell natürlichsprachigen Kontext oder Erklärungen bereitstellt, während Sie immer noch 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: 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 — 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.

Modell-Antworten mit Tools

Bei Verwendung von Tools wird Claude oft kommentieren, was es tut, oder natürlich auf den Benutzer antworten, bevor es Tools aufruft.

Zum Beispiel, gegeben die Aufforderung "What's the weather like in San Francisco right now, and what time is it there?", könnte Claude antworten mit:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "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 konversativere Interaktion. Sie können den Stil und den Inhalt dieser Antworten durch Ihre Systemprompts und durch die Bereitstellung von <examples> in Ihren Prompts lenken.

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 vom Assistenten generierten Text behandeln und sich nicht auf spezifische Formatierungskonventionen verlassen.

Parallele Werkzeugnutzung

Standardmäßig kann Claude mehrere Werkzeuge verwenden, um eine Benutzerabfrage zu beantworten. Sie können dieses Verhalten deaktivieren durch:

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

Maximierung der parallelen Werkzeugnutzung

Während Claude 4-Modelle standardmäßig hervorragende Fähigkeiten zur parallelen Werkzeugnutzung haben, können Sie die Wahrscheinlichkeit der parallelen Werkzeugausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:

Behandlung von Werkzeugnutzungs- und Werkzeugergebnis-Inhaltsblöcken

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

Behandlung von Ergebnissen von Client-Werkzeugen

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

• id: Ein eindeutiger Bezeichner für diesen bestimmten Werkzeugnutzungsblock. Dies wird später verwendet, um die Werkzeugergebnisse abzugleichen.
• name: Der Name des verwendeten Werkzeugs.
• input: Ein Objekt, das die an das Werkzeug übergebene Eingabe enthält und dem input_schema des Werkzeugs entspricht.

Wenn Sie eine Werkzeugnutzungsantwort für ein Client-Werkzeug erhalten, sollten Sie:

1. Extrahieren Sie name, id und input aus dem tool_use-Block.
2. Führen Sie das tatsächliche Werkzeug in Ihrer Codebasis aus, das diesem Werkzeugnamen entspricht, und übergeben Sie die Werkzeug-input.
3. Setzen Sie die Konversation fort, indem Sie eine neue Nachricht mit der role von user und einem content-Block mit dem Typ tool_result und den folgenden Informationen senden:
   • tool_use_id: Die id der Werkzeugnutzungsanfrage, für die dies ein Ergebnis ist.
   • content: Das Ergebnis des Werkzeugs als Zeichenkette (z. B. ), eine Liste verschachtelter Inhaltsblöcke (z. B. ) oder eine Liste von Dokumentblöcken (z. B. ). Diese Inhaltsblöcke können die Typen , oder verwenden.

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Nach Erhalt des Werkzeugergebnisses wird Claude diese Informationen verwenden, um die Antwort auf die ursprüngliche Benutzerabfrage fortzusetzen.

Behandlung von Ergebnissen von Server-Werkzeugen

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

Behandlung des max_tokens-Stoppgrunds

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

Behandlung des pause_turn-Stoppgrunds

Bei Verwendung von Server-Werkzeugen wie Web Search kann die API einen pause_turn-Stoppgrund zurückgeben, der anzeigt, dass die API einen langen Zug pausiert hat.

So behandeln Sie den pause_turn-Stoppgrund:

Bei der Behandlung von pause_turn:

• Setzen Sie die Konversation fort: Übergeben Sie die pausierte Antwort unverändert in einer nachfolgenden Anfrage, um Claude seinen Zug fortsetzen zu lassen
• Ändern Sie bei Bedarf: Sie können den Inhalt optional vor dem Fortfahren ändern, wenn Sie die Konversation unterbrechen oder umleiten möchten
• Bewahren Sie den Werkzeugzustand: Fügen Sie die gleichen Werkzeuge in die Fortsetzungsanfrage ein, um die Funktionalität beizubehalten

Fehlerbehebung

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

Dies ist korrekt:

Wenn Sie einen Fehler wie „tool_use ids were found without tool_result blocks immediately after" erhalten, überprüfen Sie, dass Ihre Werkzeugergebnisse korrekt formatiert sind.