Implementierung von Tool-Nutzung

Auswahl eines Modells

Wir empfehlen die Verwendung des neuesten Claude Opus (4.6) Modells für komplexe Tools und mehrdeutige Anfragen; es verarbeitet mehrere Tools besser und sucht 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 Parameter tools auf oberster Ebene der API-Anfrage angegeben. Jede Tool-Definition enthält:

Tool-Nutzungs-Systemaufforderung

Wenn Sie die Claude API mit dem Parameter tools aufrufen, erstellen wir eine spezielle Systemaufforderung aus den Tool-Definitionen, der Tool-Konfiguration und einer beliebigen benutzerdefinierten Systemaufforderung. Die konstruierte Aufforderung ist so konzipiert, dass sie 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 entscheiden, 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 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 Parameter ticker 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 nutzen. Dies ist besonders nützlich für komplexe Tools mit verschachtelten Objekten, optionalen Parametern oder formatempfindlichen Eingaben.

Grundlegende Verwendung

Fügen Sie ein optionales Feld input_examples 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 in der Aufforderung neben Ihrem Tool-Schema enthalten und zeigen Claude konkrete Muster für wohlgeformte 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 verarbeiten, führt der Tool Runner automatisch:

• Tools aus, wenn Claude sie aufruft
• Verarbeitet 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.

Grundlegende Verwendung

Definieren Sie Tools mit den SDK-Helfern und verwenden Sie dann den Tool Runner, um sie auszuführen.

Die Tool-Funktion muss einen Content Block oder ein Content Block Array zurückgeben, einschließlich Text, Bilder oder Dokument-Blöcke. Dies ermöglicht Tools, umfangreiche, multimodale Antworten zurückzugeben. Zurückgegebene Zeichenketten werden in einen Text-Content Block konvertiert. Wenn Sie ein strukturiertes JSON-Objekt an Claude zurückgeben möchten, kodieren Sie es vor der Rückgabe als JSON-Zeichenkette. Zahlen, Boolesche Werte oder andere nicht-String-Primitive müssen ebenfalls in Zeichenketten konvertiert werden.

Iteration über den Tool Runner

Der Tool Runner ist ein Iterable, das Nachrichten von Claude liefert. Dies wird oft als "Tool-Call-Schleife" bezeichnet. Bei jeder Iteration prüft der Runner, ob Claude eine Tool-Nutzung angefordert hat. Wenn ja, ruft er das Tool auf und sendet das Ergebnis automatisch an Claude zurück, dann liefert er die nächste Nachricht von Claude, um Ihre Schleife fortzusetzen.

Sie können die Schleife bei jeder Iteration mit einer break-Anweisung beenden. Der Runner wird in einer Schleife ausgeführt, bis Claude eine Nachricht ohne Tool-Nutzung zurückgibt.

Wenn Sie keine Zwischennachrichten benötigen, können Sie die endgültige Nachricht direkt abrufen:

Erweiterte Verwendung

Innerhalb der Schleife können Sie die nächste Anfrage des Tool Runners an die Messages API vollständig anpassen. Der Runner hängt automatisch Tool-Ergebnisse an die Nachrichtenhistorie an, sodass Sie diese nicht manuell verwalten müssen. Sie können das Tool-Ergebnis optional für Protokollierung oder Debugging inspizieren und die Request-Parameter vor dem nächsten API-Aufruf ändern.

Debugging der Tool-Ausführung

Wenn ein Tool eine Ausnahme auslöst, fängt der Tool Runner sie ab und gibt den Fehler an Claude als Tool-Ergebnis mit is_error: true zurück. Standardmäßig ist nur die Ausnahmemeldung enthalten, nicht die vollständige Stack-Spur.

Um vollständige Stack-Spuren und Debug-Informationen anzuzeigen, setzen Sie die Umgebungsvariable ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Wenn aktiviert, protokolliert das SDK vollständige Ausnahmeergebnisse (mit Pythons logging Modul, der Konsole in TypeScript oder Rubys Logger), einschließlich der vollständigen Stack-Spur, wenn ein Tool fehlschlägt.

Abfangen von Tool-Fehlern

