Chiamata programmatica degli strumenti

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 esecuzione del codice, anziché 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. Nei benchmark di ricerca agentiva come BrowseComp e DeepSearchQA, che testano la ricerca web multi-step e il recupero di informazioni complesse, l'aggiunta della chiamata programmatica degli strumenti in cima agli strumenti di ricerca di base è stato il fattore chiave che ha completamente sbloccato le prestazioni degli agenti.

La differenza si amplifica rapidamente nei flussi di lavoro reali. Considera il controllo della conformità al budget per 20 dipendenti: l'approccio tradizionale richiede 20 round-trip separati del modello, estraendo 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 poche righe.

Compatibilità del modello

Per i dettagli sulla compatibilità del modello e sulla versione degli strumenti, consulta il Riferimento agli strumenti. La chiamata programmatica degli strumenti è 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:

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_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"]
            }
        ]
    }'

Come funziona la chiamata programmatica degli strumenti

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 funzione, potenzialmente includendo più chiamate agli strumenti e logica di pre/post-elaborazione
2. Claude esegue questo codice in un container sandbox tramite l'esecuzione del codice
3. Quando viene chiamata una funzione dello strumento, l'esecuzione del codice si mette in pausa 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 tutta l'esecuzione del codice, Claude riceve l'output finale e continua a lavorare sul compito

Questo approccio è particolarmente utile per:

• Elaborazione di grandi quantità di 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 una chiamata e l'altra
• 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"] - Chiamabile solo dall'interno dell'esecuzione del codice
• ["direct", "code_execution_20260120"] - Chiamabile sia direttamente che dall'esecuzione del codice

Il campo caller nelle risposte

Ogni blocco di utilizzo degli strumenti include un campo caller che indica come è stato invocato:

Invocazione diretta (utilizzo tradizionale degli strumenti):

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

La chiamata programmatica degli strumenti utilizza gli stessi container dell'esecuzione del codice:

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

Flusso di lavoro di esempio

Ecco come funziona un flusso completo di chiamata programmatica degli strumenti:

Passaggio 1: Richiesta iniziale

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.

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

Passaggio 2: Risposta API con chiamata allo strumento

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

ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
container: container_xyz789
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: [...]
YAML

Passaggio 4: Prossima chiamata allo strumento o completamento

L'esecuzione del codice continua ed elabora i risultati. Se sono necessarie ulteriori chiamate agli strumenti, ripeti il Passaggio 3 finché tutte le chiamate agli strumenti 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"
}

Pattern avanzati

Elaborazione 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)

    # 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:

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

Terminazione anticipata

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  # Interrompi presto, non controllare i rimanenti

Selezione condizionale degli strumenti

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:]:  # Restituisci solo gli ultimi 10 errori
        print(error)

Formato della risposta

Chiamata programmatica allo strumento

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

Gestione degli errori

Errori comuni

Scadenza del container durante la chiamata allo strumento

Se il tuo strumento impiega troppo tempo a 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 del tuo strumento
• Considera di suddividere le operazioni lunghe in blocchi più piccoli

Errori di esecuzione dello strumento

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

Vincoli e limitazioni

Incompatibilità delle funzionalità

• 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 degli strumenti: disable_parallel_tool_use: true non è supportato con la chiamata programmatica

Restrizioni sugli strumenti

I seguenti strumenti non possono attualmente essere chiamati in modo programmatico, ma il supporto potrebbe essere aggiunto nelle versioni future:

• Strumenti forniti da un connettore MCP

Restrizioni di formattazione dei messaggi

Quando si risponde a chiamate programmatiche agli strumenti, ci sono requisiti di formattazione rigorosi:

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

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 (esecuzione del codice) agli strumenti. Per le normali chiamate agli strumenti lato client, puoi includere contenuto testuale dopo i risultati degli strumenti.

Limiti di frequenza

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

Valida i risultati degli strumenti prima dell'uso

Quando si implementano strumenti definiti dall'utente che verranno chiamati in modo programmatico:

• I risultati degli strumenti vengono restituiti come stringhe: Possono contenere qualsiasi contenuto, inclusi frammenti di codice o comandi eseguibili che potrebbero essere elaborati dall'ambiente di esecuzione.
• Valida i risultati degli strumenti esterni: Se il tuo strumento restituisce dati da fonti esterne o accetta input dell'utente, tieni presente i rischi di code injection se l'output verrà interpretato o eseguito come codice.

