Uso degli strumenti con Claude
Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti, quando Claude li chiama e quale strumento è adatto al tuo compito.
Il “tool use” (uso degli strumenti), chiamato anche function calling, consente a Claude di chiamare funzioni che definisci tu o che fornisce Anthropic. Claude determina quando chiamare uno strumento in base alla richiesta dell’utente e alla descrizione dello strumento. Restituisce quindi una chiamata strutturata che viene eseguita dalla tua applicazione (strumenti client) o da Anthropic (strumenti server).
Ecco un esempio minimo che utilizza uno strumento server, lo strumento di ricerca web, che Anthropic esegue per te:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
tools=[{"type": "web_search_20260209", "name": "web_search"}],
messages=[{"role": "user", "content": "What is 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 fare in modo 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. L’esempio di strumento client mostra questo ciclo completo dall’inizio alla fine. Scopri di più su come definire gli strumenti e gestire le chiamate agli strumenti.
Come funziona l’uso degli strumenti
Gli strumenti si differenziano principalmente in base a 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 restituisce 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 in cui chiama uno dei tuoi strumenti client (vedi Motivi di arresto e fallback).
Ecco il ciclo completo per uno strumento client. La prima richiesta definisce uno strumento get_weather e Claude risponde alla domanda chiamandolo: la risposta contiene un blocco tool_use, il tuo codice esegue la ricerca e una seconda richiesta restituisce il risultato in un blocco tool_result in modo che Claude possa rispondere con la risposta.
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a given location.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]
# Claude risponde con un blocco tool_use che indica lo strumento e i suoi argomenti.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
# Richiedi al massimo una chiamata a strumento per ogni turno.
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")
# Esegui lo strumento, poi rinvia il risultato in un blocco tool_result.
weather = "15 degrees Celsius, partly cloudy" # your weather lookup goes here
messages += [
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
],
},
]
followup = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
# Claude usa il risultato per rispondere alla domanda originale.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.Gestire le chiamate agli strumenti tratta ogni passaggio in dettaglio, inclusa la formattazione dei risultati e la segnalazione degli errori; Uso parallelo degli strumenti tratta le risposte che chiamano più strumenti contemporaneamente. Per evitare di scrivere tu stesso questo ciclo, usa il tool runner: l’SDK esegue i tuoi strumenti e rimanda automaticamente i risultati.
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 Model Context Protocol (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 valore predefinito di tool_choice pari a {"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à presente 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 conservativo il comportamento di attivazione.
Per richiedere una chiamata a uno strumento anziché affidarti al prompting, imposta tool_choice.
La pagina di ciascuno strumento server descrive in maggiore dettaglio il proprio confine di attivazione.
Se il prompt dell’utente non include informazioni sufficienti per compilare tutti i parametri obbligatori di uno strumento, Claude Opus è molto più propenso a riconoscere che manca un parametro e a richiederlo. Claude Sonnet potrebbe chiederlo, specialmente quando gli viene richiesto di riflettere prima di produrre una richiesta di strumento. Ma potrebbe anche dedurre un valore ragionevole.
Ad esempio, dato uno strumento get_weather che richiede un parametro location, se chiedi a Claude “Che tempo fa?” senza specificare una località, Claude (in particolare Claude Sonnet) potrebbe indovinare valori che non hai fornito:
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "New York, NY", "unit": "fahrenheit" }
}Questo comportamento non è garantito, specialmente per prompt più ambigui e per modelli meno capaci.
Scegli uno strumento
Per le stringhe type, le versioni e gli header beta, consulta il Riferimento degli strumenti.
I tuoi strumenti
Per gli strumenti che definisci, scrivi tu lo schema e la tua applicazione esegue ogni chiamata.
Specifica gli schemi degli strumenti, scrivi le descrizioni e controlla quando Claude chiama i tuoi strumenti.
Analizza i blocchi tool_use, formatta le risposte tool_result e gestisci gli errori.
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.
Memorizza e recupera informazioni tra le conversazioni in file che controlli tu.
Esegui comandi shell in una sessione persistente che mantiene lo stato.
Visualizza e modifica file di testo per eseguire il debug, correggere e migliorare il codice.
Acquisisci screenshot e controlla mouse e tastiera in un ambiente desktop.
Naviga, leggi e interagisci con le pagine web nel tuo ambiente browser.
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.
Cerca sul web informazioni oltre la data limite delle conoscenze, con fonti citate.
Recupera il contenuto completo di pagine web e documenti PDF specificati.
Esegui codice Python e Bash in un container sandbox per analizzare dati e generare file.
Consenti a un modello esecutore più veloce di consultare un modello consulente più intelligente durante la generazione.
Lavora con migliaia di strumenti scoprendoli e caricandoli su richiesta.
Connettiti a server MCP remoti dalla Messages API senza un client MCP separato.
Prezzi
Le richieste di “tool use” (uso degli strumenti) hanno un prezzo basato su:
- Il numero totale di token di input inviati al modello (inclusi quelli nel parametro
tools). - Il numero di token di output generati.
- Per gli strumenti lato server, prezzi aggiuntivi basati 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 alla Claude API, 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
toolsnelle richieste API (nomi, descrizioni e schemi degli strumenti) - I blocchi di contenuto
tool_usenelle richieste e nelle risposte API - I blocchi di contenuto
tool_resultnelle richieste API
Quando usi tools, l’API include automaticamente anche uno speciale “system prompt” (prompt di sistema) per il modello che abilita l’uso degli strumenti. La tabella seguente elenca il numero di token per l’uso degli strumenti richiesto da ciascun modello (esclusi i token aggiuntivi elencati in precedenza). La tabella presuppone che tu fornisca almeno uno strumento. Se non fornisci alcun tools, una scelta dello strumento pari a none utilizza 0 token aggiuntivi del prompt di sistema.
| Modello | Token del prompt di sistema per l’uso degli strumenti | |
|---|---|---|
| Nome | Numero di token | |
Claude Opus 5.5For long-running agentic coding and knowledge work | auto, none | 286 token |
Claude Sonnet 5.5The best combination of speed and intelligence | auto, none | 286 token |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | auto, none | 286 token |
any, tool | 406 token | |
auto, none | 286 token | |
any, tool | 406 token | |
auto, none | 290 token | |
any, tool | 410 token | |
auto, none | 675 token | |
any, tool | 804 token | |
auto, none | 497 token | |
any, tool | 589 token | |
auto, none | 496 token | |
any, tool | 588 token | |
Claude Opus 4.1 | auto, none | 313 token |
any, tool | 315 token | |
Claude Opus 4 | auto, none | 313 token |
any, tool | 315 token | |
auto, none | 354 token | |
any, tool | 474 token | |
auto, none | 497 token | |
any, tool | 589 token | |
auto, none | 496 token | |
any, tool | 588 token | |
Claude Sonnet 4 | auto, none | 313 token |
any, tool | 315 token | |
auto, none | 496 token | |
any, tool | 588 token | |
Questi conteggi di token vengono aggiunti ai tuoi normali token di input e di output per calcolare il costo totale di una richiesta.
Consulta la tabella Tutti i modelli per i prezzi attuali per modello.
Quando invii un prompt con uso degli strumenti, come per qualsiasi altra richiesta API, la risposta include sia il conteggio dei token di input sia quello dei token di output nelle metriche usage riportate.
Alcuni strumenti server aggiungono costi basati sull’utilizzo oltre ai token: consulta Utilizzo e prezzi dello strumento di ricerca web e Utilizzo e prezzi dello strumento di esecuzione del codice per le relative tariffe.
Passaggi successivi
Comprendi il ciclo di uso degli strumenti, dove vengono eseguiti gli strumenti e quando usarli invece della prosa.
Una guida passo passo da una singola chiamata a uno strumento fino a un ciclo agentico pronto per la produzione.
Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali di definizione degli strumenti.
Questa pagina ti è stata utile?