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 suchen bei Bedarf nach Klarstellung.

Verwenden Sie Claude Haiku Modelle für unkomplizierte Tools, aber beachten Sie, 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 darauf ausgelegt, das Modell anzuweisen, 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 mindestens 3-4 Sätze 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 werden sollte, 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.

Bereitstellung von Tool-Nutzungsbeispielen

Sie können konkrete Beispiele gültiger Tool-Eingaben bereitstellen, um Claude zu helfen, Ihre Tools effektiver zu verstehen. 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 Claude-Ausgabe

Erzwingung 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 ermöglicht 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 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 zeigt, wie jede Option funktioniert:

Beachten Sie, dass wenn Sie tool_choice als any oder tool haben, wir die Assistenten-Nachricht vorab ausfüllen, um zu erzwingen, dass ein Tool verwendet wird. Dies bedeutet, dass die Modelle keine natürliche Sprachantwort 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ürlichsprachlichen Kontext oder Erklärungen bietet, während Sie dennoch 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.

Modellreaktionen mit Tools

Bei der Verwendung von Tools wird Claude häufig kommentieren, was es tut, oder natürlich auf den Benutzer reagieren, bevor es Tools aufruft.

Beispielsweise könnte Claude bei der Eingabeaufforderung „Wie ist das Wetter in San Francisco gerade, und wie spät ist es dort?" mit folgendem antworten:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ich helfe dir, 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 konversativere Interaktion. Du kannst den Stil und den Inhalt dieser Antworten durch deine Systemaufforderungen und durch die Bereitstellung von <examples> in deinen Aufforderungen steuern.

Es ist wichtig zu beachten, dass Claude verschiedene Formulierungen und Ansätze verwenden kann, wenn es seine Aktionen erklärt. Dein Code sollte diese Antworten wie jeden anderen vom Assistenten generierten Text behandeln und sich nicht auf spezifische Formatierungskonventionen verlassen.

Parallele Tool-Nutzung

Standardmäßig kann Claude mehrere Tools verwenden, um eine Benutzerabfrage zu beantworten. Du kannst 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 Tool verwendet
• Setzen von disable_parallel_tool_use=true, wenn der tool_choice-Typ any oder tool ist, was sicherstellt, dass Claude genau ein Tool verwendet

Maximierung der parallelen Tool-Nutzung

Während Claude 4-Modelle standardmäßig hervorragende Fähigkeiten zur parallelen Tool-Nutzung haben, kannst du die Wahrscheinlichkeit der parallelen Tool-Ausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:

Behandlung von Tool-Nutzungs- und Tool-Ergebnis-Content-Blöcken

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

Behandlung von Ergebnissen aus Client-Tools

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

• id: Ein eindeutiger Bezeichner für diesen bestimmten Tool-Use-Block. Dies wird später verwendet, um die Tool-Ergebnisse abzugleichen.
• name: Der Name des verwendeten Tools.
• input: Ein Objekt, das die an das Tool übergebene Eingabe enthält und dem input_schema des Tools entspricht.

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

1. Den name, id und input aus dem tool_use Block extrahieren.
2. Das tatsächliche Tool in deiner Codebasis ausführen, das diesem Tool-Namen entspricht, und die Tool-input übergeben.
3. Die Konversation fortsetzen, indem du eine neue Nachricht mit der role von user sendest und einen content Block mit dem tool_result Typ und den folgenden Informationen enthältst:
   • tool_use_id: Die id der Tool-Use-Anfrage, für die dies ein Ergebnis ist.
   • content: Das Ergebnis des Tools als String (z.B. ), eine Liste verschachtelter Content-Blöcke (z.B. ) oder eine Liste von Dokument-Blöcken (z.B. ). Diese Content-Blöcke können die Typen , oder verwenden.

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

Nach Erhalt des Tool-Ergebnisses wird Claude diese Informationen verwenden, um eine Antwort auf die ursprüngliche Benutzeraufforderung zu generieren.

Behandlung von Ergebnissen aus Server-Tools

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

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-Use-Block enthält, musst du die Anfrage mit einem höheren max_tokens Wert erneut versuchen, um den vollständigen Tool-Use zu erhalten.

Behandlung des pause_turn Stop-Grundes

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

Hier ist, wie man den pause_turn Stop-Grund behandelt:

Bei der Behandlung von pause_turn:

• Setze die Konversation fort: Übergebe die pausierte Antwort wie sie ist in einer nachfolgenden Anfrage, um Claude seinen Zug fortsetzen zu lassen
• Modifiziere bei Bedarf: Du kannst den Inhalt optional vor der Fortsetzung modifizieren, wenn du die Konversation unterbrechen oder umleiten möchtest
• Bewahre den Tool-Status: Füge die gleichen Tools in die Fortsetzungsanfrage ein, um die Funktionalität zu erhalten

Fehlerbehebung

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

Dies ist korrekt:

Wenn du einen Fehler wie „tool_use ids were found without tool_result blocks immediately after" erhältst, überprüfe, dass deine Tool-Ergebnisse korrekt formatiert sind.