Efficienza dei token

La chiamata programmatica agli strumenti può ridurre significativamente il consumo di token:

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

Ad esempio, chiamare 10 strumenti direttamente utilizza circa 10 volte i token rispetto a chiamarli in modo programmatico e restituire un riepilogo.

Utilizzo e prezzi

La chiamata programmatica agli strumenti utilizza gli stessi prezzi dell'esecuzione del codice. Consulta i prezzi dell'esecuzione del codice per i dettagli.

Best practice

Progettazione degli strumenti

• Fornisci descrizioni dettagliate dell'output: Poiché Claude deserializza i risultati degli strumenti nel codice, documenta chiaramente il formato (struttura JSON, tipi di campo, ecc.)
• Restituisci dati strutturati: JSON o altri formati 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 usare la chiamata programmatica

Casi d'uso ideali:

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

Casi d'uso meno ideali:

• Singole chiamate agli strumenti con risposte semplici
• Strumenti che necessitano di feedback immediato dall'utente
• Operazioni molto veloci dove il sovraccarico dell'esecuzione del codice supererebbe il beneficio

Ottimizzazione delle prestazioni

• Riutilizza i container quando si effettuano 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 del tuo strumento includa "allowed_callers": ["code_execution_20260120"]

Scadenza del container

• Assicurati di rispondere alle chiamate agli strumenti prima che il container vada in idle (4,5 minuti di inattività; massimo assoluto di 30 giorni)
• Monitora il campo expires_at nelle risposte
• Considera di implementare un'esecuzione più rapida degli strumenti

Risultato dello strumento non analizzato correttamente

• Assicurati che il tuo strumento restituisca dati stringa che Claude può deserializzare
• Fornisci una documentazione chiara del formato di output nella descrizione del tuo strumento

Suggerimenti per il debug

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

Perché la chiamata programmatica agli strumenti funziona

L'addestramento di Claude include un'ampia esposizione al codice, rendendolo efficace nel ragionare e concatenare le chiamate alle funzioni. 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 degli strumenti: Concatenare operazioni e gestire le dipendenze in modo naturale come scrivere qualsiasi codice Python
• Elaborare grandi risultati in modo efficiente: Filtrare grandi output degli strumenti, estrarre solo i dati rilevanti o scrivere risultati intermedi su file prima di restituire riepiloghi alla finestra di contesto
• Ridurre significativamente la latenza: Eliminare il sovraccarico del ricampionamento di Claude tra ogni chiamata allo strumento nei flussi di lavoro multi-step

Questo approccio consente flussi di lavoro che sarebbero impraticabili con l'uso tradizionale degli strumenti (come l'elaborazione di file con oltre 1 milione di token) consentendo a Claude di lavorare con i dati in modo programmatico piuttosto che caricare tutto nel contesto della conversazione.

Implementazioni alternative

La chiamata programmatica agli strumenti è un pattern generalizzabile che può essere implementato al di fuori dell'esecuzione del codice gestita da 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 rielaborazione minima
• Pieno controllo sull'ambiente e sulle istruzioni

Svantaggi:

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

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

Esecuzione sandboxed autogestita

Stesso approccio dal punto di vista di Claude, ma il codice viene eseguito in un container sandboxed con restrizioni di sicurezza (ad es., nessun egress di rete). Se i tuoi strumenti richiedono risorse esterne, avrai bisogno di un protocollo per eseguire le chiamate agli strumenti al di fuori della sandbox.

Vantaggi:

• Chiamata programmatica sicura agli strumenti sulla tua infrastruttura
• Pieno controllo sull'ambiente di esecuzione

Svantaggi:

• Complesso da costruire e mantenere
• Richiede la gestione sia dell'infrastruttura che della comunicazione inter-processo

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

Esecuzione gestita da Anthropic

La chiamata programmatica agli strumenti di Anthropic è una versione gestita dell'esecuzione sandboxed con un ambiente Python orientato ottimizzato per Claude. Anthropic gestisce la gestione dei container, l'esecuzione del codice e la comunicazione sicura delle invocazioni degli strumenti.

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 usando l'API Claude.

Conservazione dei dati

La chiamata programmatica agli 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 in tutte le funzionalità, consulta API e conservazione dei dati.

Funzionalità correlate