Vai al contenuto principale
La ricerca di strumenti consente al vostro agente di lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente solo quelli di cui ha bisogno. Invece di caricare tutte le definizioni degli strumenti nella finestra di contesto in anticipo, l’agente cerca nel vostro catalogo di strumenti e carica solo gli strumenti di cui ha bisogno. Questo approccio risolve due sfide man mano che le librerie di strumenti si scalano:
  • Efficienza del contesto: Le definizioni degli strumenti possono consumare grandi porzioni della finestra di contesto (50 strumenti possono utilizzare 10-20K token), lasciando meno spazio per il lavoro effettivo.
  • Accuratezza della selezione degli strumenti: L’accuratezza della selezione degli strumenti si degrada con più di 30-50 strumenti caricati contemporaneamente.
La ricerca di strumenti è abilitata per impostazione predefinita. Questa pagina copre come funziona, come configurarla e come ottimizzare la scoperta degli strumenti.

​
Come funziona la ricerca di strumenti

Quando la ricerca di strumenti è attiva, le definizioni degli strumenti vengono trattenute dalla finestra di contesto. L’agente riceve un riepilogo degli strumenti disponibili e cerca quelli rilevanti quando l’attività richiede una capacità non già caricata. I 3-5 strumenti più rilevanti vengono caricati nel contesto, dove rimangono disponibili per i turni successivi. Se la conversazione è abbastanza lunga da far sì che l’SDK compatti i messaggi precedenti per liberare spazio, gli strumenti precedentemente scoperti possono essere rimossi e l’agente ricerca di nuovo secondo le necessità. La ricerca di strumenti aggiunge un extra round-trip la prima volta che Claude scopre uno strumento (il passaggio di ricerca), ma per grandi set di strumenti questo è compensato da un contesto più piccolo ad ogni turno. Con meno di ~10 strumenti, il caricamento di tutto in anticipo è generalmente più veloce. Per i dettagli sul meccanismo API sottostante, vedere Ricerca di strumenti nell’API.
La ricerca di strumenti richiede Claude Sonnet 4 o successivo, o Claude Opus 4 o successivo. I modelli Haiku non supportano la ricerca di strumenti.

​
Configurare la ricerca di strumenti

La ricerca di strumenti è attiva per impostazione predefinita. È disabilitata per impostazione predefinita su Vertex AI, dove è supportata per Claude Sonnet 4.5 e successivo e Claude Opus 4.5 e successivo. È anche disabilitata quando ANTHROPIC_BASE_URL punta a un host non di prima parte, poiché la maggior parte dei proxy non inoltrano i blocchi tool_reference. Potete ignorare uno qualsiasi dei valori predefiniti con la variabile di ambiente ENABLE_TOOL_SEARCH:
ValoreComportamento
(non impostato)La ricerca di strumenti è attiva. Le definizioni degli strumenti vengono differite e scoperte su richiesta. Ritorna al caricamento in anticipo su Vertex AI o su un ANTHROPIC_BASE_URL non di prima parte.
trueLa ricerca di strumenti è sempre attiva. L’SDK invia l’intestazione beta anche su Vertex AI e attraverso i proxy. Le richieste falliscono sui modelli Vertex AI precedenti a Sonnet 4.5 o Opus 4.5, o sui proxy che non supportano i blocchi tool_reference.
autoControlla il conteggio dei token combinato di tutte le definizioni degli strumenti rispetto alla finestra di contesto del modello. Se superano il 10%, la ricerca di strumenti si attiva. Se sono sotto il 10%, tutti gli strumenti vengono caricati nel contesto normalmente.
auto:NCome auto con una percentuale personalizzata. auto:5 si attiva quando le definizioni degli strumenti superano il 5% della finestra di contesto. Valori più bassi si attivano prima.
falseLa ricerca di strumenti è disattivata. Tutte le definizioni degli strumenti vengono caricate nel contesto ad ogni turno.
La ricerca di strumenti si applica a tutti gli strumenti registrati, che provengano da server MCP remoti o da server MCP SDK personalizzati. Quando si utilizza auto, la soglia si basa sulla dimensione combinata di tutte le definizioni degli strumenti su tutti i server. Impostare il valore nell’opzione env su query(). Questo esempio si connette a un server MCP remoto che espone molti strumenti, pre-approva tutti loro con un carattere jolly e utilizza auto:5 in modo che la ricerca di strumenti si attivi quando le loro definizioni superano il 5% della finestra di contesto: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
Impostare ENABLE_TOOL_SEARCH su "false" disabilita la ricerca di strumenti e carica tutte le definizioni degli strumenti nel contesto ad ogni turno. Questo rimuove il round-trip di ricerca, che può essere più veloce quando il set di strumenti è piccolo (meno di ~10 strumenti) e le definizioni si adattano comodamente nella finestra di contesto.

​
Ottimizzare la scoperta degli strumenti

Il meccanismo di ricerca abbina le query ai nomi e alle descrizioni degli strumenti. Nomi come search_slack_messages emergono per una gamma più ampia di richieste rispetto a query_slack. Le descrizioni con parole chiave specifiche (“Cerca messaggi Slack per parola chiave, canale o intervallo di date”) corrispondono a più query rispetto a quelle generiche (“Query Slack”). Potete anche aggiungere una sezione di prompt di sistema che elenca le categorie di strumenti disponibili. Questo dà all’agente il contesto su quali tipi di strumenti sono disponibili per la ricerca: 
You can search for tools to interact with Slack, GitHub, and Jira.

​
Limiti

  • Strumenti massimi: 10.000 strumenti nel vostro catalogo
  • Risultati di ricerca: Restituisce i 3-5 strumenti più rilevanti per ricerca
  • Supporto del modello: Claude Sonnet 4 e successivo, Claude Opus 4 e successivo (nessun Haiku)

​
Documentazione correlata