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 imtools 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 Klartext-Beschreibung 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. |
Beispiel einer einfachen Tool-Definition
Beispiel einer einfachen Tool-Definition
get_weather erwartet ein Eingabeobjekt mit einem erforderlichen location String und einem optionalen unit String, der entweder “celsius” oder “fahrenheit” sein muss.Tool-Nutzung System-Prompt
Wenn Sie die Claude API mit demtools 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 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.
Beispiel einer guten Tool-Beschreibung
Beispiel einer guten Tool-Beschreibung
Beispiel einer schlechten Tool-Beschreibung
Beispiel einer schlechten Tool-Beschreibung
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 imtool_choice Feld wie folgt spezifizieren:
autoerlaubt Claude zu entscheiden, ob bereitgestellte Tools aufgerufen werden sollen oder nicht. Dies ist der Standardwert, wenntoolsbereitgestellt werden.anyteilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss, aber kein bestimmtes Tool erzwingt.toolerlaubt es uns, Claude zu zwingen, immer ein bestimmtes Tool zu verwenden.noneverhindert, dass Claude Tools verwendet. Dies ist der Standardwert, wenn keinetoolsbereitgestellt werden.
tool_choice Parameter zwischengespeicherte Nachrichtenblöcke ungültig machen. Tool-Definitionen und System-Prompts bleiben zwischengespeichert, aber Nachrichteninhalte müssen erneut verarbeitet werden.
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.
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.{"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 einrecord_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:<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=truesetzen, wenn tool_choice typeautoist, was sicherstellt, dass Claude höchstens ein Tool verwendetdisable_parallel_tool_use=truesetzen, wenn tool_choice typeanyodertoolist, was sicherstellt, dass Claude genau ein Tool verwendet
Vollständiges Beispiel für parallele Tool-Nutzung
Vollständiges Beispiel für parallele Tool-Nutzung
Vollständiges Testskript für parallele Tools
Vollständiges Testskript für parallele Tools
- Wie parallele Tool-Aufrufe und Ergebnisse korrekt formatiert werden
- Wie überprüft wird, dass parallele Aufrufe gemacht werden
- Die korrekte Nachrichtenstruktur, die zukünftige parallele Tool-Nutzung fördert
- Häufige Fehler, die vermieden werden sollten (wie Text vor Tool-Ergebnissen)
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:System-Prompts für parallele Tool-Nutzung
System-Prompts für parallele Tool-Nutzung
Benutzer-Nachrichten-Prompting
Benutzer-Nachrichten-Prompting
disable_parallel_tool_use nicht gesetzt haben. Um dies zu umgehen, empfehlen wir die Aktivierung der token-effizienten Tool-Nutzung, die 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, sich nicht für die token-effiziente Tool-Nutzung Beta anzumelden, 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 gleichzeitig mehrere Tools parallel für Sie aufzurufen.Siehe dieses Beispiel in unserem Cookbook für die Verwendung dieser Umgehungslösung.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 einenstop_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 deminput_schemades Tools.
Beispiel API-Antwort mit einem `tool_use` Inhaltsblock
Beispiel API-Antwort mit einem `tool_use` Inhaltsblock
- Den
name, dieidund dieinputaus demtool_useBlock extrahieren. - Das tatsächliche Tool in Ihrer Codebasis ausführen, das diesem Tool-Namen entspricht, und die Tool-
inputübergeben. - Das Gespräch fortsetzen, indem Sie eine neue Nachricht mit der
rolevonuserund einemcontentBlock senden, der dentool_resultTyp und die folgenden Informationen enthält:tool_use_id: Dieidder 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 Typentext,imageoderdocumentverwenden.is_error(optional): Auftruesetzen, wenn die Tool-Ausführung zu einem Fehler geführt hat.
- 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.
Beispiel eines erfolgreichen Tool-Ergebnisses
Beispiel eines erfolgreichen Tool-Ergebnisses
Beispiel eines Tool-Ergebnisses mit Bildern
Beispiel eines Tool-Ergebnisses mit Bildern
Beispiel eines leeren Tool-Ergebnisses
Beispiel eines leeren Tool-Ergebnisses
Beispiel eines Tool-Ergebnisses mit Dokumenten
Beispiel eines Tool-Ergebnisses mit Dokumenten
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.tool oder function verwenden, integriert die Claude 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 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.
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:
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:Tool-Ausführungsfehler
Tool-Ausführungsfehler
content zusammen mit "is_error": true zurückgeben:Ungültiger Tool-Name
Ungültiger Tool-Name
description Werten in Ihren Tool-Definitionen zu versuchen.Sie können jedoch auch das Gespräch mit einem tool_result fortsetzen, das den Fehler anzeigt, und Claude wird versuchen, das Tool erneut mit den fehlenden Informationen zu verwenden:<search_quality_reflection> Tags
<search_quality_reflection> Tags
Server-Tool-Fehler
Server-Tool-Fehler
is_error Ergebnisse für Server-Tools behandeln.Für Websuche speziell umfassen mögliche Fehlercodes:too_many_requests: Ratenlimit überschritteninvalid_input: Ungültiger Suchanfrage-Parametermax_uses_exceeded: Maximale Websuche-Tool-Nutzungen überschrittenquery_too_long: Anfrage überschreitet maximale Längeunavailable: Ein interner Fehler ist aufgetreten
Parallele Tool-Aufrufe funktionieren nicht
Parallele Tool-Aufrufe funktionieren nicht
- ❌ Falsch: Separate Benutzernachrichten für jedes Tool-Ergebnis senden
- ✅ Richtig: Alle Tool-Ergebnisse müssen in einer einzigen Benutzernachricht sein
- Claude Opus 4.1, Opus 4 und Sonnet 4: Exzellent bei paralleler Tool-Nutzung mit minimalem Prompting
- Claude Sonnet 3.7: Benötigt möglicherweise stärkeres Prompting oder token-effiziente Tool-Nutzung
- Claude Haiku: Weniger wahrscheinlich, parallele Tools ohne explizites Prompting zu verwenden