Uso degli strumenti con Claude

Il "tool use" (uso degli strumenti) 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 la tua applicazione esegue (strumenti client) o che Anthropic esegue (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",
    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. Come funziona l'uso degli strumenti mostra quel 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 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 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 quel 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 invia 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",
    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 invia 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",
    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 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 costruire il tuo client MCP, consulta la guida del Model Context Protocol su come costruire 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à 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 più in dettaglio il proprio confine di attivazione.



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 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 usi 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 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 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 nella 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 lo strumento di ricerca web e lo strumento di esecuzione del codice per le loro tariffe.



Prossimi passi