Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Lo strumento di ricerca degli strumenti consente a Claude di lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente quelli necessari su richiesta. Invece di caricare tutte le definizioni degli strumenti nella finestra di contesto in anticipo, Claude cerca il tuo catalogo di strumenti—inclusi nomi degli strumenti, descrizioni, nomi degli argomenti e descrizioni degli argomenti—e carica solo gli strumenti di cui ha bisogno.
Questo approccio risolve due sfide critiche man mano che le librerie di strumenti si espandono:
Sebbene questo sia fornito come uno strumento lato server, puoi anche implementare la tua funzionalità di ricerca degli strumenti lato client. Vedi Implementazione personalizzata della ricerca degli strumenti per i dettagli.
Lo strumento di ricerca degli strumenti è attualmente in beta pubblica.
Per utilizzare questa funzione, aggiungi l'intestazione beta "advanced-tool-use-2025-11-20" alle tue richieste API.
Ti invitiamo a contattarci tramite il nostro modulo di feedback per condividere la tua esperienza con lo strumento di ricerca degli strumenti.
| Piattaforma | Modelli supportati |
|---|
| Claude API | Claude Opus 4.5, Claude Sonnet 4.5 |
| Microsoft Foundry | Claude Opus 4.5, Claude Sonnet 4.5 |
| Google Cloud Vertex AI | Claude Opus 4.5, Claude Sonnet 4.5 |
| Amazon Bedrock | Claude Opus 4.5 |
Su Amazon Bedrock, la ricerca degli strumenti lato server è disponibile solo tramite l'API invoke, non l'API converse.
Puoi anche implementare ricerca degli strumenti lato client restituendo blocchi tool_reference dalla tua implementazione di ricerca personalizzata.
Ci sono due varianti di ricerca degli strumenti:
tool_search_tool_regex_20251119): Claude costruisce pattern regex per cercare gli strumentitool_search_tool_bm25_20251119): Claude utilizza query in linguaggio naturale per cercare gli strumentiQuando abiliti lo strumento di ricerca degli strumenti:
tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119) nella tua lista di strumentidefer_loading: true per gli strumenti che non dovrebbero essere caricati immediatamentetool_reference più rilevantiQuesto mantiene la tua finestra di contesto efficiente mantenendo un'elevata accuratezza nella selezione degli strumenti.
Ecco un semplice esempio con strumenti differiti:
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
}
]
}'Lo strumento di ricerca degli strumenti ha due varianti:
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}{
"type": "tool_search_tool_bm25_20251119",
"name": "tool_search_tool_bm25"
}Formato della query della variante Regex: regex Python, NON linguaggio naturale
Quando utilizzi tool_search_tool_regex_20251119, Claude costruisce pattern regex utilizzando la sintassi re.search() di Python, non query in linguaggio naturale. Pattern comuni:
"weather" - corrisponde ai nomi/descrizioni degli strumenti contenenti "weather""get_.*_data" - corrisponde a strumenti come get_user_data, get_weather_data"database.*query|query.*database" - pattern OR per flessibilità"(?i)slack" - ricerca case-insensitiveLunghezza massima della query: 200 caratteri
Formato della query della variante BM25: Linguaggio naturale
Quando utilizzi tool_search_tool_bm25_20251119, Claude utilizza query in linguaggio naturale per cercare gli strumenti.
Contrassegna gli strumenti per il caricamento su richiesta aggiungendo defer_loading: true:
{
"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
}Punti chiave:
defer_loading vengono caricati nel contesto immediatamentedefer_loading: true vengono caricati solo quando Claude li scopre tramite ricercadefer_loading: trueEntrambe le varianti di ricerca degli strumenti (regex e bm25) cercano nomi degli strumenti, descrizioni, nomi degli argomenti e descrizioni degli argomenti.
Quando Claude utilizza lo strumento di ricerca degli strumenti, la risposta include nuovi tipi di blocco:
{
"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_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": [{ "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: Indica che Claude sta invocando lo strumento di ricerca degli strumentitool_result con tool_reference: I risultati della ricerca contenenti riferimenti agli strumenti scopertitool_use: Claude che invoca lo strumento scopertoI blocchi tool_reference vengono automaticamente espansi in definizioni complete degli strumenti prima di essere mostrati a Claude. Non è necessario gestire questa espansione da solo. Accade automaticamente nell'API finché fornisci tutte le definizioni degli strumenti corrispondenti nel parametro tools.
Lo strumento di ricerca degli strumenti funziona con i server MCP. Aggiungi l'intestazione beta "mcp-client-2025-11-20" alla tua richiesta API, quindi utilizza mcp_tool_set con default_configs per differire il caricamento degli strumenti MCP:
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_tool_set",
"mcp_server_name": "database-server",
"default_configs": {
"defer_loading": true
},
"configs": {
"search_events": {
"defer_loading": false
}
}
}
],
"messages": [
{
"role": "user",
"content": "What events are in my database?"
}
]
}'Opzioni di configurazione MCP:
default_configs.defer_loading: Imposta il valore predefinito per tutti gli strumenti dal server MCPconfigs: Sostituisci i valori predefiniti per strumenti specifici per nomePuoi implementare la tua logica di ricerca degli strumenti (ad es. utilizzando embedding o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato:
{
"type": "tool_result",
"tool_use_id": "toolu_custom_search",
"content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}Ogni strumento referenziato deve avere una definizione dello strumento corrispondente nel parametro tools di livello superiore con defer_loading: true. Questo approccio ti consente di utilizzare algoritmi di ricerca più sofisticati mantenendo la compatibilità con il sistema di ricerca degli strumenti.
Per un esempio completo utilizzando embedding, vedi il nostro cookbook di ricerca degli strumenti con embedding.
Lo strumento di ricerca degli strumenti non è compatibile con gli esempi di utilizzo degli strumenti. Se hai bisogno di fornire esempi di utilizzo degli strumenti, utilizza la chiamata degli strumenti standard senza ricerca degli strumenti.
Questi errori impediscono l'elaborazione della richiesta:
Tutti gli strumenti differiti:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "All tools have defer_loading set. At least one tool must be non-deferred."
}
}Definizione dello strumento mancante:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Tool reference 'unknown_tool' has no corresponding tool definition"
}
}Gli errori durante l'esecuzione dello strumento restituiscono una risposta 200 con informazioni sull'errore nel corpo:
{
"type": "tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_result_error",
"error_code": "invalid_pattern"
}
}Codici di errore:
too_many_requests: Limite di velocità superato per le operazioni di ricerca degli strumentiinvalid_pattern: Pattern regex malformatopattern_too_long: Il pattern supera il limite di 200 caratteriunavailable: Servizio di ricerca degli strumenti temporaneamente non disponibileLa ricerca degli strumenti funziona con la memorizzazione nella cache dei prompt. Aggiungi punti di interruzione cache_control per ottimizzare le conversazioni multi-turno:
import anthropic
client = anthropic.Anthropic()
# Prima richiesta con ricerca degli strumenti
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
}
]
)
# Aggiungi la risposta di Claude alla conversazione
messages.append({
"role": "assistant",
"content": response1.content
})
# Seconda richiesta con punto di interruzione della cache
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)}")Il sistema espande automaticamente i blocchi tool_reference nell'intera cronologia della conversazione, quindi Claude può riutilizzare gli strumenti scoperti nei turni successivi senza ricercare di nuovo.
Con lo streaming abilitato, riceverai gli eventi di ricerca degli strumenti come parte dello stream:
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"}}
// Query di ricerca trasmessa
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}
// Pausa mentre la ricerca viene eseguita
// Risultati della ricerca trasmessi
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}
// Claude continua con gli strumenti scopertiPuoi includere lo strumento di ricerca degli strumenti nell'API Messages Batches. Le operazioni di ricerca degli strumenti tramite l'API Messages Batches hanno lo stesso prezzo di quelle nelle richieste dell'API Messages regolari.
Buoni casi d'uso:
Quando la chiamata degli strumenti tradizionale potrebbe essere migliore:
L'utilizzo dello strumento di ricerca degli strumenti viene tracciato nell'oggetto di utilizzo della risposta:
{
"usage": {
"input_tokens": 1024,
"output_tokens": 256,
"server_tool_use": {
"tool_search_requests": 2
}
}
}Per informazioni sui prezzi attuali, vedi la pagina dei prezzi.