Uso degli strumenti con Claude

Il "tool use" (uso degli strumenti), chiamato anche function calling, consente a Claude di chiamare funzioni definite da te o fornite da Anthropic. 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-5-5",
    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 fare in modo che Claude chiami una funzione definita da te, passa uno strumento con un input_schema, quindi esegui la chiamata quando Claude restituisce un blocco tool_use. Come funziona l'uso degli strumenti 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 differiscono principalmente per il luogo in cui 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 agli strumenti insieme a 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 uno strumento per 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 copre ogni passaggio in dettaglio, inclusa la formattazione dei risultati e la segnalazione degli errori; Uso parallelo degli strumenti copre le risposte che chiamano più strumenti contemporaneamente. Per evitare di scrivere tu stesso questo ciclo, usa Tool Runner: gli SDK eseguono i tuoi strumenti e restituiscono i risultati automaticamente.

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.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

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 tu, 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 "tool use" (uso degli strumenti) hanno un prezzo basato su:

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, 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 tools nelle richieste API (nomi, descrizioni e schemi degli strumenti)
• I blocchi di contenuto tool_use nelle richieste e nelle risposte API
• I blocchi di contenuto tool_result nelle 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. Il numero di token per l'uso degli strumenti richiesto per ciascun modello è elencato nella tabella seguente (esclusi i token aggiuntivi elencati in precedenza). Nota che la tabella presuppone che venga fornito almeno 1 strumento. Se non viene fornito alcun tools, una scelta dello strumento pari a none utilizza 0 token aggiuntivi del prompt di sistema.

Model	Tool use system prompt tokens
Name	Tool choice	Token count
Claude Opus 5.5For long-running agentic coding and knowledge work	auto, none	286 tokens
Claude Sonnet 5.5The best combination of speed and intelligence	auto, none	286 tokens
Claude Haiku 4.5The fastest model with near-frontier intelligence	auto, none	496 tokens
	any, tool	588 tokens
Additional models
Claude Opus 5	auto, none	286 tokens
	any, tool	406 tokens
Claude Opus 4.8	auto, none	290 tokens
	any, tool	410 tokens
Claude Opus 4.7	auto, none	675 tokens
	any, tool	804 tokens
Claude Opus 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Opus 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Opus 4.1	auto, none	313 tokens
	any, tool	315 tokens
Claude Opus 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Sonnet 5	auto, none	354 tokens
	any, tool	474 tokens
Claude Sonnet 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Sonnet 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Sonnet 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Haiku 3.5	auto, none	264 tokens
	any, tool	355 tokens

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 Panoramica dei 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 Strumento Web search e Strumento Code execution per le relative tariffe.

Passaggi successivi