Standardmäßig werden Tool-Fehler an Claude zurückgegeben, das dann angemessen antworten kann. Sie möchten jedoch möglicherweise Fehler erkennen und anders verarbeiten – zum Beispiel, um die Ausführung früh zu beenden oder benutzerdefinierte Fehlerbehandlung zu implementieren.

Verwenden Sie die Tool-Response-Methode, um Tool-Ergebnisse abzufangen und auf Fehler zu prüfen, bevor sie an Claude gesendet werden:

Ändern von Tool-Ergebnissen

Sie können Tool-Ergebnisse ändern, bevor sie an Claude zurückgesendet werden. Dies ist nützlich, um Metadaten wie cache_control hinzuzufügen, um Prompt-Caching auf Tool-Ergebnisse zu aktivieren, oder um die Tool-Ausgabe zu transformieren.

Verwenden Sie die Tool-Response-Methode, um das Tool-Ergebnis zu erhalten, es zu ändern und dann Ihre geänderte Version zu den Nachrichten hinzuzufügen:

Streaming

Aktivieren Sie Streaming, um Ereignisse zu empfangen, wenn sie ankommen. Jede Iteration liefert ein Stream-Objekt, das Sie für Ereignisse iterieren können.

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

tool_choice = {"type": "tool", "name": "get_weather"}

Bei der Arbeit mit dem Parameter tool_choice 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 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 beeinträchtigen sollte. Wenn Sie möchten, dass das Modell natürlichsprachigen Kontext oder Erklärungen bereitstellt, 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-Ausgaben zurückgibt, die einem bereitgestellten Schema entsprechen. Beispielsweise könnten Sie ein record_summary-Tool mit einem bestimmten Schema verwenden. Siehe Tool-Verwendung 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": "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 System-Prompts und durch die Bereitstellung von <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 vom Assistenten generierten Text behandeln und sich nicht auf spezifische Formatierungskonventionen verlassen.

Parallele Tool-Verwendung

Standardmäßig kann Claude mehrere Tools 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 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-Verwendung

Während Claude 4-Modelle standardmäßig hervorragende Funktionen zur parallelen Tool-Verwendung haben, können Sie die Wahrscheinlichkeit einer parallelen Tool-Ausführung über alle Modelle hinweg mit gezieltem Prompting erhöhen:

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

Claudes Antwort unterscheidet sich je nachdem, ob es ein Client-Tool oder ein 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 Sie eine Tool-Use-Antwort für ein Client-Tool erhalten, sollten Sie:

1. Extrahieren Sie name, id und input aus dem tool_use-Block.
2. Führen Sie das tatsächliche Tool in Ihrer Codebasis aus, das diesem Tool-Namen entspricht, und übergeben Sie die Tool-input.
3. Setzen Sie das Gespräch fort, indem Sie eine neue Nachricht mit der role von user und einem content-Block mit dem tool_result-Typ und den folgenden Informationen senden:
   • 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": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Nach Erhalt des Tool-Ergebnisses wird Claude diese Informationen verwenden, um die Antwort auf die ursprüngliche Benutzer-Eingabeaufforderung fortzusetzen.

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, müssen Sie die Anfrage mit einem höheren max_tokens-Wert erneut versuchen, um die vollständige Tool-Verwendung 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 Durchgang unterbrochen hat.

So behandeln Sie den pause_turn Stop-Grund:

Bei der Behandlung von pause_turn:

• Setzen Sie das Gespräch fort: Übergeben Sie die unterbrochene Antwort in einer nachfolgenden Anfrage unverändert, um Claude seinen Durchgang fortsetzen zu lassen
• Ändern Sie bei Bedarf: Sie können den Inhalt optional vor dem Fortsetzen ändern, wenn Sie das Gespräch unterbrechen oder umleiten möchten
• Bewahren Sie den Tool-Status: Fügen Sie die gleichen Tools in die Fortsetzungsanfrage ein, um die Funktionalität beizubehalten

Fehlerbehebung

Es gibt verschiedene Arten von Fehlern, die bei der Verwendung von Tools 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 Tool-Ergebnisse richtig formatiert sind.