View a markdown version of this page

Verwendung von Werkzeugen von Anthropic Claude - Amazon Bedrock

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Verwendung von Werkzeugen von Anthropic Claude

Warnung

Einige der folgenden Funktionen werden, wie angegeben, in der Betaversion angeboten. Diese Funktionen werden Ihnen als „Beta-Service“ gemäß der Definition in den AWS Servicebedingungen zur Verfügung gestellt. Sie unterliegt Ihrer Vereinbarung mit AWS und den AWS Servicebedingungen sowie der jeweiligen Muster-EULA.

Bei Anthropic-Claude-Modellen können Sie ein Tool angeben, mit dem das Modell eine Nachricht beantworten kann. Sie könnten beispielsweise ein Tool angeben, das den beliebtesten Song eines Radiosenders ermittelt. Wenn der Benutzer die Nachricht weitergibt Was ist der beliebteste Song bei WZPZ?, stellt das Modell fest, dass das von Ihnen angegebene Tool bei der Beantwortung der Frage helfen kann. In seiner Antwort fordert das Modell Sie auf, das Tool in seinem Namen auszuführen. Anschließend führen Sie das Tool aus und übergeben das Tool-Ergebnis an das Modell, das dann eine Antwort für die ursprüngliche Nachricht generiert. Weitere Informationen finden Sie unter Verwendung des Tools (Funktionsaufruf) in der Anthropic-Claude-Dokumentation.

Tipp

Es wird empfohlen, die Converse-API zur Integration der Tool-Nutzung in Ihre Anwendung zu verwenden. Weitere Informationen finden Sie unter Verwenden eines Tools, um eine Amazon-Bedrock-Modellantwort zu vervollständigen.

Wichtig

Claude Sonnet 4.5 behält jetzt die absichtliche Formatierung der Zeichenfolgenparameter für Tool-Aufrufe bei. Bisher wurden nachfolgende Zeilenumbrüche in Zeichenfolgenparametern manchmal fälschlicherweise entfernt. Mit dieser Korrektur wird sichergestellt, dass Tools, die eine genaue Formatierung erfordern (wie Text-Editoren), Parameter genau wie vorgesehen erhalten. Dies ist eine Verbesserung im Hintergrund, für die keine API-Änderungen erforderlich sind. Tools mit Zeichenfolgenparametern können jetzt jedoch Werte mit abschließenden Zeilenumbrüchen empfangen, die zuvor entfernt wurden.

Anmerkung

Claude Sonnet 4.5 beinhaltet automatische Optimierungen zur Verbesserung der Modellleistung. Durch diese Optimierungen können Anfragen kleine Mengen an Token hinzugefügt werden. Diese vom System hinzugefügten Token werden Ihnen jedoch nicht in Rechnung gestellt.

Sie geben die Tools, die Sie einem Modell zur Verfügung stellen möchten, im Feld tools an. Das folgende Beispiel bezieht sich auf ein Tool, das den beliebtesten Song eines Radiosenders ermittelt.

[ { "name": "top_song", "description": "Get the most popular song played on a radio station.", "input_schema": { "type": "object", "properties": { "sign": { "type": "string", "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP." } }, "required": [ "sign" ] } } ]

Wenn das Modell ein Tool benötigt, um eine Antwort auf eine Nachricht zu generieren, gibt es Informationen über das angeforderte Tool und die Eingabe für das Tool im content-Nachrichtenfeld zurück. Außerdem wird der Grund für den Stopp der Antwort auf tool_use festgelegt.

{ "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx", "type": "message", "role": "assistant", "model": "claude-3-sonnet-20240229", "stop_sequence": null, "usage": { "input_tokens": 375, "output_tokens": 36 }, "content": [ { "type": "tool_use", "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy", "name": "top_song", "input": { "sign": "WZPZ" } } ], "stop_reason": "tool_use" }

In Ihrem Code rufen Sie das Tool im Namen des Tools auf. Anschließend übergeben Sie das Tool-Ergebnis (tool_result) in einer Benutzernachricht an das Modell.

{ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy", "content": "Elemental Hotel" } ] }

In seiner Antwort verwendet das Modell das Tool-Ergebnis, um eine Antwort auf die ursprüngliche Nachricht zu generieren.

{ "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP", "type": "message", "role": "assistant", "model": "claude-3-sonnet-20240229", "content": [ { "type": "text", "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"." } ], "stop_reason": "end_turn" }

Fine-grained Werkzeug-Streaming

Fine-grained Werkzeug-Streaming ist eine Anthropic Claude Modellfunktion, die mit Claude Sonnet 4.5 Claude Haiku 4.5Claude Sonnet 4, und Claude Opus 4 verfügbar ist. Mit differenziertem Tool-Streaming können Claude-Entwickler Parameter für die Verwendung von Tools ohne Pufferung oder JSON-Validierung streamen, wodurch die Latenz beim Empfang großer Parameter reduziert wird.

Anmerkung

Wenn Sie differenziertes Tool-Streaming verwenden, erhalten Sie möglicherweise ungültige oder unvollständige JSON-Eingaben. Bitte achten Sie darauf, diese Grenzfälle in Ihrem Code zu berücksichtigen.

Wenn Sie dieses Feature nutzen möchten, fügen Sie einfach den Header fine-grained-tool-streaming-2025-05-14 zu einer Anfrage zur Verwendung eines Tools hinzu.

Hier ist ein Beispiel dafür, wie der Header beim differenzierten Tool-Streaming angegeben werden kann:

{ "anthropic_version": "bedrock-2023-05-31", "max_tokens": 1024, "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"], "messages": [ { "role": "user", "content": "Can you write a long poem and make a file called poem.txt?" } ], "tools": [ { "name": "make_file", "description": "Write text to a file", "input_schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The filename to write text to" }, "lines_of_text": { "type": "array", "description": "An array of lines of text to write to the file" } }, "required": [ "filename", "lines_of_text" ] } } ] }

In diesem Beispiel ermöglicht es Claude durch differenziertes Tool-Streaming, die Zeilen eines langen Gedichts ohne Pufferung in den Tool-Aufruf make_file zu streamen, um zu überprüfen, ob es sich bei dem Parameter lines_of_text um einen gültigen JSON-Wert handelt. Das bedeutet, dass Sie den Parameter-Stream sehen können, sobald er eingeht, ohne darauf warten zu müssen, dass der gesamte Parameter gepuffert und validiert ist.

Bei differenziertem Tool-Streaming beginnen die Chunks, die das Tool verwenden, schneller zu streamen. Sie sind oft länger und enthalten weniger Wortumbrüche. Dies ist auf Unterschiede im Chunking-Verhalten zurückzuführen.

Ein Beispiel ohne differenziertes Streaming (Verzögerung von 15 Sekunden):

Chunk 1: '{"' Chunk 2: 'query": "Ty' Chunk 3: 'peScri' Chunk 4: 'pt 5.0 5.1 ' Chunk 5: '5.2 5' Chunk 6: '.3' Chunk 8: ' new f' Chunk 9: 'eatur' ...

Mit differenziertem Streaming (3 Sekunden Verzögerung):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3' Chunk 2: ' new features comparison'
Anmerkung

Da beim differenzierten Streaming Parameter ohne Pufferung oder JSON-Validierung gesendet werden, gibt es keine Garantie dafür, dass der resultierende Stream in einer gültigen JSON-Zeichenfolge abgeschlossen wird. Insbesondere wenn der Stopp-Grund max_tokens erreicht ist, kann es sein, dass der Stream nach der Hälfte eines Parameters endet und unvollständig ist. In der Regel müssen Sie spezielle Support-Programme schreiben, um zu regeln, was passiert, wenn der Wert erreicht max_tokens ist.

Computer Use (Beta)

Computer Use ist eine Anthropic Claude Toolfamilie (in der Betaversion) zur Automatisierung von Aufgaben auf der grafischen Benutzeroberfläche (GUI). Eine Übersicht, die Bedrock-specific Amazon-Anforderungsform und ein durchgängiges Beispiel finden Sie unterVerwenden Sie Tools zur Computernutzung, um GUI-Aufgaben mit Amazon Bedrock-Modellen zu automatisieren. Informationen darüber, welche Modelle die Computernutzung an den einzelnen Endpunkten unterstützen, finden Sie in der jeweiligen Tabelle mit Funktionen und FunktionenModelle im Überblick.

Um die Computernutzung auf Anfrage anthropic_beta zu aktivieren, legen Sie eine Version für die Computernutzung fest und fügen Sie einen Tooleintrag hinzu, der dieser Version type entspricht. Die gültigen Kombinationen sind:

Beta-Header Typ des Computerwerkzeugs
computer-use-2025-11-24 computer_20251124
computer-use-2025-01-24 computer_20250124
computer-use-2024-10-22 computer_20241022

Jeder Werkzeugtyp funktioniert nur mit einer bestimmten Teilmenge von Modellen. Beim Senden eines Werkzeugtyps, den ein Modell nicht unterstützt, wird eine Meldung 400 invalid_request_error mit einer Meldung wie 'claude-opus-4-7' does not support tool types: computer_20241022 zurückgegeben. Bestätigen Sie die Unterstützung in der Tabelle mit den Funktionen und Funktionen des Modells, bevor Sie Anfragen senden.

Das zugrundeliegende Werkzeugprotokoll, das vollständige Aktionsvokabular und Anleitungen zum Prompt-Engineering finden Sie in der Anthropic Dokumentation unter Computernutzung.

Anthropic definierte Werkzeuge

Anthropicstellt eine Reihe vordefinierter Tools bereit, die Claude Modelle für die Interaktion mit Computern verwenden können. Bei der Angabe eines Anthropic -definierten Werkzeugs sind die tool_schema Felder description und nicht erforderlich oder zulässig. Das Modell führt diese Werkzeuge nicht automatisch aus. Sie müssen jede angeforderte Aktion ausführen und a tool_result an Claude zurückgeben. Informationen darüber, welche dieser Werkzeuge jedes Modell akzeptiert, finden Sie in der Tabelle mit Funktionen und Funktionen in der Tabelle des Modelle im Überblick Modells. Wenn Sie einen Werkzeugtyp eingeben, den ein Modell nicht unterstützt, wird a zurückgegeben400 invalid_request_error.

Tool

Hinweise

{ "type": "computer_20251124", "name": "computer" }

Neuestes Tool zur Verwendung am Computer. Mit "anthropic_beta": ["computer-use-2025-11-24"] verwenden.

{ "type": "computer_20250124", "name": "computer" }

Mit "anthropic_beta": ["computer-use-2025-01-24"] verwenden.

{ "type": "computer_20241022", "name": "computer" }

Vermächtnis. Mit "anthropic_beta": ["computer-use-2024-10-22"] verwenden.

{ "type": "text_editor_20250124", "name": "str_replace_based_edit_tool" }

Aktualisieren Sie das vorhandene str_replace_editor Tool. Verwenden Sie mit "anthropic_beta": ["computer-use-2025-01-24"] oder["computer-use-2025-11-24"].

{ "type": "text_editor_20241022", "name": "str_replace_editor" }

Vermächtnis. Mit "anthropic_beta": ["computer-use-2024-10-22"] verwenden.

{ "type": "bash_20250124", "name": "bash" }

Verwenden Sie mit "anthropic_beta": ["computer-use-2025-01-24"] oder["computer-use-2025-11-24"].

{ "type": "bash_20241022", "name": "bash" }

Vermächtnis. Mit "anthropic_beta": ["computer-use-2024-10-22"] verwenden.

Das type Feld identifiziert das Werkzeug und seine Parameter für Validierungszwecke; das name Feld ist der Werkzeugname, der dem Modell zur Verfügung gestellt wird.

Wenn Sie das Modell auffordern möchten, eines dieser Tools zu verwenden, können Sie das Tool explizit anhand des Felds name referenzieren. Das name Feld muss in der Werkzeugliste eindeutig sein. Sie können kein Werkzeug definieren, das mit einem Anthropic -definierten Werkzeug im selben API-Aufruf identisch ist. name

Automatisches Löschen von Tool-Aufrufen (Beta)

Warnung

Das automatische Löschen von Toolaufrufen wird gemäß der Definition in den Servicebedingungen als „ AWS Beta-Service“ zur Verfügung gestellt.

Anmerkung

Diese Funktion wird derzeit von Claude Sonnet 4/4 3.5, Claude Haiku 4.5 und Claude Opus unterstützt. 4/4 1/43.5.

Das automatische Löschen von Toolaufrufen ist eine Funktion des Modells Anthropic Claude (in der Betaversion). Mit dieser Funktion kann Claude die Ergebnisse der Verwendung alter Tools automatisch löschen, wenn Sie sich den Token-Limits nähern. Dies ermöglicht ein effizienteres Kontextmanagement in Szenarien, in denen Tools mit mehreren Umdrehungen verwendet werden. Wenn Sie das Löschen von Tool-Aufrufen nutzen möchten, müssen Sie dem Anforderungsparameter anthropic_beta in der Liste der Beta-Header context-management-2025-06-27 hinzufügen. Sie müssen außerdem die Verwendung der folgenden Konfigurationsoptionen angeben clear_tool_uses_20250919 und eine der folgenden Optionen auswählen.

Dies sind die verfügbaren Steuerelemente für die Kontextmanagement-Strategie von clear_tool_uses_20250919. Alle sind optional oder haben Standardwerte:

Konfigurationsoption Beschreibung

trigger

Standard: 100 000 Eingabe-Token

Definiert, wann die Strategie zur Kontextbearbeitung aktiviert wird. Sobald der Prompt diesen Schwellenwert überschreitet, beginnt der Löschvorgang. Sie können diesen Wert entweder in input_tokens oder tool_uses angeben.

keep

Standard: 3 Tool-Anwendungen

Definiert, wie viele aktuelle use/result Werkzeugpaare nach dem Löschen beibehalten werden sollen. Die API entfernt zuerst die ältesten Tool-Interaktionen, wobei die neuesten beibehalten werden. Dies ist hilfreich, wenn das Modell Zugriff auf die letzten Tool-Interaktionen benötigt, um die Konversation effektiv fortzusetzen.

clear_at_least (optional)

Dadurch wird sichergestellt, dass bei jeder Aktivierung der Strategie eine Mindestanzahl an Token gelöscht wird. Wenn die API nicht mindestens die angegebene Menge löschen kann, wird die Strategie nicht angewendet. Dies ist nützlich, um festzustellen, ob es sich lohnt, den Prompt-Cache für das Löschen von Kontexten zu unterbrechen.

exclude_tools (optional)

Liste der Tool-Namen, deren Tool-Anwendungen und Ergebnisse niemals gelöscht werden sollten. Dies ist nützlich, um wichtigen Kontext zu bewahren.

clear_tool_inputs: (optional, Standard falsch)

Steuert, ob die Tool-Aufruf-Parameter zusammen mit den Tool-Ergebnissen gelöscht werden. Standardmäßig werden nur die Tool-Ergebnisse gelöscht, wobei die ursprünglichen Tool-Aufrufe von Claude sichtbar bleiben, sodass Claude auch nach dem Entfernen der Ergebnisse sehen kann, welche Operationen ausgeführt wurden.

Anmerkung

Durch das Löschen von Tools wird Ihr Cache ungültig, wenn Ihre Präfixe Ihre Tools enthalten.

Wichtig

Das web_search_20250305 Anthropic-Servertool wird auf Amazon Bedrock nicht unterstützt.

Request
from anthropic import AnthropicBedrock client = AnthropicBedrock() response = client.beta.messages.create( betas=["context-management-2025-06-27"], model="claude-sonnet-4-20250514", max_tokens=4096, messages=[ { "role": "user", "content": "Create a simple command line calculator app using Python" } ], tools=[ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000 } ], extra_body={ "context_management": { "edits": [ { "type": "clear_tool_uses_20250919", # The below parameters are OPTIONAL: # Trigger clearing when threshold is exceeded "trigger": { "type": "input_tokens", "value": 30000 }, # Number of tool uses to keep after clearing "keep": { "type": "tool_uses", "value": 3 }, # Optional: Clear at least this many tokens "clear_at_least": { "type": "input_tokens", "value": 5000 }, # Exclude these tools uses from being cleared "exclude_tools": ["str_replace_based_edit_tool"] } ] } } )
Response
{ "id": "msg_123", "type": "message", "role": "assistant", "content": [ { "type": "tool_use", "id": "toolu_456", "name": "data_analyzer", "input": { "data": "sample data" } } ], "context_management": { "applied_edits": [ { "type": "clear_tool_uses_20250919", "cleared_tool_uses": 8, # Number of tool use/result pairs that were cleared "cleared_input_tokens": 50000 # Total number of input tokens removed from the prompt } ] } "stop_reason": "tool_use", "usage": { "input_tokens": 150, "output_tokens": 50 } }
Streaming Response
data: {"type": "message_start", "message": {"id": "msg_123", "type": "message", "role": "assistant"}} data: {"type": "content_block_start", "index": 0, "content_block": {"type": "tool_use", "id": "toolu_456", "name": "data_analyzer", "input": {}}} data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": "{\"data\": \"sample"}} data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": " data\"}"}} data: {"type": "content_block_stop", "index": 0} data: {"type": "message_delta", "delta": {"stop_reason": "tool_use"}} data: {"type": "message_stop"} { "type": "message_delta", "delta": { "stop_reason": "end_turn", "stop_sequence": null, }, "usage": { "output_tokens": 1024 }, "context_management": { "applied_edits": [...], } }
Anmerkung

Bedrock unterstützt derzeit kein clear_tool_uses_20250919 Kontextmanagement auf der API. CountTokens

Speicher-Tool (Beta)

Warnung

Memory Tool wird wie in den Servicebedingungen definiert als „Beta-Service“ zur AWS Verfügung gestellt.

Claude Sonnet 4.5 enthält ein neues Speicher-Tool. Dieses Tool bietet Ihnen die Möglichkeit, das Gedächtnis aller Konversationen zu verwalten. Mit dieser Funktion können Sie Claude erlauben, Informationen außerhalb des Kontextfensters abzurufen, indem Sie Zugriff auf ein lokales Verzeichnis gewähren. Diese Funktion ist in der Betaversion verfügbar. Um diese Funktion verwenden zu können, müssen Sie sie context-management-2025-06-27 in den anthropic_beta Parameter aufnehmen.

Tool-Definition:

{ "type": "memory_20250818", "name": "memory" }

Beispielanforderung:

{ "max_tokens": 2048, "anthropic_version": "bedrock-2023-05-31", "anthropic_beta": ["context-management-2025-06-27"], "tools": [{ "type": "memory_20250818", "name": "memory" }], "messages": [ { "role": "user", "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}] } ] }

Beispielantwort:

{ "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd", "type": "message", "role": "assistant", "model": "claude-sonnet-4-20250514", "content": [ { "type": "text", "text": "I'll start by checking your memory directory and then record this important information about you." }, { "type": "tool_use", "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB", "name": "memory", "input": { "command": "view", "path": "/memories" } } ], "stop_reason": "tool_use", "stop_sequence": null, "usage": { "input_tokens": 1403, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 87 }, "context_management": { "applied_edits": [] } }

Überlegungen zu den Kosten bei der Tool-Nutzung

Die Preise für Anfragen zur Nutzung von Tools basieren auf folgenden Faktoren:

  1. Die Gesamtzahl der an das Modell gesendeten Eingabe-Token (einschließlich des Parameters tools)

  2. Die Anzahl der generierten Ausgabe-Token

Tools haben denselben Preis wie alle anderen Claude-API-Anfragen, enthalten jedoch zusätzliche Token pro Anfrage. Die zusätzlichen Token, die sich aus der Nutzung des Tools ergeben, stammen aus den folgenden Quellen:

  • Parameter tools in den API-Anfragen. Zum Beispiel Tool-Namen, Beschreibungen und Schemas.

  • Alle tool_use-Inhaltsblöcke in API-Anfragen und -Antworten.

  • Alle tool_result-Inhaltsblöcke in API-Anfragen.

Wenn Sie Tools nutzen, enthalten die Anthropic-Modelle automatisch einen speziellen System-Prompt, der die Verwendung von Tools ermöglicht. Die Anzahl der für jedes Modell erforderlichen Tool-Nutzungstoken ist in der folgenden Tabelle aufgeführt. In dieser Tabelle sind die zuvor beschriebenen zusätzlichen Token nicht enthalten. Beachten Sie, dass in dieser Tabelle davon ausgegangen wird, dass mindestens ein Tool bereitgestellt wird. Wenn keine Tools bereitgestellt werden, werden bei der Toolauswahl „Keine“ 0 zusätzliche System-Prompt-Token verwendet.

Modell Auswahl des Tools Anzahl der System-Prompt-Token für die Tool-Nutzung

Claude Opus4.5

Claude Opus4,1

Claude Opus 4

Claude Sonnet 4.5

Claude Haiku 4.5

Claude Sonnet 4

Claude 3.7 Sonnet

Claude 3.5 Sonnet v2

auto oder none 346

Claude Opus4,5

Claude Opus4,1

Claude Opus 4

Claude Sonnet 4.5

Claude Haiku 4.5

Claude Sonnet 4

Claude 3.7 Sonnet

Claude 3.5 Sonnet v2

any oder tool 313

Claude 3.5 Sonnet

auto oder none 294

Claude 3.5 Sonnet

any oder tool 261

Claude 3 Opus

auto oder none 530

Claude 3 Opus

any oder tool 281

Claude 3 Sonnet

auto oder none 159

Claude 3 Sonnet

any oder tool 235

Claude 3 Haiku

auto oder none 264

Claude 3 Haiku

any oder tool 340

Tool zur Werkzeugsuche (Beta)

Mit dem Tool Search Tool können Claude Sie mit Hunderten oder sogar Tausenden von Tools arbeiten, ohne dass alle Definitionen im Voraus in das Kontextfenster geladen werden müssen. Anstatt alle Werkzeuge sofort zu deklarieren, können Sie sie mit defer_loading: true markieren. Über den Werkzeugsuchmechanismus werden nur die Tools Claude gefunden und geladen, die benötigt werden.

Um auf diese Funktion zugreifen zu können, müssen Sie sie tool-search-tool-2025-10-19 in den anthropic_beta Parameter aufnehmen. Beachten Sie, dass diese Funktion derzeit nur über die InvokeModelWithResponseStream APIs InvokeModel und verfügbar ist.

Tool-Definition:

{ "type": "tool_search_tool_regex", "name": "tool_search_tool_regex" }

Anfragebeispiel:

{ "anthropic_version": "bedrock-2023-05-31", "anthropic_beta": [ "tool-search-tool-2025-10-19" ], "max_tokens": 4096, "tools": [{ "type": "tool_search_tool_regex", "name": "tool_search_tool_regex" }, { "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] }, "defer_loading": true }, { "name": "search_files", "description": "Search through files in the workspace", "input_schema": { "type": "object", "properties": { "query": { "type": "string" }, "file_types": { "type": "array", "items": { "type": "string" } } }, "required": ["query"] }, "defer_loading": true } ], "messages": [{ "role": "user", "content": "What's the weather in Seattle?" }] }

Beispiel für eine Antwort

{ "role": "assistant", "content": [{ "type": "text", "text": "I'll search for the appropriate tools to help with this task." }, { "type": "server_tool_use", "id": "srvtoolu_01ABC123", "name": "tool_search_tool_regex", "input": { "pattern": "weather" } }, { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_01ABC123", "content": { "type": "tool_search_tool_search_result", "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }] } }, { "type": "text", "text": "Now I can check the weather." }, { "type": "tool_use", "id": "toolu_01XYZ789", "name": "get_weather", "input": { "location": "Seattle", "unit": "fahrenheit" } } ], "stop_reason": "tool_use" }

Beispiel für Streaming

# Event 1: content_block_start(with complete server_tool_use block) { "type": "content_block_start", "index": 0, "content_block": { "type": "server_tool_use", "id": "srvtoolu_01ABC123", "name": "tool_search_tool_regex" } } # Event 2: content_block_delta(input JSON streamed) { "type": "content_block_delta", "index": 0, "delta": { "type": "input_json_delta", "partial_json": "{\"regex\": \".*weather.*\"}" } } # Event 3: content_block_stop(tool_use complete) { "type": "content_block_stop", "index": 0 } # Event 4: content_block_start(COMPLETE result in single chunk) { "type": "content_block_start", "index": 1, "content_block": { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_01ABC123", "content": { "type": "tool_search_tool_search_result", "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }] } } } # Event 5: content_block_stop(result complete) { "type": "content_block_stop", "index": 1 }
Tools für die Suche nach benutzerdefinierten Tools

Sie können benutzerdefinierte Tools für die Werkzeugsuche implementieren (z. B. mithilfe von Einbettungen), indem Sie ein Tool definieren, das Blöcke zurückgibttool_reference. Das benutzerdefinierte Tool muss es haben, defer_loading: false während andere Tools dies tun sollten. defer_loading: true Wenn Sie Ihr eigenes Tool für die Werkzeugsuche definieren, sollte es ein Tool-Ergebnis mit tool_reference Inhaltsblöcken zurückgeben, die auf die Tools verweisen, die Sie verwenden Claude möchten.

Das erwartete, vom Kunden definierte Ergebnisformat für das Tool Search Tool:

{ "type": "tool_result", "tool_use_id": "toolu_01ABC123", "content": [{ "type": "tool_reference", "tool_name": "get_weather" }, { "type": "tool_reference", "tool_name": "weather_forecast" } ] }

Das tool_name muss einem in der Anfrage definierten Tool entsprechen. defer_loading: true Claude hat dann Zugriff auf die vollständigen Schemas dieser Tools.

Benutzerdefinierte Suchwerkzeuge — Ausführliches Beispiel

Sie können benutzerdefinierte Tools für die Werkzeugsuche implementieren (z. B. mithilfe von Einbettungen oder semantischer Suche), indem Sie ein Tool definieren, das Blöcke zurückgibt. tool_reference Dies ermöglicht ausgeklügelte Mechanismen zur Werkzeugerkennung, die über den Regex-Matching hinausgehen.

Beispiel für eine Anfrage mit benutzerdefiniertem TST:

{ "model": "claude-sonnet-4-5-20250929", "anthropic_version": "bedrock-2023-05-31", "anthropic_beta": ["tool-search-tool-2025-10-19"], "max_tokens": 4096, "tools": [{ "name": "semantic_tool_search", "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Natural language description of what kind of tool is needed" }, "top_k": { "type": "integer", "description": "Number of tools to return (default: 5)" } }, "required": ["query"] }, "defer_loading": false }, { "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] }, "defer_loading": true }, { "name": "search_flights", "description": "Search for available flights between locations", "input_schema": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "date": { "type": "string" } }, "required": ["origin", "destination", "date"] }, "defer_loading": true } ], "messages": [{ "role": "user", "content": "What's the weather forecast in Seattle for the next 3 days?" }] }

ClaudeAntwort (Aufruf eines benutzerdefinierten TST):

{ "role": "assistant", "content": [{ "type": "text", "text": "I'll search for the appropriate tools to help with weather information." }, { "type": "tool_use", "id": "toolu_01ABC123", "name": "semantic_tool_search", "input": { "query": "weather forecast multiple days", "top_k": 3 } } ], "stop_reason": "tool_use" }
Customer-provided Ergebnis des Werkzeugs

Nachdem der Kunde eine semantische Suche in der Werkzeugbibliothek durchgeführt hat, gibt er passende Werkzeugreferenzen zurück:

{ "role": "user", "content": [{ "type": "tool_search_tool_result", "tool_use_id": "toolu_01ABC123", "content": { "type": "tool_search_tool_search_result", "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }] } }] }

ClaudeWeiterverfolgung (unter Verwendung des erkannten Tools)

{ "role": "assistant", "content": [{ "type": "text", "text": "I found the forecast tool. Let me get the weather forecast for Seattle." }, { "type": "tool_use", "id": "toolu_01DEF456", "name": "get_weather", "input": { "location": "Seattle, WA" } } ], "stop_reason": "tool_use" }
Fehlerbehandlung
  • Die Einstellung defer_loading: true für alle Tools (einschließlich des Tool Search Tools) führt zu einem 400-Fehler.

  • Wenn Sie eine tool_reference ohne eine entsprechende Werkzeugdefinition übergeben, wird ein 400-Fehler ausgegeben

Beispiele für die Verwendung von Tools (Beta)

Claude Opus4.5 unterstützt von Benutzern bereitgestellte Beispiele in Werkzeugdefinitionen, um die Leistung bei Claude der Werkzeugnutzung zu erhöhen. Sie können Beispiele als vollständige Funktionsaufrufe bereitstellen, die genau so formatiert sind, wie es echte LLM-Ausgaben wären, ohne dass eine Übersetzung in ein anderes Format erforderlich ist. Um diese Funktion verwenden zu können, müssen Sie sie tool-examples-2025-10-29 in den Parameter aufnehmen. anthropic_beta

Beispiel für eine Werkzeugdefinition:

{ "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature unit" } }, "required": ["location"] }, "input_examples": [{ "location": "San Francisco, CA", "unit": "fahrenheit" }, { "location": "Tokyo, Japan", "unit": "celsius" }, { "location": "New York, NY" } ] }
Regeln für die Validierung
  • Schemakonformität: Jedes Beispiel in input_examples muss gemäß den Angaben des input_schema Tools gültig sein.

    • Erforderliche Felder müssen in mindestens einem Beispiel vorhanden sein.

    • Feldtypen müssen dem Schema entsprechen.

    • Enum-Werte müssen aus dem erlaubten Satz stammen.

    • Wenn die Validierung fehlschlägt, geben Sie einen Fehler 400 mit Details darüber zurück, welches Beispiel die Validierung nicht bestanden hat.

  • Array-Anforderungen: input_examples muss ein Array sein (kann leer sein).

    • Ein leeres Array [] ist gültig und entspricht dem Weglassen des Felds.

    • Ein einzelnes Beispiel muss immer noch in ein Array eingeschlossen werden: [{...}]

    • Längenbeschränkung: Beginnen Sie mit einem Limit von 20 Beispielen pro Werkzeugdefinition.

Beispiele für Fehler:

// Invalid: Example doesn't match schema (missing required field) { "type": "invalid_request_error", "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'" } // Invalid: Example has wrong type for field { "type": "invalid_request_error", "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string" } // Invalid: input_examples on server-side tool { "type": "invalid_request_error", "message": "input_examples is not supported for server-side tool" }

Mid-conversation Änderungen am Tool (Beta)

Anmerkung

Für diese Funktion muss das Beta-Flag mid-conversation-tool-changes-2026-07-01 aktiviert seinanthropic_beta. Wird derzeit nur von Claude Opus 5 unterstützt.

Claude Opus 5 unterstützt das Hinzufügen und Entfernen von Tools während der Konversation tool_addition und tool_removal Inhaltsblöcke in role: "system" Nachrichten, anstatt das gesamte tools Array der obersten Ebene erneut zu senden (was den Prompt-Cache ungültig machen würde).

Form anfragen

tool_additionund tool_removal Blöcke erscheinen im content Array einer role: "system" Nachricht zusammen mit optionalen text Blöcken. Jeder Block referenziert über sein tool Feld ein Werkzeug. Mehrere Blöcke sind zulässig und werden in der Reihenfolge ihrer Inhalte verarbeitet.

{ "role": "system", "content": [ {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}}, {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "search_docs"}}, {"type": "text", "text": "Tool set updated for phase 2."} ] }

Beide Blocktypen unterstützen cache_control das Zwischenspeichern von Eingabeaufforderungen.

Referenzvarianten für Werkzeuge

Das tool Feld ist eine diskriminierte Vereinigung in folgenden Bereichen: type

Typ Felder Bezieht sich auf Zusätzliche Betaversion erforderlich
tool_reference name(Zeichenfolge, Muster^[a-zA-Z0-9_-]{1,128}$) Ein Tool, das direkt in der obersten Ebene deklariert wurde tools[]
mcp_tool_reference server_name, name Ein einziges MCP-Tool Eine mcp-client-* Betaversion
mcp_toolset_reference server_name Jedes Tool im Toolset des benannten MCP-Servers Eine Betaversion mcp-client-*

tool_referenceakzeptiert die den MCP-resolved Werkzeugen zugewiesene {server}_{name} Form nicht; verwenden Sie dafür eine der MCP-Varianten.

Semantik

  • Das verfügbare Toolset beginnt so, wie alles drin ist tools[] (nach der MCP-Auflösung). Jedes tool_removal subtrahiert das/die referenzierte (n) Werkzeug (e); jedes fügt sie erneut hinzu. tool_addition Ein entferntes und später wieder hinzugefügtes Werkzeug ist am Ende verfügbar.

  • tool_removalgibt einen kurzen kontextbezogenen Hinweis aus, sodass das Modell die Planung rund um das entfernte Werkzeug beendet.

  • Mid-conversation Werkzeugänderungen lösen keine eingeschränkte Dekodierung aus; es tool_choice bleibt die einzige Steuerung dafür.

  • Maximal 512 tool_addition Blöcke pro Anfrage.

Fehlerantworten (400 invalid_request_error)

Bedingung Fehler
Beta-Flag fehlt Blocktyp wurde als unbekannter Diskriminator zurückgewiesen
Draußen blockieren role: "system" 'tool_addition'/'tool_removal' blocks are only permitted within role: "system" messages
tool_reference.namenicht drintools[], oder benennt ein MCP-resolved Tool tool_addition/tool_removal references unknown tool '<name>'
MCP-Variante mit nicht deklariertem server_name tool_addition/tool_removal references unknown server '<name>'
MCP-Variante, bei der der Server tool_configuration.enabled: false tool_addition/tool_removal references disabled server '<name>'
mcp_tool_referencetool_additionin einem Where-Server hat kein solches Tool Fehler beim Auflisten aller ungelösten Toolnamen für diesen Server
Anmerkung

mcp_tool_referencein a tool_removal ist nachsichtig — wenn der Server das Tool inzwischen fallen gelassen hat, ist das Entfernen ein No-Op (sodass historische Konversationen wiedergegeben werden können).