Uso degli strumenti con Claude

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

Ecco un esempio minimo che utilizza uno strumento server, lo strumento Web search, che Anthropic esegue per te:

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)

Claude esegue la ricerca sull'infrastruttura di Anthropic e restituisce i risultati citati nella stessa risposta. Per far sì che Claude chiami una funzione che definisci tu, passa uno strumento con un input_schema, quindi esegui la chiamata quando Claude restituisce un blocco tool_use. Definire gli strumenti e Gestire le chiamate agli strumenti coprono questo ciclo completo.



Come funziona l'uso degli strumenti

Gli strumenti differiscono principalmente per dove viene eseguito il codice. Gli strumenti client (inclusi gli strumenti definiti dall'utente e gli strumenti con schemi definiti da 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 invia un tool_result. Gli strumenti server (come web_search, web_fetch, code_execution e tool_search) vengono eseguiti sull'infrastruttura di Anthropic: vedi i risultati direttamente senza gestire l'esecuzione, a meno che Claude non chiami lo strumento nello stesso gruppo di chiamate parallele di uno dei tuoi strumenti client (vedi Motivi di arresto e fallback).

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

Per connetterti a server "Model Context Protocol", o MCP, consulta il connettore MCP. Per creare il tuo client MCP, consulta la guida del Model Context Protocol su come creare un client MCP.



Quando Claude usa gli strumenti

Con il tool_choice predefinito di {"type": "auto"}, Claude determina 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, compiti creativi 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 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 il comportamento di attivazione conservativo.

Per richiedere una chiamata a uno strumento anziché affidarti al prompting, imposta tool_choice.

La pagina di ciascuno strumento server descrive il proprio confine di attivazione in modo più dettagliato.



Scegli uno strumento

Per le stringhe type, le versioni e gli header beta, consulta Riferimento degli strumenti.



I tuoi strumenti

Per gli strumenti che definisci, scrivi lo schema e la tua applicazione esegue ogni chiamata.



Strumenti client con schema Anthropic

Anthropic pubblica lo schema e addestra Claude su di esso. La tua applicazione esegue comunque ogni chiamata e restituisce il tool_result.



Strumenti server

Gli strumenti server vengono eseguiti sull'infrastruttura di Anthropic, senza codice di gestione nella tua applicazione. Consulta Strumenti server per i meccanismi che condividono.



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 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 di uso degli strumenti, come qualsiasi altra richiesta API, la risposta include sia il conteggio dei token di input che di output nelle metriche usage riportate.

Alcuni strumenti server aggiungono costi basati sull'utilizzo oltre ai token: consulta Strumento Web search e Strumento Code execution per le rispettive tariffe.



Passaggi successivi