Uso degli strumenti con Claude

L'uso degli strumenti consente a Claude di chiamare funzioni che definisci tu o che fornisce Anthropic. Claude decide quando chiamare uno strumento in base alla richiesta dell'utente e alla descrizione dello strumento, quindi restituisce una chiamata strutturata che la tua applicazione esegue (strumenti client) o che Anthropic esegue (strumenti server).

Ecco l'esempio più semplice che utilizza uno strumento server, dove Anthropic gestisce l'esecuzione:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)



Come funziona l'uso degli strumenti

Gli strumenti si differenziano principalmente per il luogo in cui viene eseguito il codice. Gli strumenti client (inclusi gli strumenti definiti dall'utente e gli strumenti con schema Anthropic come bash e text_editor) vengono eseguiti nella tua applicazione: Claude risponde con stop_reason: "tool_use" e uno o più blocchi tool_use, il tuo codice esegue l'operazione e tu invii un tool_result. Gli strumenti server (web_search, code_execution, web_fetch, tool_search) vengono eseguiti sull'infrastruttura di Anthropic: vedi i risultati direttamente senza gestire l'esecuzione.

Per il modello concettuale completo, incluso il ciclo agentico e quando scegliere ciascun approccio, consulta Come funziona l'uso degli strumenti.

Per connetterti ai server MCP, consulta il connettore MCP. Per creare il tuo client MCP, consulta modelcontextprotocol.io.

L'accesso agli strumenti è una delle primitive a più alto impatto che puoi fornire a un agente. Su benchmark come LAB-Bench FigQA (interpretazione di figure scientifiche) e SWE-bench (ingegneria del software nel mondo reale), l'aggiunta anche solo di strumenti di base produce guadagni di capacità sproporzionati, spesso superando le baseline degli esperti umani.



Quando Claude usa gli strumenti

Con il tool_choice predefinito di {"type": "auto"}, Claude decide a ogni turno se chiamare uno strumento o rispondere direttamente. Chiama uno strumento quando la richiesta corrisponde alla capacità descritta di quello strumento e la risposta non è già nel contesto; risponde direttamente per conoscenze stabili, attività creative e turni conversazionali.

Questo confine è orientabile tramite il tuo prompt di sistema. Se Claude non chiama gli strumenti quando te lo aspetti, un'istruzione leggera come "Use the tools to investigate before responding." aumenta in modo misurabile l'uso degli strumenti; una forma più forte come "Always call a tool first before responding." spinge ulteriormente. Al contrario, "Use your judgment about whether to call a tool or respond directly." mantiene conservativo il comportamento di attivazione.

Per una garanzia rigida piuttosto che un suggerimento, usa tool_choice.

La pagina di ciascuno strumento server descrive più in dettaglio il proprio confine di attivazione. Vedi ad esempio lo strumento di ricerca web o lo strumento di esecuzione del codice.



Esempi di uso degli strumenti

Per una guida pratica completa, consulta il tutorial. Per esempi di riferimento di singoli concetti, consulta Definire gli strumenti e Gestire le chiamate agli strumenti.



Prezzi

Le richieste di uso degli strumenti vengono tariffate in base a:

1. Il numero totale di token di input inviati al modello (inclusi quelli nel parametro tools)
2. Il numero di token di output generati
3. Per gli strumenti lato server, tariffazione aggiuntiva basata sull'utilizzo (ad esempio, la ricerca web addebita un costo per ogni ricerca eseguita)

Gli strumenti lato client hanno lo stesso prezzo di qualsiasi altra richiesta all'API di Claude, mentre gli strumenti lato server possono comportare costi aggiuntivi in base al loro utilizzo specifico.

I token aggiuntivi derivanti dall'uso degli strumenti provengono da:

• Il parametro tools nelle richieste API (nomi, descrizioni e schemi degli strumenti)
• Blocchi di contenuto tool_use nelle richieste e risposte API
• Blocchi di contenuto tool_result nelle richieste API

Quando utilizzi tools, l'API include automaticamente anche uno speciale prompt di sistema per il modello che abilita l'uso degli strumenti. Il numero di token per l'uso degli strumenti richiesti per ciascun modello è elencato di seguito (esclusi i token aggiuntivi elencati sopra). Nota che la tabella presuppone che venga fornito almeno 1 strumento. Se non vengono forniti tools, una scelta dello strumento impostata su none utilizza 0 token aggiuntivi del prompt di sistema.

Questi conteggi di token vengono aggiunti ai normali token di input e output per calcolare il costo totale di una richiesta.

Consulta la tabella panoramica dei modelli per i prezzi attuali per modello.

Quando invii un prompt con uso degli strumenti, proprio come qualsiasi altra richiesta API, la risposta restituirà sia il conteggio dei token di input che di output come parte delle metriche usage riportate.



Passaggi successivi



Scegli il tuo percorso