Strumento di ricerca strumenti

Lo strumento di ricerca strumenti consente a Claude di lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente solo quelli necessari. 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 problemi che si aggravano rapidamente man mano che le librerie di strumenti si espandono:

• Bloat del contesto: Le definizioni degli strumenti consumano rapidamente il tuo budget di contesto. Una configurazione tipica multi-server (GitHub, Slack, Sentry, Grafana, Splunk) può consumare ~55k token in definizioni prima che Claude faccia qualsiasi lavoro effettivo. La ricerca degli strumenti in genere riduce questo di oltre l'85%, caricando solo i 3-5 strumenti che Claude effettivamente necessita per una determinata richiesta.
• Accuratezza della selezione degli strumenti: La capacità di Claude di scegliere correttamente lo strumento giusto si degrada significativamente una volta superati i 30-50 strumenti disponibili. Presentando un insieme focalizzato di strumenti rilevanti su richiesta, la ricerca degli strumenti mantiene l'accuratezza della selezione elevata anche su migliaia di strumenti.

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.

Puoi anche implementare ricerca degli strumenti lato client restituendo blocchi tool_reference dalla tua implementazione di ricerca personalizzata.

Come funziona la ricerca degli strumenti

Ci sono due varianti di ricerca degli strumenti:

• Regex (tool_search_tool_regex_20251119): Claude costruisce pattern regex per cercare gli strumenti
• BM25 (tool_search_tool_bm25_20251119): Claude utilizza query in linguaggio naturale per cercare gli strumenti

Quando abiliti lo strumento di ricerca degli strumenti:

1. Includi uno strumento di ricerca degli strumenti (ad es. tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119) nella tua lista di strumenti
2. Fornisci tutte le definizioni degli strumenti con defer_loading: true per gli strumenti che non dovrebbero essere caricati immediatamente
3. Claude vede inizialmente solo lo strumento di ricerca degli strumenti e gli strumenti non differiti
4. Quando Claude ha bisogno di strumenti aggiuntivi, cerca utilizzando uno strumento di ricerca degli strumenti
5. L'API restituisce 3-5 blocchi tool_reference più rilevanti
6. Questi riferimenti vengono automaticamente espansi in definizioni complete degli strumenti
7. Claude seleziona dagli strumenti scoperti e li invoca

Questo mantiene la tua finestra di contesto efficiente mantenendo un'elevata accuratezza nella selezione degli strumenti.

Avvio rapido

Ecco un semplice esempio con strumenti differiti:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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,
        },
    ],
)

print(response)

Definizione dello strumento

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"
}

Caricamento differito degli 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:

• Gli strumenti senza defer_loading vengono caricati nel contesto immediatamente
• Gli strumenti con defer_loading: true vengono caricati solo quando Claude li scopre tramite ricerca
• Lo strumento di ricerca degli strumenti stesso non dovrebbe mai avere defer_loading: true
• Mantieni i tuoi 3-5 strumenti più frequentemente utilizzati come non differiti per prestazioni ottimali

Entrambe le varianti di ricerca degli strumenti (regex e bm25) cercano nomi degli strumenti, descrizioni, nomi degli argomenti e descrizioni degli argomenti.

Come funziona il differimento internamente: Gli strumenti differiti non sono inclusi nel prefisso del prompt di sistema. Quando il modello scopre uno strumento differito tramite ricerca degli strumenti, la definizione dello strumento viene aggiunta inline come blocco tool_reference nella conversazione. Il prefisso rimane intatto, quindi il caching del prompt viene preservato. La grammatica per la modalità ristretta si costruisce dal set completo di strumenti, quindi defer_loading e la modalità ristretta si compongono senza ricompilazione della grammatica.

Formato della risposta

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_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"
}

Comprensione della risposta

• server_tool_use: Indica che Claude sta invocando lo strumento di ricerca degli strumenti
• tool_search_tool_result: Contiene i risultati della ricerca con un oggetto tool_search_tool_search_result annidato
• tool_references: Array di oggetti tool_reference che puntano agli strumenti scoperti
• tool_use: Claude che invoca lo strumento scoperto

I 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.

Integrazione MCP

Per configurare mcp_toolset con defer_loading, vedi Connettore MCP.

Implementazione personalizzata della ricerca degli strumenti

Puoi implementare la tua logica di ricerca degli strumenti (ad es. utilizzando embeddings o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato. Quando Claude chiama il tuo strumento di ricerca personalizzato, restituisci un tool_result standard con blocchi tool_reference nell'array di contenuto:

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "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 embeddings, vedi il cookbook di ricerca degli strumenti con embeddings.

Gestione degli errori

Errori HTTP (stato 400)

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"
  }
}

Errori dei risultati degli strumenti (stato 200)

Gli errori durante l'esecuzione dello strumento restituiscono una risposta 200 con informazioni di 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 strumenti
• invalid_pattern: Pattern regex malformato
• pattern_too_long: Il pattern supera il limite di 200 caratteri
• unavailable: Servizio di ricerca degli strumenti temporaneamente non disponibile

Errori comuni

Caching del prompt

Per come defer_loading preserva il caching del prompt, vedi Utilizzo degli strumenti con caching del prompt.

Il sistema espande automaticamente i blocchi tool_reference in tutta la cronologia della conversazione, quindi Claude può riutilizzare gli strumenti scoperti nei turni successivi senza ricercare di nuovo.

Streaming

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"}}

// 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 tools

Richieste batch

Puoi 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 regolare.

Conservazione dei dati

La ricerca degli strumenti lato server (strumento tool_search) indicizza e archivia i dati del catalogo degli strumenti (nomi degli strumenti, descrizioni e metadati degli argomenti) oltre la risposta API immediata; questi dati del catalogo vengono conservati secondo la politica di conservazione standard di Anthropic. Le implementazioni personalizzate di ricerca degli strumenti lato client che utilizzano l'API Messages standard sono completamente idonee per ZDR.

Per l'idoneità ZDR in tutte le funzioni, vedi API e conservazione dei dati.

Limiti e best practice

Limiti

• Strumenti massimi: 10.000 strumenti nel tuo catalogo
• Risultati della ricerca: Restituisce 3-5 strumenti più rilevanti per ricerca
• Lunghezza del pattern: Massimo 200 caratteri per i pattern regex
• Supporto del modello: Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ solo (nessun Haiku)

Quando utilizzare la ricerca degli strumenti

Buoni casi d'uso:

• 10+ strumenti disponibili nel tuo sistema
• Definizioni degli strumenti che consumano >10k token
• Problemi di accuratezza nella selezione degli strumenti con set di strumenti grandi
• Costruzione di sistemi alimentati da MCP con più server (200+ strumenti)
• Libreria di strumenti che cresce nel tempo

Quando la chiamata degli strumenti tradizionale potrebbe essere migliore:

• Meno di 10 strumenti totali
• Tutti gli strumenti sono frequentemente utilizzati in ogni richiesta
• Definizioni degli strumenti molto piccole (<100 token totali)

Suggerimenti di ottimizzazione

• Mantieni i 3-5 strumenti più frequentemente utilizzati come non differiti
• Scrivi nomi e descrizioni degli strumenti chiari e descrittivi
• Utilizza namespacing coerente nei nomi degli strumenti: prefisso per servizio o risorsa (ad es. github_, slack_) in modo che le query di ricerca scoprano naturalmente il giusto gruppo di strumenti
• Utilizza parole chiave semantiche nelle descrizioni che corrispondono a come gli utenti descrivono i compiti
• Aggiungi una sezione di prompt di sistema che descrive le categorie di strumenti disponibili: "Puoi cercare strumenti per interagire con Slack, GitHub e Jira"
• Monitora quali strumenti Claude scopre per perfezionare le descrizioni

Utilizzo

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
    }
  }
}

Passaggi successivi