Riferimento degli strumenti

Questa pagina è un riferimento per gli strumenti forniti da Anthropic e per le proprietà opzionali che puoi impostare su qualsiasi definizione di strumento. Per un'introduzione concettuale al "tool use" (uso degli strumenti), consulta Uso degli strumenti con Claude. Per indicazioni su come implementare l'uso degli strumenti nella tua applicazione, consulta Definire gli strumenti.

Strumenti forniti da Anthropic

Anthropic fornisce due tipi di strumenti: strumenti server che vengono eseguiti sull'infrastruttura di Anthropic e strumenti client per i quali Anthropic definisce lo schema ma la tua applicazione gestisce l'esecuzione. Entrambi i tipi compaiono nell'array tools della tua richiesta insieme a eventuali strumenti definiti dall'utente.

Per la compatibilità con i modelli, consulta la pagina di ciascuno strumento. I modelli supportati variano in base allo strumento e alla versione dello strumento.

Versionamento degli strumenti

La maggior parte degli strumenti forniti da Anthropic riporta un suffisso _YYYYMMDD nella stringa type. Una nuova versione viene rilasciata quando cambiano il comportamento, lo schema o il supporto dei modelli dello strumento. Le versioni precedenti restano disponibili affinché le integrazioni esistenti continuino a funzionare.

Quando uno strumento ha più versioni attive, la relazione tra di esse varia:

• Basata sulle funzionalità: web_search_20260209 e web_fetch_20260209 aggiungono il filtraggio dinamico dei contenuti rispetto ai loro predecessori; web_fetch_20260309 aggiunge un'opzione per bypassare la cache; web_search_20260318 e web_fetch_20260318 aggiungono il controllo dell'inclusione nella risposta. code_execution_20260120 aggiunge la chiamata programmatica degli strumenti dall'interno della sandbox; code_execution_20260521 indica il limite di tempo per cella nella descrizione dello strumento. In ogni caso, sia la nuova che la vecchia versione sono attuali; quale usare dipende dal fatto che tu abbia bisogno o meno della nuova funzionalità.
• Basata sul modello: text_editor_20250728 è per i modelli Claude 4 e successivi e text_editor_20250124 è per i modelli precedenti. La versione da usare dipende dal modello di destinazione.
• Variante, non versione: tool_search_tool_regex_20251119 e tool_search_tool_bm25_20251119 sono due algoritmi di ricerca rilasciati insieme. Nessuno dei due sostituisce l'altro.
• Legacy: code_execution_20250522 supporta solo Python. code_execution_20250825 aggiunge Bash e le operazioni sui file.
• Successore: computer_toolset_20260801 è il successore stabile delle versioni beta computer_20251124 e computer_20250124, che restano disponibili per le integrazioni esistenti e per i modelli che non supportano il toolset (Versioni precedenti dello strumento). browser_toolset_20260801 è la prima versione dello strumento browser use. Entrambi sono toolset client.

Il tipo mcp_toolset non è versionato per data; il versionamento è invece gestito tramite l'header anthropic-beta.

Toolset client

Lo strumento computer use e lo strumento browser use sono "client toolsets" (toolset client) definiti da Anthropic: una singola voce in tools dichiara un insieme fisso di strumenti membri i cui nomi, descrizioni e schemi di input sono definiti da Anthropic, e la tua applicazione esegue ogni chiamata. La voce non accetta name, perché il type datato fissa i nomi dei membri. configs, cache_control e allowed_callers (che accetta solo ["direct"]) sono opzionali.

I toolset client sono strumenti della Messages API. Non sono attualmente disponibili come strumenti agente in Claude Managed Agents, che fornisce il proprio toolset agente integrato, toolset MCP e strumenti personalizzati.

{
  "type": "browser_toolset_20260801",
  "configs": {
    "javascript_exec": { "enabled": true }
  },
  "cache_control": { "type": "ephemeral" }
}

configs regola i singoli membri:

• Le chiavi sono i nomi dei membri e ogni valore accetta solo enabled e defer_loading.
• Un membro omesso mantiene i suoi valori predefiniti. Un valore assente, {} e un valore predefinito ribadito sono equivalenti.
• Un nome di membro sconosciuto o qualsiasi altro campo nel valore di un membro viene rifiutato, così come un configs che disabilita tutti i membri (ometti invece la voce).
• Un membro disabilitato viene rimosso dagli strumenti che Claude vede. Se Claude lo nomina comunque, restituisci un tool_result di errore.

Imposta defer_loading per membro, mai sulla voce, e assegna a ogni membro abilitato lo stesso valore: con la ricerca strumenti il toolset viene caricato ed espanso come un'unica definizione. Quando ogni membro abilitato è differito, solo uno strumento di ricerca strumenti che non sia a sua volta differito può far emergere il toolset, quindi dichiarane uno nella stessa richiesta. Non inserire cache_control su una voce di toolset i cui membri sono differiti; imposta invece il breakpoint su uno strumento non differito, perché le definizioni differite non fanno parte del prefisso in cache.

cache_control va solo sulla voce; per sapere dove ricade il breakpoint, inclusi i marcatori all'interno di un'azione batch, consulta Uso degli strumenti con la cache dei prompt.

Gestisci le chiamate agli strumenti membri. Claude chiama un membro con un blocco tool_use il cui name è il nome del membro e il cui toolset_name è computer o browser; input contiene i parametri di quel membro e nessun campo action. Esegui il dispatch sulla coppia toolset_name e name, perché uno strumento personalizzato potrebbe condividere il nome di un membro e i due toolset condividono nomi come screenshot. Solo i risultati dei membri riportano toolset_name. Più chiamate a membri in un singolo turno formano un'azione batch che esegui in ordine (computer use, browser use). Nuovi membri arrivano solo con un nuovo type datato.

Non supportato sulle voci di toolset. L'API rifiuta ciascuno di questi con un invalid_request_error:

• strict: true o input_examples.
• defer_loading sulla voce, oppure membri abilitati i cui valori defer_loading differiscono (impostalo per membro in configs, tutti allo stesso valore).
• Un chiamante di esecuzione del codice in allowed_callers (nessuna chiamata programmatica degli strumenti).
• L'header beta legacy fine-grained-tool-streaming-2025-05-14. Quando usi lo streaming, l'input di ciascun membro arriva come un unico input_json_delta completo.
• Un tool_choice di tipo tool che nomina il toolset o un membro (usa auto, any o none).
• Due voci dello stesso toolset, oppure un altro strumento che porta il nome di quel toolset: uno strumento chiamato computer insieme a computer_toolset_20260801, oppure uno strumento chiamato browser insieme a browser_toolset_20260801. I due toolset possono essere dichiarati insieme.

Proprietà delle definizioni degli strumenti

Ogni strumento nell'array tools, inclusi gli strumenti definiti dall'utente, accetta proprietà opzionali che controllano come lo strumento viene caricato, chi può chiamarlo e come vengono validati i suoi input. Queste proprietà si combinano: puoi impostare defer_loading, cache_control e strict sullo stesso strumento.

Valori di allowed_callers

allowed_callers è un array che accetta qualsiasi combinazione di:

Sia "code_execution_20260120" che "code_execution_20260521" sono accettati in allowed_callers e sono intercambiabili: una richiesta che usa una qualsiasi delle due versioni dello strumento di esecuzione del codice soddisfa gli strumenti che elencano uno qualsiasi dei due chiamanti. I blocchi di risposta etichettano sempre il chiamante come code_execution_20260120 indipendentemente dalla versione dichiarata nella richiesta.

Omettere "direct" dall'array (ad esempio, "allowed_callers": ["code_execution_20260120"]) induce Claude a chiamare lo strumento solo dall'interno dell'esecuzione del codice. Il blocco tool_use della risposta include un campo caller che identifica quale chiamante ha chiamato lo strumento. Consulta Chiamata programmatica degli strumenti per la trattazione completa, inclusa la forma della risposta caller e il comportamento in caso di errore.

defer_loading e cache dei prompt

Gli strumenti con defer_loading: true vengono rimossi dalla sezione degli strumenti renderizzata prima che venga calcolata la chiave di cache. Non compaiono affatto nel prefisso del prompt di sistema. Quando la ricerca strumenti scopre uno strumento differito e restituisce un tool_reference per esso, la definizione completa dello strumento viene espansa inline in quel punto del corpo della conversazione, non nel prefisso.

Questo significa che defer_loading: true preserva la tua "prompt caching" (cache dei prompt). Puoi aggiungere strumenti differiti a una richiesta senza invalidare una voce di cache esistente, e la cache resta valida sia nel turno in cui lo strumento viene scoperto sia nel turno in cui viene chiamato.

Per sapere come combinare defer_loading con i breakpoint cache_control, consulta le indicazioni sulla cache dei prompt dello strumento di ricerca strumenti.