La chiamata programmatica degli strumenti consente a Claude di scrivere codice che chiama i tuoi strumenti in modo programmatico all'interno di un container di code execution (esecuzione di codice), invece di richiedere round-trip attraverso il modello per ogni invocazione dello strumento. Questo riduce la "latency" (latenza) per i flussi di lavoro multi-strumento e diminuisce il consumo di token permettendo a Claude di filtrare o elaborare i dati prima che raggiungano la "context window" (finestra di contesto) del modello. Sui benchmark di ricerca agentica come BrowseComp e DeepSearchQA, che testano la ricerca web multi-step e il recupero di informazioni complesse, l'aggiunta della chiamata programmatica degli strumenti sopra gli strumenti di ricerca di base ha migliorato le prestazioni in media dell'11% utilizzando il 24% di token di input in meno (vedi Improved web search with dynamic filtering).
La differenza si amplifica rapidamente nei flussi di lavoro reali. Considera la verifica della conformità al budget per 20 dipendenti: l'approccio tradizionale richiede 20 round-trip separati al modello, caricando migliaia di voci di spesa nel contesto lungo il percorso. Con la chiamata programmatica degli strumenti, un singolo script esegue tutte le 20 ricerche, filtra i risultati e restituisce solo i dipendenti che hanno superato i loro limiti, riducendo ciò su cui Claude deve ragionare da centinaia di kilobyte a una manciata di righe.
Per un'analisi più approfondita dei costi di inferenza e di contesto che la chiamata programmatica degli strumenti affronta, consulta Advanced tool use.
Questa funzionalità richiede che lo strumento di esecuzione del codice sia abilitato.
Questa funzionalità non è idonea per Zero Data Retention (ZDR). I dati vengono conservati secondo la politica di conservazione standard della funzionalità.
La chiamata programmatica degli strumenti richiede code_execution_20260120, che è supportato sui seguenti modelli:
| Modello |
|---|
| Claude Fable 5 (claude-fable-5) |
| Claude Mythos 5 (claude-mythos-5) |
| Claude Opus 4.8 (claude-opus-4-8) |
| Claude Opus 4.7 (claude-opus-4-7) |
| Claude Opus 4.6 (claude-opus-4-6) |
| Claude Sonnet 4.6 (claude-sonnet-4-6) |
| Claude Opus 4.5 (claude-opus-4-5-20251101) |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) |
Per la matrice completa delle versioni dello strumento di esecuzione del codice, consulta la tabella di compatibilità dei modelli dello strumento di esecuzione del codice. La chiamata programmatica degli strumenti è disponibile sull'API di Claude, su Claude Platform on AWS e su Microsoft Foundry. Attualmente non è disponibile su Amazon Bedrock o Vertex AI.
Ecco un esempio in cui Claude interroga programmaticamente un database più volte e aggrega i risultati:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
}
],
tools=[
{"type": "code_execution_20260120", "name": "code_execution"},
{
"name": "query_database",
"description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
"input_schema": {
"type": "object",
"properties": {
"sql": {"type": "string", "description": "SQL query to execute"}
},
"required": ["sql"],
},
"allowed_callers": ["code_execution_20260120"],
},
],
)
print(response)Quando configuri uno strumento per essere chiamabile dall'esecuzione del codice e Claude decide di usare quello strumento:
tool_useQuesto approccio è particolarmente utile per:
Gli strumenti personalizzati vengono convertiti in funzioni Python asincrone per supportare la chiamata parallela degli strumenti. Quando Claude scrive codice che chiama i tuoi strumenti, usa await (ad esempio, result = await query_database("<sql>")) e include automaticamente la funzione wrapper asincrona appropriata.
Il wrapper asincrono è omesso dagli esempi di codice in questa documentazione per chiarezza.
allowed_callersIl campo allowed_callers specifica quali contesti possono invocare uno strumento:
{
"name": "query_database",
"description": "Execute a SQL query against the database",
"input_schema": {
// ...
},
"allowed_callers": ["code_execution_20260120"]
}Valori possibili:
["direct"] - Claude è guidato a chiamare questo strumento direttamente (predefinito se omesso)["code_execution_20260120"] - Claude è guidato a chiamare questo strumento solo dall'interno dell'esecuzione del codice["direct", "code_execution_20260120"] - Claude può chiamare questo strumento direttamente o dall'interno dell'esecuzione del codiceScegli ["direct"] oppure ["code_execution_20260120"] per ogni strumento invece di abilitare entrambi, poiché questo fornisce indicazioni più chiare a Claude su come utilizzare al meglio lo strumento.
allowed_callers controlla come lo strumento viene presentato a Claude ed è validato rispetto a tool_choice, ma non è un blocco rigido a livello di API sull'invocazione diretta. Claude è fortemente guidato a rispettarlo, ma il tuo client dovrebbe comunque essere preparato a gestire un tool_use diretto per qualsiasi strumento che definisce. Non fare affidamento su allowed_callers come confine di sicurezza.
caller nelle risposteOgni blocco di uso degli strumenti include un campo caller che indica come è stato invocato:
Invocazione diretta (uso degli strumenti tradizionale):
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "sql": "<sql>" },
"caller": { "type": "direct" }
}Invocazione programmatica:
{
"type": "tool_use",
"id": "toolu_xyz789",
"name": "query_database",
"input": { "sql": "<sql>" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123"
}
}Il tool_id fa riferimento allo strumento di esecuzione del codice che ha effettuato la chiamata programmatica.
La chiamata programmatica degli strumenti utilizza gli stessi container dell'esecuzione del codice:
containerQuando uno strumento viene chiamato programmaticamente e il container è in attesa del risultato del tuo strumento, devi rispondere prima che il container scada. Monitora il campo expires_at. Se il container scade, Claude potrebbe trattare la chiamata allo strumento come andata in timeout e riprovarla.
Ecco come funziona un flusso completo di chiamata programmatica degli strumenti:
Invia una richiesta con l'esecuzione del codice e uno strumento che consente la chiamata programmatica. Per abilitare la chiamata programmatica, aggiungi il campo allowed_callers alla definizione del tuo strumento.
Fornisci descrizioni dettagliate del formato di output del tuo strumento nella descrizione dello strumento. Se specifichi che lo strumento restituisce JSON, Claude tenta di deserializzare ed elaborare il risultato nel codice. Più dettagli fornisci sullo schema di output, meglio Claude può gestire la risposta in modo programmatico.
La forma della richiesta è identica all'esempio della Guida rapida: includi code_execution nella tua lista di strumenti, aggiungi allowed_callers: ["code_execution_20260120"] a qualsiasi strumento che vuoi che Claude invochi dal codice e invia il tuo messaggio utente. I passaggi rimanenti in questo flusso di lavoro utilizzano il messaggio utente "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".
Claude scrive codice che chiama il tuo strumento. L'API si mette in pausa e restituisce:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll query the purchase history and analyze the results."
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "code_execution",
"input": {
"code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
}
},
{
"type": "tool_use",
"id": "toolu_def456",
"name": "query_database",
"input": { "sql": "<sql>" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123"
}
}
],
"container": {
"id": "container_xyz789",
"expires_at": "2026-01-20T14:30:00Z"
},
"stop_reason": "tool_use"
}Includi l'intera cronologia della conversazione più il risultato del tuo strumento:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
container="container_xyz789", # Reuse the container
messages=[
{
"role": "user",
"content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll query the purchase history and analyze the results.",
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "code_execution",
"input": {"code": "..."},
},
{
"type": "tool_use",
"id": "toolu_def456",
"name": "query_database",
"input": {"sql": "<sql>"},
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123",
},
},
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_def456",
"content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
}
],
},
],
tools=[...],
)
print(response)L'esecuzione del codice continua ed elabora i risultati. Se sono necessarie ulteriori chiamate agli strumenti, ripeti il Passaggio 3 fino a quando tutte le chiamate agli strumenti sono soddisfatte.
Una volta completata l'esecuzione del codice, Claude fornisce la risposta finale:
{
"content": [
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "code_execution_result",
"stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
"stderr": "",
"return_code": 0,
"content": []
}
},
{
"type": "text",
"text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
}
],
"stop_reason": "end_turn"
}Claude può scrivere codice che elabora più elementi in modo efficiente:
async def _claude_code():
regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
data = await query_database(f"<sql for {region}>")
results[region] = sum(row["revenue"] for row in data)
# Elabora i risultati in modo programmatico
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")
Questo pattern:
Claude può interrompere l'elaborazione non appena i criteri di successo sono soddisfatti:
async def _claude_code():
endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
status = await check_health(endpoint)
if status == "healthy":
print(f"Found healthy endpoint: {endpoint}")
break # Stop early, don't check remaining
async def _claude_code():
file_info = await get_file_info(path)
if file_info["size"] < 10000:
content = await read_full_file(path)
else:
content = await read_file_summary(path)
print(content)
async def _claude_code():
logs = await fetch_logs(server_id)
errors = [log for log in logs if "ERROR" in log]
print(f"Found {len(errors)} errors")
for error in errors[-10:]: # Only return last 10 errors
print(error)
Quando l'esecuzione del codice chiama uno strumento:
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "sql": "<sql>" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_xyz789"
}
}Il risultato del tuo strumento viene passato al codice in esecuzione:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_abc123",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
}
]
}Quando tutte le chiamate agli strumenti sono soddisfatte e il codice è completato:
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_xyz789",
"content": {
"type": "code_execution_result",
"stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
"stderr": "",
"return_code": 0,
"content": []
}
}| Errore | Descrizione | Soluzione |
|---|---|---|
invalid_tool_input | L'input dello strumento non corrisponde allo schema | Valida l'input_schema del tuo strumento |
invalid_request_error (su tool_choice) | tool_choice nomina uno strumento il cui allowed_callers non include "direct" | Aggiungi "direct" all'allowed_callers di quello strumento, oppure rimuovi lo strumento da tool_choice e lascia che Claude lo invochi dal codice |
Se il tuo strumento impiega troppo tempo a rispondere, l'esecuzione del codice riceve un TimeoutError. Claude vede questo in stderr e tipicamente riprova:
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "code_execution_result",
"stdout": "",
"stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
"return_code": 0,
"content": []
}
}Per prevenire i timeout:
expires_at nelle risposteSe il tuo strumento restituisce un errore:
{
"type": "tool_result",
"tool_use_id": "toolu_abc123",
"content": "Error: Query timeout - table lock exceeded 30 seconds"
}Il codice di Claude riceve questo errore e può gestirlo in modo appropriato.
strict: true non sono supportati con la chiamata programmaticatool_choicedisable_parallel_tool_use: true non è supportato con la chiamata programmaticaI seguenti strumenti non possono essere chiamati programmaticamente:
Quando rispondi alle chiamate programmatiche agli strumenti, ci sono requisiti di formattazione rigorosi:
Risposte con solo risultati degli strumenti: Se ci sono chiamate programmatiche agli strumenti in sospeso in attesa di risultati, il tuo messaggio di risposta deve contenere solo blocchi tool_result. Non puoi includere alcun contenuto testuale, nemmeno dopo i risultati degli strumenti.
Non valido - Non è possibile includere testo quando si risponde a chiamate programmatiche agli strumenti:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
},
{ "type": "text", "text": "What should I do next?" }
]
}Valido - Solo risultati degli strumenti quando si risponde a chiamate programmatiche agli strumenti:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
}
]
}Questa restrizione si applica solo quando si risponde a chiamate programmatiche agli strumenti (esecuzione del codice). Per le normali chiamate agli strumenti lato client, puoi includere contenuto testuale dopo i risultati degli strumenti.
Le chiamate programmatiche agli strumenti sono soggette agli stessi limiti di velocità delle normali chiamate agli strumenti. Ogni chiamata allo strumento dall'esecuzione del codice conta come un'invocazione separata.
Quando implementi strumenti definiti dall'utente che verranno chiamati programmaticamente:
La chiamata programmatica degli strumenti può ridurre significativamente il consumo di token:
Ad esempio, chiamare 10 strumenti direttamente utilizza circa 10 volte i token rispetto a chiamarli programmaticamente e restituire un riepilogo.
Nelle valutazioni interne di Anthropic su un modello Claude di produzione:
tools contiene da 10 a 49 definizioni di strumenti vedono risparmi tipici di token dal 20% al 40% con la chiamata programmatica degli strumenti abilitata.I risparmi effettivi variano in base alla forma del carico di lavoro; consulta Quando usare la chiamata programmatica.
La chiamata programmatica degli strumenti utilizza gli stessi prezzi dell'esecuzione del codice. Consulta i prezzi dell'esecuzione del codice per i dettagli.
Conteggio dei token per le chiamate programmatiche agli strumenti: i risultati degli strumenti dalle invocazioni programmatiche non contano ai fini dell'utilizzo dei token di input/output. Contano solo il risultato finale dell'esecuzione del codice e la risposta di Claude.
La chiamata programmatica degli strumenti scambia un piccolo overhead fisso (avvio del container, generazione dello script) con grandi risparmi sui token dei risultati degli strumenti e sui round-trip al modello. Se questo scambio conviene dipende dalla forma del carico di lavoro.
Adatta per:
Poco adatta per:
Se non sei sicuro, misura i token di input fatturati con e senza allowed_callers su un campione rappresentativo del tuo traffico prima di abilitarlo ampiamente.
invalid_request_error quando si imposta tool_choice
tool_choice non può nominare uno strumento il cui allowed_callers omette "direct". Aggiungi "direct" all'allowed_callers di quello strumento, oppure rimuovi lo strumento da tool_choice e lascia che Claude lo invochi dal codice.Scadenza del container
expires_at nelle risposteRisultato dello strumento non analizzato correttamente
caller per confermare l'invocazione programmaticaL'addestramento di Claude include un'ampia esposizione al codice, rendendolo efficace nel ragionare e concatenare chiamate a funzioni. Quando gli strumenti vengono presentati come funzioni chiamabili all'interno di un ambiente di esecuzione del codice, Claude può sfruttare questa forza per:
Questo approccio abilita flussi di lavoro che sarebbero impraticabili con l'uso degli strumenti tradizionale (come l'elaborazione di file oltre 1M di token) permettendo a Claude di lavorare con i dati in modo programmatico invece di caricare tutto nel contesto della conversazione.
La chiamata programmatica degli strumenti è un pattern generalizzabile che può anche essere implementato sulla tua infrastruttura. Ecco come si confrontano gli approcci:
Fornisci a Claude uno strumento di esecuzione del codice e descrivi quali funzioni sono disponibili in quell'ambiente. Quando Claude invoca lo strumento con del codice, la tua applicazione lo esegue localmente dove quelle funzioni sono definite.
Vantaggi:
Svantaggi:
Usa quando: La tua applicazione può eseguire in sicurezza codice arbitrario, vuoi una soluzione semplice e l'offerta gestita di Anthropic non soddisfa le tue esigenze.
Stesso approccio dal punto di vista di Claude, ma il codice viene eseguito in un container sandbox con restrizioni di sicurezza (ad esempio, nessun traffico di rete in uscita). Se i tuoi strumenti richiedono risorse esterne, avrai bisogno di un protocollo per eseguire le chiamate agli strumenti al di fuori della sandbox.
Vantaggi:
Svantaggi:
Usa quando: La sicurezza è critica e la soluzione gestita di Anthropic non soddisfa i tuoi requisiti.
La chiamata programmatica degli strumenti di Anthropic è una versione gestita dell'esecuzione sandbox con un ambiente Python opinionato ottimizzato per Claude. Anthropic gestisce la gestione dei container, l'esecuzione del codice e la comunicazione sicura per l'invocazione degli strumenti.
Vantaggi:
Considera di utilizzare la soluzione gestita di Anthropic se stai usando l'API di Claude, Claude Platform on AWS o Microsoft Foundry.
La chiamata programmatica degli strumenti è costruita sull'infrastruttura di esecuzione del codice e utilizza gli stessi container sandbox. I dati del container, inclusi gli artefatti di esecuzione e gli output, vengono conservati per un massimo di 30 giorni.
Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati.
Scopri la capacità di esecuzione del codice sottostante che alimenta la chiamata programmatica degli strumenti.
Comprendi i fondamenti dell'uso degli strumenti con Claude.
Guida passo-passo per definire gli strumenti.
Was this page helpful?