Wie man Tool-Nutzung implementiert
Leitfaden zur Implementierung von Tool-Nutzung mit Claude, einschließlich Modellauswahl, Tool-Definitionen und Behandlung von Antworten.
Ein Modell auswählen
Verwenden Sie generell 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; sie handhaben mehrere Tools besser und suchen bei Bedarf Klarstellung.
Verwenden Sie Claude Haiku 3.5 oder Claude Haiku 3 für einfache Tools, beachten Sie jedoch, dass sie möglicherweise fehlende Parameter ableiten.
Wenn Sie Claude Sonnet 3.7 mit Tool-Nutzung und erweitertem Denken verwenden, lesen Sie unseren Leitfaden hier für weitere Informationen.
Client-Tools spezifizieren
Client-Tools (sowohl von Anthropic definierte als auch benutzerdefinierte) werden im tools
Top-Level-Parameter der API-Anfrage spezifiziert. Jede Tool-Definition umfasst:
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. |
Tool-Nutzung System-Prompt
Wenn Sie die Anthropic 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:
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, wann und wie sie zu verwenden sind. 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 zu haben. Fügen Sie nur Beispiele hinzu, nachdem Sie die Beschreibung vollständig ausgearbeitet haben.
Die gute Beschreibung erklärt klar, 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 über das Verhalten und die Verwendung des Tools zurück.
Claudes Ausgabe kontrollieren
Tool-Nutzung erzwingen
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:
Bei der Arbeit mit dem tool_choice Parameter haben wir vier mögliche Optionen:
auto
erlaubt Claude zu entscheiden, ob es bereitgestellte Tools aufruft oder nicht. Dies ist der Standardwert, wenntools
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 keinetools
bereitgestellt werden.
Bei der Verwendung von Prompt-Caching werden Änderungen am tool_choice
Parameter zwischengespeicherte Nachrichtenblöcke ungültig machen. Tool-Definitionen und System-Prompts bleiben zwischengespeichert, aber Nachrichteninhalte müssen erneut verarbeitet werden.
Dieses Diagramm veranschaulicht, wie jede Option funktioniert:
Beachten Sie, dass wenn Sie tool_choice
als any
oder tool
haben, wir die Assistentennachricht vorab ausfü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, auch wenn explizit darum gebeten wird.
Bei der Verwendung von erweitertem Denken mit Tool-Nutzung werden tool_choice: {"type": "any"}
und tool_choice: {"type": "tool", "name": "..."}
nicht unterstützt und führen zu einem Fehler. Nur tool_choice: {"type": "auto"}
(der Standard) und tool_choice: {"type": "none"}
sind mit erweitertem Denken kompatibel.
Unsere Tests haben gezeigt, dass dies die Leistung nicht reduzieren sollte. Wenn Sie Chain-of-Thought (besonders mit Opus) beibehalten möchten, während Sie trotzdem 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: 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.
Chain of Thought
Bei der Verwendung von Tools zeigt Claude oft seine “Chain of Thought”, 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 Tool-Nutzung erzwingen), und Sonnet und Haiku können dazu aufgefordert werden.
Zum Beispiel, bei dem Prompt “Wie ist das Wetter in San Francisco gerade jetzt, und wie spät ist es dort?”, könnte Claude mit folgendem antworten:
Diese Chain of Thought gibt Einblick in Claudes Denkprozess und kann Ihnen helfen, unerwartetes Verhalten zu debuggen.
Mit dem Claude Sonnet 3 Modell ist Chain of Thought standardmäßig weniger häufig, aber Sie können Claude dazu auffordern, seine Argumentation zu zeigen, indem Sie etwas wie "Bevor Sie antworten, erklären Sie Ihre Argumentation Schritt für Schritt in Tags."
zur Benutzernachricht oder zum System-Prompt hinzufügen.
Es ist wichtig zu beachten, dass obwohl die <thinking>
Tags eine gängige Konvention sind, die Claude verwendet, um seine Chain of Thought zu kennzeichnen, das genaue Format (wie z.B. wie dieser XML-Tag benannt ist) sich im Laufe der Zeit ändern kann. Ihr Code sollte die Chain of Thought wie jeden anderen 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. Sie können dieses Verhalten deaktivieren, indem Sie:
disable_parallel_tool_use=true
setzen, wenn tool_choice Typauto
ist, was sicherstellt, dass Claude höchstens ein Tool verwendetdisable_parallel_tool_use=true
setzen, wenn tool_choice Typany
odertool
ist, was sicherstellt, dass Claude genau ein Tool verwendet
Parallele Tool-Nutzung maximieren
Während Claude 4 Modelle standardmäßig ausgezeichnete Fähigkeiten für parallele Tool-Nutzung haben, können Sie die Wahrscheinlichkeit paralleler Tool-Ausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:
Parallele Tool-Nutzung mit Claude Sonnet 3.7
Claude Sonnet 3.7 macht möglicherweise weniger wahrscheinlich parallele Tool-Aufrufe in einer Antwort, auch wenn Sie disable_parallel_tool_use
nicht gesetzt haben. Um dies zu umgehen, empfehlen wir, token-effiziente Tool-Nutzung zu aktivieren, was hilft, Claude zu ermutigen, parallele Tools zu verwenden. Diese Beta-Funktion reduziert auch die Latenz und spart durchschnittlich 14% bei Ausgabe-Tokens.
Wenn Sie es vorziehen, nicht in die token-effiziente Tool-Nutzung Beta einzusteigen, können Sie auch ein “Batch-Tool” einführen, das als Meta-Tool fungieren kann, um Aufrufe an andere Tools gleichzeitig zu umhüllen. Wir stellen fest, dass wenn dieses Tool vorhanden ist, das Modell es verwenden wird, um mehrere Tools gleichzeitig parallel für Sie aufzurufen.
Siehe dieses Beispiel in unserem Cookbook für die Verwendung dieser Umgehung.
Behandlung von Tool-Nutzung und Tool-Ergebnis-Inhaltsblöcken
Claudes Antwort unterscheidet sich je nachdem, ob es ein Client- oder Server-Tool verwendet.
Behandlung von 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
: Ein eindeutiger Identifikator für diesen bestimmten Tool-Nutzungsblock. Dieser wird verwendet, um die Tool-Ergebnisse später zuzuordnen.name
: Der Name des verwendeten Tools.input
: Ein Objekt, das die Eingabe enthält, die an das Tool weitergegeben wird, entsprechend deminput_schema
des Tools.
Wenn Sie eine Tool-Nutzungsantwort für ein Client-Tool erhalten, sollten Sie:
- Den
name
,id
undinput
aus demtool_use
Block extrahieren. - Das tatsächliche Tool in Ihrer Codebasis ausführen, das diesem Tool-Namen entspricht, und die Tool-
input
übergeben. - Die Unterhaltung fortsetzen, indem Sie eine neue Nachricht mit der
role
vonuser
und einemcontent
Block senden, 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 Grad"
) oder Liste von verschachtelten Inhaltsblöcken (z.B."content": [{"type": "text", "text": "15 Grad"}]
). Diese Inhaltsblöcke können die Typentext
oderimage
verwenden.is_error
(optional): Auftrue
setzen, wenn die Tool-Ausführung zu einem Fehler führte.
Wichtige Formatierungsanforderungen:
- Tool-Ergebnisblöcke müssen unmittelbar auf ihre entsprechenden Tool-Nutzungsblöcke in der Nachrichtenhistorie folgen. Sie können keine Nachrichten zwischen der Assistenten-Tool-Nutzungsnachricht und der Benutzer-Tool-Ergebnisnachricht einschließen.
- In der Benutzernachricht, die Tool-Ergebnisse enthält, müssen die tool_result Blöcke ZUERST im content Array stehen. Jeder Text muss NACH allen Tool-Ergebnissen kommen.
Zum Beispiel wird dies einen 400-Fehler verursachen:
Dies ist korrekt:
Wenn Sie einen Fehler wie “tool_use ids were found without tool_result blocks immediately after” erhalten, überprüfen Sie, ob Ihre Tool-Ergebnisse korrekt formatiert sind.
Nach Erhalt des Tool-Ergebnisses wird Claude diese Information verwenden, um weiterhin eine Antwort auf den ursprünglichen Benutzer-Prompt zu generieren.
Behandlung von 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.
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.
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-Nutzungsblock enthält, müssen Sie die Anfrage mit einem höheren max_tokens
Wert wiederholen, um die vollständige Tool-Nutzung zu erhalten.
Behandlung des pause_turn
Stop-Grundes
Bei der Verwendung von Server-Tools wie Web-Suche kann die API einen pause_turn
Stop-Grund zurückgeben, der anzeigt, dass die API einen lang laufenden Turn pausiert hat.
So behandeln Sie den pause_turn
Stop-Grund:
Bei der Behandlung von pause_turn
:
- Unterhaltung 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 die Unterhaltung 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: