Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Das Tool-Suchwerkzeug ermöglicht Claude, mit Hunderten oder Tausenden von Werkzeugen zu arbeiten, indem diese dynamisch entdeckt und bei Bedarf geladen werden. Anstatt alle Werkzeugdefinitionen vorab in das Kontextfenster zu laden, durchsucht Claude Ihren Werkzeugkatalog – einschließlich Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen – und lädt nur die Werkzeuge, die er benötigt.
Dieser Ansatz löst zwei kritische Herausforderungen bei der Skalierung von Werkzeugbibliotheken:
Obwohl dies als serverseitiges Werkzeug bereitgestellt wird, können Sie auch Ihre eigene clientseitige Tool-Suchfunktionalität implementieren. Siehe Benutzerdefinierte Tool-Suchimplementierung für Details.
Das Tool-Suchwerkzeug befindet sich derzeit in der öffentlichen Beta. Fügen Sie den entsprechenden Beta-Header für Ihren Anbieter ein:
| Anbieter | Beta-Header | Unterstützte Modelle |
|---|---|---|
| Claude API Microsoft Foundry | advanced-tool-use-2025-11-20 | Claude Opus 4.5 Claude Sonnet 4.5 |
| Google Cloud's Vertex AI |
tool-search-tool-2025-10-19 |
| Claude Opus 4.5 Claude Sonnet 4.5 |
| Amazon Bedrock | tool-search-tool-2025-10-19 | Claude Opus 4.5 |
Bei Amazon Bedrock ist die serverseitige Tool-Suche nur über die invoke API, nicht über die converse API verfügbar.
Sie können auch clientseitige Tool-Suche implementieren, indem Sie tool_reference-Blöcke aus Ihrer eigenen Suchimplementierung zurückgeben.
Es gibt zwei Tool-Suchvarianten:
tool_search_tool_regex_20251119): Claude konstruiert Regex-Muster zur Suche nach Werkzeugentool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen zur Suche nach WerkzeugenWenn Sie das Tool-Suchwerkzeug aktivieren:
tool_search_tool_regex_20251119 oder tool_search_tool_bm25_20251119) in Ihre Werkzeugliste eindefer_loading: true für Werkzeuge bereit, die nicht sofort geladen werden solltentool_reference-Blöcke zurückDies hält Ihr Kontextfenster effizient, während die hohe Genauigkeit der Werkzeugauswahl erhalten bleibt.
Hier ist ein einfaches Beispiel mit aufgeschobenen Werkzeugen:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"messages": [
{
"role": "user",
"content": "What is the weather in San Francisco?"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get the weather at a specific 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
}
]
}'Das Tool-Suchwerkzeug hat zwei Varianten:
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}{
"type": "tool_search_tool_bm25_20251119",
"name": "tool_search_tool_bm25"
}Regex-Varianten-Abfrageformat: Python-Regex, KEINE natürliche Sprache
Bei Verwendung von tool_search_tool_regex_20251119 konstruiert Claude Regex-Muster mit der Syntax von Pythons re.search(), nicht natürlichsprachliche Abfragen. Häufige Muster:
"weather" - passt Werkzeugnamen/Beschreibungen mit "weather""get_.*_data" - passt Werkzeuge wie get_user_data, get_weather_data"database.*query|query.*database" - ODER-Muster für Flexibilität"(?i)slack" - Suche ohne Berücksichtigung der Groß-/KleinschreibungMaximale Abfragelänge: 200 Zeichen
BM25-Varianten-Abfrageformat: Natürliche Sprache
Bei Verwendung von tool_search_tool_bm25_20251119 verwendet Claude natürlichsprachliche Abfragen zur Suche nach Werkzeugen.
Markieren Sie Werkzeuge für das Laden bei Bedarf, indem Sie defer_loading: true hinzufügen:
{
"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
}Wichtige Punkte:
defer_loading werden sofort in den Kontext geladendefer_loading: true werden nur geladen, wenn Claude sie durch Suche entdecktdefer_loading: true habenBeide Tool-Suchvarianten (regex und bm25) durchsuchen Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen.
Wenn Claude das Tool-Suchwerkzeug verwendet, enthält die Antwort neue Blocktypen:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll search for tools to help with the weather information."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01ABC123",
"name": "tool_search_tool_regex",
"input": {
"query": "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": "I found a weather tool. Let me get the weather for San Francisco."
},
{
"type": "tool_use",
"id": "toolu_01XYZ789",
"name": "get_weather",
"input": { "location": "San Francisco", "unit": "fahrenheit" }
}
],
"stop_reason": "tool_use"
}server_tool_use: Zeigt an, dass Claude das Tool-Suchwerkzeug aufrufttool_search_tool_result: Enthält die Suchergebnisse mit einem verschachtelten tool_search_tool_search_result-Objekttool_references: Array von tool_reference-Objekten, die auf entdeckte Werkzeuge verweisentool_use: Claude ruft das entdeckte Werkzeug aufDie tool_reference-Blöcke werden automatisch in vollständige Werkzeugdefinitionen erweitert, bevor sie Claude angezeigt werden. Sie müssen diese Erweiterung nicht selbst durchführen. Dies geschieht automatisch in der API, solange Sie alle übereinstimmenden Werkzeugdefinitionen im tools-Parameter bereitstellen.
Das Tool-Suchwerkzeug funktioniert mit MCP-Servern. Fügen Sie den "mcp-client-2025-11-20" Beta-Header zu Ihrer API-Anfrage hinzu, und verwenden Sie dann mcp_toolset mit default_config, um MCP-Werkzeuge aufzuschieben:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"mcp_servers": [
{
"type": "url",
"name": "database-server",
"url": "https://mcp-db.example.com"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"type": "mcp_toolset",
"mcp_server_name": "database-server",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"defer_loading": false
}
}
}
],
"messages": [
{
"role": "user",
"content": "What events are in my database?"
}
]
}'MCP-Konfigurationsoptionen:
default_config.defer_loading: Standardwert für alle Werkzeuge vom MCP-Server festlegenconfigs: Standardwerte für bestimmte Werkzeuge nach Name überschreibenSie können Ihre eigene Tool-Suchlogik implementieren (z. B. mit Embeddings oder semantischer Suche), indem Sie tool_reference-Blöcke von einem benutzerdefinierten Werkzeug zurückgeben:
{
"type": "tool_search_tool_result",
"tool_use_id": "toolu_custom_search",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
}Jedes referenzierte Werkzeug muss eine entsprechende Werkzeugdefinition im Top-Level-tools-Parameter mit defer_loading: true haben. Dieser Ansatz ermöglicht es Ihnen, anspruchsvollere Suchalgorithmen zu verwenden und gleichzeitig die Kompatibilität mit dem Tool-Suchsystem zu bewahren.
Ein vollständiges Beispiel mit Embeddings finden Sie in unserem Tool-Suche mit Embeddings Cookbook.
Das Tool-Suchwerkzeug ist nicht kompatibel mit Tool-Use- Beispielen. Wenn Sie Beispiele für die Werkzeugnutzung bereitstellen müssen, verwenden Sie Standard-Tool-Aufrufe ohne Tool-Suche.
Diese Fehler verhindern die Verarbeitung der Anfrage:
Alle Werkzeuge aufgeschoben:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "All tools have defer_loading set. At least one tool must be non-deferred."
}
}Fehlende Werkzeugdefinition:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Tool reference 'unknown_tool' has no corresponding tool definition"
}
}Fehler während der Werkzeugausführung geben eine 200-Antwort mit Fehlerinformationen im Text zurück:
{
"type": "tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_result_error",
"error_code": "invalid_pattern"
}
}Fehlercodes:
too_many_requests: Ratenlimit für Tool-Suchvorgänge überschritteninvalid_pattern: Malformed Regex-Musterpattern_too_long: Muster überschreitet 200-Zeichen-Limitunavailable: Tool-Suchservice vorübergehend nicht verfügbarTool-Suche funktioniert mit Prompt-Caching. Fügen Sie cache_control-Breakpoints hinzu, um mehrteilige Gespräche zu optimieren:
import anthropic
client = anthropic.Anthropic()
# First request with tool search
messages = [
{
"role": "user",
"content": "What's the weather in Seattle?"
}
]
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
# Add Claude's response to conversation
messages.append({
"role": "assistant",
"content": response1.content
})
# Second request with cache breakpoint
messages.append({
"role": "user",
"content": "What about New York?",
"cache_control": {"type": "ephemeral"}
})
response2 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")
Das System erweitert automatisch tool_reference-Blöcke in der gesamten Gesprächshistorie, sodass Claude entdeckte Werkzeuge in nachfolgenden Runden wiederverwenden kann, ohne erneut zu suchen.
Mit aktiviertem Streaming erhalten Sie Tool-Suchereignisse als Teil des Streams:
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}
// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}
// Pause while search executes
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}
// Claude continues with discovered toolsSie können das Tool-Suchwerkzeug in die Messages Batches API einbeziehen. Tool-Suchvorgänge über die Messages Batches API werden genauso berechnet wie die in regulären Messages API-Anfragen.
Gute Anwendungsfälle:
Wann traditionelle Tool-Aufrufe möglicherweise besser sind:
Die Nutzung des Tool-Suchwerkzeugs wird im Nutzungsobjekt der Antwort verfolgt:
{
"usage": {
"input_tokens": 1024,
"output_tokens": 256,
"server_tool_use": {
"tool_search_requests": 2
}
}
}Aktuelle Preisinformationen finden Sie auf der Preisseite.