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.
Wenn du Claude Sonnet 3.7 mit Tool-Nutzung und erweitertem Denken verwendest, findest du weitere Informationen in unserem Leitfaden hier.
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:
Parameter | Beschreibung |
---|---|
name | Der Name des Tools. Muss dem Regex ^[a-zA-Z0-9_-]{1,64}$ entsprechen. |
description | Eine detaillierte Klartextbeschreibung dessen, was das Tool tut, wann es verwendet werden sollte und wie es sich verhält. |
input_schema | Ein JSON Schema-Objekt, das die erwarteten Parameter für das Tool definiert. |
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:
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:
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, wenntools
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 keinetools
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:
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-Typauto
ist, was sicherstellt, dass Claude höchstens ein Tool verwendetdisable_parallel_tool_use=true
setzt, wenn der tool_choice-Typany
odertool
ist, was sicherstellt, dass Claude genau ein Tool verwendet
Parallele Tool-Nutzung mit Claude Sonnet 3.7
Claude Sonnet 3.7 könnte weniger wahrscheinlich parallele Tool-Aufrufe in einer Antwort machen, selbst wenn du disable_parallel_tool_use
nicht gesetzt hast. Um dieses Problem zu umgehen, empfehlen wir, token-effiziente Tool-Nutzung zu aktivieren, was Claude dazu ermutigt, parallele Tools zu verwenden. Diese Beta-Funktion reduziert auch die Latenz und spart durchschnittlich 14% an Ausgabe-Tokens.
Wenn du es vorziehst, nicht in die Beta der token-effizienten Tool-Nutzung einzusteigen, kannst du auch ein “Batch-Tool” einführen, das als Meta-Tool fungieren kann, um Aufrufe an andere Tools gleichzeitig zu umschließen. Wir stellen fest, dass, wenn dieses Tool vorhanden ist, das Modell es verwenden wird, um mehrere Tools gleichzeitig parallel für dich aufzurufen.
Siehe dieses Beispiel in unserem Cookbook für die Verwendung dieses Workarounds.
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 deminput_schema
des Tools entspricht.
Wenn du eine Tool-Nutzungsantwort für ein Client-Tool erhältst, solltest du:
- Den
name
, dieid
und deninput
aus demtool_use
-Block extrahieren. - Das tatsächliche Tool in deinem Codebase ausführen, das diesem Tool-Namen entspricht, und dabei den Tool-
input
übergeben. - Das Gespräch fortsetzen, indem du eine neue Nachricht mit der
role
desuser
sendest und einencontent
-Block, der dentool_result
-Typ und die folgenden Informationen enthält:tool_use_id
: Dieid
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 Typentext
oderimage
verwenden.is_error
(optional): Auftrue
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.
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.
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:
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: