Chiamata di strumenti programmatica

La chiamata di strumenti programmatica consente a Claude di scrivere codice che chiama i tuoi strumenti programmaticamente all'interno di un contenitore di esecuzione del codice, piuttosto che richiedere round trip attraverso il modello per ogni invocazione di 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.

Compatibilità del modello

La chiamata di strumenti programmatica è disponibile sui seguenti modelli:

Avvio rapido

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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_20250825",
                "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_20250825"]
            }
        ]
    }'

Come funziona la chiamata di strumenti programmatica

Quando configuri uno strumento per essere chiamabile 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 strumento 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 del 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 dello strumento 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 dello strumento
• Logica condizionale: Prendi decisioni in base ai risultati intermedi dello strumento

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

Valori possibili:

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

La chiamata di strumenti programmatica 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 scadono dopo circa 4,5 minuti di inattività (soggetto a modifiche)
• 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 lavoro completo di chiamata di strumenti programmatica:

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.

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20250825", "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": {...},
            "allowed_callers": ["code_execution_20250825"],
        },
    ],
)

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_20250825",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Passaggio 3: Fornisci il risultato dello strumento

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

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

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 batch con cicli

Claude può scrivere codice che elabora più elementi in modo efficiente:

# async wrapper omitted for clarity
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 set di risultati di grandi dimensioni programmaticamente 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 wrapper omitted for clarity
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 wrapper omitted for clarity
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 wrapper omitted for clarity
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_20250825",
    "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 riceverà un TimeoutError. Claude lo vede in stderr e di solito ritenterà:

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

# Provide error information in the tool result
{
    "type": "tool_result",
    "tool_use_id": "toolu_abc123",
    "content": "Error: Query timeout - table lock exceeded 30 seconds",
}

Il codice di Claude riceverà 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
• Utilizzo 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 programmaticamente, ma il supporto potrebbe essere aggiunto nelle versioni future:

• Ricerca web
• Recupero web
• Strumenti forniti da un connettore MCP

Restrizioni sulla formattazione dei messaggi

Quando rispondi a chiamate di strumenti programmatiche, ci sono rigorosi requisiti di formattazione:

Risposte solo con risultato dello strumento: Se ci sono chiamate di strumenti programmatiche 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.

// ❌ INVALID - Cannot include text when responding to programmatic tool calls
{
  "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?"}  // This will cause an error
  ]
}

// ✅ VALID - Only tool results when responding to programmatic tool calls
{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"}
  ]
}

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

Limiti di velocità

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

Convalida i risultati dello strumento prima dell'uso

Quando implementi strumenti personalizzati che verranno chiamati programmaticamente:

• I risultati dello strumento vengono restituiti come stringhe: Possono contenere qualsiasi contenuto, inclusi frammenti di codice o comandi eseguibili che potrebbero essere elaborati dall'ambiente di esecuzione.
• Convalida i risultati degli strumenti esterni: Se il tuo 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 di strumenti programmatica 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 - filtraggio, aggregazione, ecc. non consumano token del modello
• Più chiamate di strumento in un'esecuzione di codice - riduce l'overhead rispetto ai turni di modello separati

Ad esempio, chiamare 10 strumenti direttamente utilizza ~10x i token di chiamarli programmaticamente e restituire un riepilogo.

Utilizzo e prezzi

La chiamata di strumenti programmatica utilizza gli stessi prezzi dell'esecuzione del codice. Vedi i prezzi dell'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 l'overhead 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 di strumento dipendenti
• Operazioni che richiedono filtraggio, ordinamento o trasformazione dei risultati dello strumento
• Compiti in cui i dati intermedi non dovrebbero influenzare il ragionamento di Claude
• Operazioni parallele su molti elementi (ad esempio, verifica di 50 endpoint)

Casi d'uso meno ideali:

• Singole chiamate di strumento con risposte semplici
• Strumenti che necessitano di feedback immediato dell'utente
• Operazioni molto veloci in cui l'overhead 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 di codice quando possibile

Risoluzione dei problemi

Problemi comuni

Errore "Tool not allowed"

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

Scadenza del contenitore

• Assicurati di rispondere alle chiamate dello strumento entro la durata del contenitore (~4,5 minuti)
• Monitora il campo expires_at nelle risposte
• Considera di implementare un'esecuzione dello strumento più veloce

Risultato dello strumento non analizzato correttamente

• Assicurati che il tuo 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 indipendentemente prima di abilitare la chiamata programmatica

Perché la chiamata di strumenti programmatica funziona

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

• Ragionare naturalmente sulla composizione dello strumento: Concatenare operazioni e gestire le dipendenze naturalmente come scrivere qualsiasi codice Python
• Elaborare risultati di grandi dimensioni in modo efficiente: Filtrare gli output di grandi dimensioni dello strumento, estrarre solo i dati rilevanti o scrivere i risultati intermedi in file prima di restituire riepiloghi alla finestra di contesto
• Ridurre significativamente la latenza: Eliminare l'overhead 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'utilizzo tradizionale dello strumento, come l'elaborazione di file oltre 1M token, consentendo a Claude di lavorare con i dati programmaticamente piuttosto che caricare tutto nel contesto della conversazione.

Implementazioni alternative

La chiamata di strumenti programmatica è un modello generalizzabile che può essere implementato al di fuori dell'esecuzione del codice gestita 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 invoca 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 l'iniezione di codice

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 sandbox auto-gestita

Lo stesso approccio dal punto di vista di Claude, ma il codice viene eseguito in un contenitore sandbox con restrizioni di sicurezza (ad esempio, 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 di strumenti programmatica 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 di strumenti programmatica di Anthropic è una versione gestita dell'esecuzione sandbox con un ambiente Python opinato sintonizzato per Claude. Anthropic gestisce la gestione dei contenitori, l'esecuzione del codice e la comunicazione sicura dell'invocazione dello strumento.

Vantaggi:

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

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

Funzioni correlate