Programmatic tool calling

Programmatic tool calling consente a Claude di scrivere codice che chiama i tuoi strumenti in modo programmatico all'interno di un contenitore di esecuzione del codice, piuttosto che richiedere round trip attraverso il modello per ogni invocazione dello strumento. Questo riduce la latenza per i flussi di lavoro multi-strumento e diminuisce il consumo di token consentendo a Claude di filtrare o elaborare i dati prima che raggiungano la finestra di contesto del modello. Su benchmark di ricerca agentiva come BrowseComp e DeepSearchQA, che testano la ricerca web multi-step e il recupero di informazioni complesse, l'aggiunta di programmatic tool calling in cima agli strumenti di ricerca di base è stato il fattore chiave che ha completamente sbloccato le prestazioni dell'agente.

La differenza si compone rapidamente nei flussi di lavoro reali. Considera il controllo della conformità del budget su 20 dipendenti: l'approccio tradizionale richiede 20 round trip separati del modello, tirando migliaia di voci di spesa nel contesto lungo il percorso. Con programmatic tool calling, un singolo script esegue tutti e 20 i lookup, filtra i risultati e restituisce solo i dipendenti che hanno superato i loro limiti, riducendo ciò che Claude deve ragionare da centinaia di kilobyte a poche righe.

Compatibilità del modello

Programmatic tool calling richiede code_execution_20260120, che è supportato sui seguenti modelli:

Per la matrice completa delle versioni dello strumento di esecuzione del codice, vedi la tabella di compatibilità del modello dello strumento di esecuzione del codice. Programmatic tool calling è disponibile tramite l'API Claude e Microsoft Foundry.

Avvio rapido

Ecco un semplice esempio in cui Claude interroga programmaticamente un database più volte e aggrega i risultati:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

Come funziona il programmatic tool calling

Quando configuri uno strumento per essere richiamabile dall'esecuzione del codice e Claude decide di utilizzare quello strumento:

1. Claude scrive codice Python che invoca lo strumento come una funzione, potenzialmente includendo più chiamate di strumenti e logica di pre/post-elaborazione
2. Claude esegue questo codice in un contenitore sandbox tramite l'esecuzione del codice
3. Quando viene chiamata una funzione dello strumento, l'esecuzione del codice si interrompe e l'API restituisce un blocco tool_use
4. Fornisci il risultato dello strumento e l'esecuzione del codice continua (i risultati intermedi non vengono caricati nella finestra di contesto di Claude)
5. Una volta completata l'esecuzione di tutto il codice, Claude riceve l'output finale e continua a lavorare sul compito

Questo approccio è particolarmente utile per:

• Elaborazione di grandi dati: Filtra o aggrega i risultati degli strumenti prima che raggiungano il contesto di Claude
• Flussi di lavoro multi-step: Risparmia token e latenza chiamando gli strumenti in serie o in un ciclo senza campionare Claude tra le chiamate degli strumenti
• Logica condizionale: Prendi decisioni basate sui risultati intermedi degli strumenti

Concetti fondamentali

Il campo allowed_callers

Il 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"] - Solo Claude può chiamare questo strumento direttamente (predefinito se omesso)
• ["code_execution_20260120"] - Richiamabile solo dall'interno dell'esecuzione del codice
• ["direct", "code_execution_20260120"] - Richiamabile sia direttamente che dall'esecuzione del codice

Il campo caller nelle risposte

Ogni blocco di utilizzo dello strumento include un campo caller che indica come è stato invocato:

Invocazione diretta (utilizzo tradizionale dello strumento):

{
  "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.

Ciclo di vita del contenitore

Programmatic tool calling utilizza gli stessi contenitori dell'esecuzione del codice:

• Creazione del contenitore: Un nuovo contenitore viene creato per ogni sessione a meno che non riutilizzi uno esistente
• Scadenza: I contenitori hanno una durata massima di 30 giorni e vengono puliti dopo 4,5 minuti di tempo di inattività
• ID del contenitore: Restituito nelle risposte tramite il campo container
• Riutilizzo: Passa l'ID del contenitore per mantenere lo stato tra le richieste

Flusso di lavoro di esempio

Ecco come funziona un flusso di programmatic tool calling completo:

Passaggio 1: Richiesta iniziale

Invia una richiesta con esecuzione del codice e uno strumento che consente la chiamata programmatica. Per abilitare la chiamata programmatica, aggiungi il campo allowed_callers alla definizione dello strumento.

La forma della richiesta è identica all'esempio Avvio rapido: includi code_execution nell'elenco dei tuoi strumenti, aggiungi allowed_callers: ["code_execution_20260120"] a qualsiasi strumento che desideri che Claude invochi dal codice e invia il tuo messaggio utente.

Passaggio 2: Risposta API con chiamata dello strumento

Claude scrive codice che chiama il tuo strumento. L'API si interrompe 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": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Passaggio 3: Fornire il risultato dello strumento

Includi la cronologia completa della conversazione più il risultato dello strumento:

response = client.messages.create(
    model="claude-opus-4-7",
    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)

Passaggio 4: Prossima chiamata dello strumento o completamento

L'esecuzione del codice continua ed elabora i risultati. Se sono necessarie ulteriori chiamate dello strumento, ripeti il Passaggio 3 fino a quando tutte le chiamate dello strumento non sono soddisfatte.

Passaggio 5: Risposta finale

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 by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "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"
}

Modelli avanzati

Elaborazione in batch con cicli

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)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Questo modello:

• Riduce i round-trip del modello da N (uno per regione) a 1
• Elabora i set di risultati di grandi dimensioni a livello di programmazione prima di tornare a Claude
• Risparmia token restituendo solo conclusioni aggregate invece di dati grezzi

Terminazione anticipata

Claude può interrompere l'elaborazione non appena vengono soddisfatti i criteri di successo:

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

Selezione condizionale dello strumento

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)

Filtraggio dei dati

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)

Formato della risposta

Chiamata dello strumento programmatica

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"
  }
}

Gestione del risultato dello strumento

Il risultato dello 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}, ...]"
    }
  ]
}

Completamento dell'esecuzione del codice

Quando tutte le chiamate dello strumento sono soddisfatte e il codice si completa:

{
  "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": []
  }
}

Gestione degli errori

Errori comuni

Scadenza del contenitore durante la chiamata dello strumento

Se lo strumento impiega troppo tempo per rispondere, l'esecuzione del codice riceve un TimeoutError. Claude lo vede in stderr e in genere 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:

• Monitora il campo expires_at nelle risposte
• Implementa timeout per l'esecuzione dello strumento
• Considera di suddividere le operazioni lunghe in blocchi più piccoli

Errori di esecuzione dello strumento

Se lo 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.

Vincoli e limitazioni

Incompatibilità delle funzioni

• Output strutturati: Gli strumenti con strict: true non sono supportati con la chiamata programmatica
• Scelta dello strumento: Non puoi forzare la chiamata programmatica di uno strumento specifico tramite tool_choice
• Uso parallelo dello strumento: disable_parallel_tool_use: true non è supportato con la chiamata programmatica

Restrizioni degli strumenti

I seguenti strumenti attualmente non possono essere chiamati a livello di programmazione, ma il supporto potrebbe essere aggiunto nelle versioni future:

• Strumenti forniti da un connettore MCP

Restrizioni sulla formattazione dei messaggi

Quando rispondi alle chiamate dello strumento programmatico, ci sono requisiti di formattazione rigorosi:

Risposte solo con risultato dello strumento: Se ci sono chiamate dello strumento programmatico in sospeso in attesa di risultati, il tuo messaggio di risposta deve contenere solo blocchi tool_result. Non puoi includere alcun contenuto di testo, nemmeno dopo i risultati dello strumento.

Non valido - Non puoi includere testo quando rispondi alle chiamate dello strumento programmatico:

{
  "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 dello strumento quando rispondi alle chiamate dello strumento programmatico:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Questa restrizione si applica solo quando rispondi alle chiamate dello strumento programmatico (esecuzione del codice). Per le normali chiamate dello strumento lato client, puoi includere contenuto di testo dopo i risultati dello strumento.

Limiti di velocità

Le chiamate dello strumento programmatico sono soggette agli stessi limiti di velocità delle normali chiamate dello strumento. Ogni chiamata dello strumento dall'esecuzione del codice conta come una separata invocazione.

Convalida i risultati dello strumento prima dell'uso

Quando implementi strumenti definiti dall'utente che verranno chiamati a livello di programmazione:

• I risultati dello strumento vengono restituiti come stringhe: Possono contenere qualsiasi contenuto, inclusi frammenti di codice o comandi eseguibili che possono essere elaborati dall'ambiente di esecuzione.
• Convalida i risultati dello strumento esterno: Se lo strumento restituisce dati da fonti esterne o accetta input dell'utente, sii consapevole dei rischi di code injection se l'output verrà interpretato o eseguito come codice.

Efficienza dei token

La chiamata dello strumento programmatico può ridurre significativamente il consumo di token:

• I risultati dello strumento dalle chiamate programmatiche non vengono aggiunti al contesto di Claude - solo l'output finale del codice
• L'elaborazione intermedia avviene nel codice - il filtraggio, l'aggregazione, ecc. non consumano token del modello
• Più chiamate dello strumento in un'esecuzione del codice - riduce il sovraccarico rispetto ai turni del modello separati

Ad esempio, chiamare 10 strumenti direttamente utilizza ~10 volte i token di chiamarli a livello di programmazione e restituire un riepilogo.

Utilizzo e prezzi

La chiamata dello strumento programmatico utilizza gli stessi prezzi dell'esecuzione del codice. Vedi i prezzi di esecuzione del codice per i dettagli.

Migliori pratiche

Progettazione dello strumento

• Fornisci descrizioni dettagliate dell'output: Poiché Claude deserializza i risultati dello strumento nel codice, documenta chiaramente il formato (struttura JSON, tipi di campo, ecc.)
• Restituisci dati strutturati: I formati JSON o altri facilmente analizzabili funzionano meglio per l'elaborazione programmatica
• Mantieni le risposte concise: Restituisci solo i dati necessari per ridurre al minimo il sovraccarico di elaborazione

Quando utilizzare la chiamata programmatica

Buoni casi d'uso:

• Elaborazione di set di dati di grandi dimensioni in cui hai bisogno solo di aggregati o riepiloghi
• Flussi di lavoro multi-step con 3+ chiamate dello strumento dipendenti
• Operazioni che richiedono filtraggio, ordinamento o trasformazione dei risultati dello strumento
• Attività in cui i dati intermedi non dovrebbero influenzare il ragionamento di Claude
• Operazioni parallele su molti elementi (ad es. verifica di 50 endpoint)

Casi d'uso meno ideali:

• Singole chiamate dello strumento con risposte semplici
• Strumenti che necessitano di feedback immediato dell'utente
• Operazioni molto veloci in cui il sovraccarico dell'esecuzione del codice supererebbe il beneficio

Ottimizzazione delle prestazioni

• Riutilizza i contenitori quando effettui più richieste correlate per mantenere lo stato
• Raggruppa operazioni simili in un'unica esecuzione del codice quando possibile

Risoluzione dei problemi

Problemi comuni

Errore "Tool not allowed"

• Verifica che la definizione dello strumento includa "allowed_callers": ["code_execution_20260120"]

Scadenza del contenitore

• Assicurati di rispondere alle chiamate dello strumento prima che il contenitore scada (4,5 minuti di inattività; massimo fisso di 30 giorni)
• Monitora il campo expires_at nelle risposte
• Considera di implementare un'esecuzione dello strumento più veloce

Risultato dello strumento non analizzato correttamente

• Assicurati che lo strumento restituisca dati di stringa che Claude possa deserializzare
• Fornisci una chiara documentazione del formato di output nella descrizione dello strumento

Suggerimenti per il debug

1. Registra tutte le chiamate dello strumento e i risultati per tracciare il flusso
2. Controlla il campo caller per confermare l'invocazione programmatica
3. Monitora gli ID dei contenitori per assicurare il corretto riutilizzo
4. Testa gli strumenti in modo indipendente prima di abilitare la chiamata programmatica

Perché la chiamata dello strumento programmatico funziona

L'addestramento di Claude include un'ampia esposizione al codice, il che lo rende efficace nel ragionare attraverso e concatenare le chiamate di funzione. Quando gli strumenti vengono presentati come funzioni richiamabili all'interno di un ambiente di esecuzione del codice, Claude può sfruttare questa forza per:

• Ragionare naturalmente sulla composizione dello strumento: Concatenare operazioni e gestire le dipendenze come naturalmente come scrivere qualsiasi codice Python
• Elaborare i risultati di grandi dimensioni in modo efficiente: Filtrare i grandi output dello strumento, estrarre solo i dati rilevanti o scrivere i risultati intermedi nei file prima di restituire riepiloghi alla finestra di contesto
• Ridurre significativamente la latenza: Eliminare il sovraccarico del ricampionamento di Claude tra ogni chiamata dello strumento nei flussi di lavoro multi-step

Questo approccio abilita flussi di lavoro che sarebbero impraticabili con l'uso dello strumento tradizionale (come l'elaborazione di file oltre 1M token) consentendo a Claude di lavorare con i dati a livello di programmazione piuttosto che caricare tutto nella finestra di contesto della conversazione.

Implementazioni alternative

La chiamata dello strumento programmatico è un modello generalizzabile che può essere implementato al di fuori dell'esecuzione del codice gestito di Anthropic. Ecco una panoramica degli approcci:

Esecuzione diretta lato client

Fornisci a Claude uno strumento di esecuzione del codice e descrivi quali funzioni sono disponibili in quell'ambiente. Quando Claude richiama lo strumento con il codice, la tua applicazione lo esegue localmente dove quelle funzioni sono definite.

Vantaggi:

• Semplice da implementare con una riarchiettazione minima
• Controllo completo sull'ambiente e sulle istruzioni

Svantaggi:

• Esegue codice non attendibile al di fuori di una sandbox
• Le invocazioni dello strumento possono essere vettori per code injection

Usa quando: La tua applicazione può eseguire in modo sicuro codice arbitrario, desideri una soluzione semplice e l'offerta gestita di Anthropic non si adatta alle tue esigenze.

Esecuzione in sandbox auto-gestita

Lo stesso approccio dal punto di vista di Claude, ma il codice viene eseguito in un contenitore in sandbox con restrizioni di sicurezza (ad es. nessun egresso di rete). Se i tuoi strumenti richiedono risorse esterne, avrai bisogno di un protocollo per eseguire le chiamate dello strumento al di fuori della sandbox.

Vantaggi:

• Chiamata dello strumento programmatico sicura sulla tua infrastruttura
• Controllo completo sull'ambiente di esecuzione

Svantaggi:

• Complesso da costruire e mantenere
• Richiede la gestione sia dell'infrastruttura che della comunicazione tra processi

Usa quando: La sicurezza è critica e la soluzione gestita di Anthropic non si adatta alle tue esigenze.

Esecuzione gestita da Anthropic

La chiamata dello strumento programmatico di Anthropic è una versione gestita dell'esecuzione in sandbox con un ambiente Python opinato ottimizzato per Claude. Anthropic gestisce la gestione dei contenitori, l'esecuzione del codice e la comunicazione sicura dell'invocazione dello strumento.

Vantaggi:

• Sicuro e protetto per impostazione predefinita
• Facile da abilitare con una configurazione minima
• Ambiente e istruzioni ottimizzati per Claude

Considera di utilizzare la soluzione gestita di Anthropic se stai utilizzando l'API Claude.

Conservazione dei dati

La chiamata dello strumento programmatico è costruita sull'infrastruttura di esecuzione del codice e utilizza gli stessi contenitori sandbox. I dati del contenitore, inclusi gli artefatti di esecuzione e gli output, vengono conservati per un massimo di 30 giorni.

Per l'idoneità ZDR in tutte le funzioni, vedi Conservazione dell'API e dei dati.

Funzioni correlate