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, invece di richiedere round trip attraverso il modello per ogni invocazione di strumento. Questo riduce la "latency" (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 agentica come BrowseComp e DeepSearchQA, che testano la ricerca web multistep 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% in meno di token di input (vedi Improved web search with dynamic filtering).

Considera la verifica della conformità al budget per 20 dipendenti: l'approccio tradizionale richiede 20 round trip separati del modello, portando 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.



Compatibilità dei modelli

La chiamata programmatica degli strumenti richiede code_execution_20260120 o versioni successive, che è supportato sui seguenti modelli:

Per la matrice completa delle versioni dello strumento di esecuzione del codice, vedi la tabella di compatibilità dei modelli dello strumento di esecuzione del codice. La chiamata programmatica degli strumenti è disponibile sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry. Su Microsoft Foundry, la chiamata programmatica degli strumenti richiede un deployment Hosted on Anthropic. Non è attualmente disponibile su Amazon Bedrock o Google Cloud.



Avvio rapido

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-5",
    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)

La risposta si ferma con stop_reason: "tool_use", un ID container e un blocco tool_use per query_database il cui campo caller identifica l'esecuzione del codice che lo ha chiamato. Restituisci il risultato come mostrato nel Passo 3 del flusso di lavoro di esempio in modo che il codice possa terminare.



Come funziona la chiamata programmatica degli strumenti

Quando configuri uno strumento in modo che sia chiamabile dall'esecuzione del codice e Claude decide di usare 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 container sandbox tramite l'esecuzione del codice
3. Quando viene chiamata una funzione 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 multistep: Risparmia token e latency chiamando gli strumenti in serie o in un ciclo senza campionare Claude tra una chiamata di strumento 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"] - 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 codice

Sia "code_execution_20260120" che "code_execution_20260521" sono accettati in allowed_callers e sono intercambiabili: una richiesta che utilizza una qualsiasi delle due versioni dello strumento di esecuzione del codice soddisfa gli strumenti che elencano uno dei due chiamanti. I blocchi di risposta etichettano sempre il chiamante come code_execution_20260120 indipendentemente dalla versione dichiarata nella richiesta.



Il campo caller nelle risposte

Ogni 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 è l'id del blocco server_tool_use di esecuzione del codice che ha effettuato la chiamata, quindi puoi abbinare ogni tool_use programmatico all'esecuzione del codice che lo ha prodotto.



Ciclo di vita del container

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

• Creazione del container: Un nuovo container viene creato per ogni richiesta a meno che tu non ne riutilizzi uno esistente
• ID del container: Restituito nelle risposte nel campo container, insieme a un timestamp expires_at
• Riutilizzo: Passa l'ID del container nella richiesta successiva per mantenere lo stato. Mentre una chiamata programmatica di strumento è in attesa del tuo risultato, l'ID del container è obbligatorio su quella richiesta, non opzionale: l'API rifiuta la richiesta senza di esso.
• Scadenza: expires_at ti dice quanto tempo rimane al container. I container inattivi vengono attualmente recuperati dopo circa 5 minuti, e nessun container può essere riutilizzato più di 30 giorni dopo la sua creazione.



Flusso di lavoro di esempio

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



Passo 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 di Avvio rapido: 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 passi 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".



Passo 2: Risposta dell'API con chiamata dello 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": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, 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"
}



Passo 3: Fornisci il risultato dello strumento

Invia la cronologia completa della conversazione più il risultato del tuo strumento. Tre dettagli sono importanti in questa richiesta:

• Il messaggio utente che trasporta il tuo risultato può contenere solo blocchi tool_result. Vedi Restrizioni di formattazione dei messaggi.
• Passa l'ID container dalla risposta in pausa. L'API rifiuta una continuazione che ha chiamate programmatiche di strumenti in sospeso ma nessun ID del container.
• Invia lo stesso array tools della richiesta originale. Lo strumento di esecuzione del codice deve essere ancora presente affinché il codice in pausa riprenda, e gli strumenti che invii in questa richiesta sono le definizioni che Claude e il codice in esecuzione possono usare per il resto del turno.

response = client.messages.create(
    model="claude-opus-5",
    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}, ...]',
                }
            ],
        },
    ],
    # Stesso array di strumenti della richiesta originale
    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)



Passo 4: Chiamata dello strumento successiva o completamento

Il codice riprende da dove si era fermato ed elabora il tuo risultato. Ogni risposta di continuazione si mette nuovamente in pausa con altri blocchi tool_use programmatici, oppure completa l'esecuzione del codice e consente a Claude di continuare il turno (Passo 5). Controlla stop_reason e il caller di ogni blocco tool_use per distinguere i due casi: una risposta che si mette in pausa per te ha stop_reason: "tool_use" e un blocco tool_use il cui caller indica una versione di esecuzione del codice, e tu ripeti il Passo 3 con un tool_result per ogni chiamata programmatica in sospeso in un unico messaggio utente.



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



Pattern avanzati



Elaborazione in batch con cicli

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

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# 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 di dati grezzi



Terminazione anticipata

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

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health({"endpoint": endpoint})
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break  # Stop early, don't check remaining



Selezione condizionale degli strumenti

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)



Filtraggio dei dati

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)



Formato della risposta



Chiamata programmatica dello 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 del tuo strumento viene passato indietro 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 degli 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 dello strumento

Se il risultato del tuo strumento non arriva entro circa 4 minuti, la chiamata in sospeso solleva un TimeoutError all'interno del codice in esecuzione di Claude. Claude vede l'errore in stderr e tipicamente riprova la chiamata:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Per prevenire i timeout:

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



Errori di esecuzione degli strumenti

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



Limitazioni dello schema di input

Gli strumenti personalizzati il cui input_schema contiene un $ref ricorsivo (un ciclo di riferimento, come uno schema che fa riferimento a se stesso) non possono essere abilitati per la chiamata programmatica. Includere una versione dello strumento di esecuzione del codice in allowed_callers per un tale strumento causa il fallimento della richiesta con un 400 invalid_request_error il cui messaggio contiene Circular $ref detected. Lo stesso schema è accettato per la chiamata diretta degli strumenti.

Per aggirare questo problema, fai una delle seguenti cose:

• Mantieni lo strumento solo diretto omettendo allowed_callers (o impostandolo su ["direct"]). Gli altri strumenti nella stessa richiesta possono comunque usare la chiamata programmatica.
• Rimuovi il ciclo dallo schema. Ad esempio, srotola la ricorsione a una profondità fissa e descrivi qualsiasi annidamento più profondo nella description del livello più interno, oppure sostituisci la proprietà ricorsiva con un semplice {"type": "object"} la cui description spiega la forma prevista.



Restrizioni degli strumenti

I seguenti strumenti non possono essere chiamati in modo programmatico:

• Strumenti forniti da un connettore MCP



Restrizioni di formattazione dei messaggi

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

Risposte con solo risultati degli strumenti: Se ci sono chiamate programmatiche di 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 degli 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 degli 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) degli strumenti. Per le normali chiamate di strumenti lato client, puoi includere contenuto testuale dopo i risultati degli strumenti.

Contenuto del risultato dello strumento solo testuale: Il content di ogni tool_result che risponde a una chiamata programmatica deve essere una stringa o blocchi text. I tipi di blocco di contenuto immagine, documento e altri vengono rifiutati.



Limiti di velocità

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



Valida i risultati degli strumenti prima dell'uso

Quando implementi 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, sii consapevole dei rischi di code injection se l'output verrà interpretato o eseguito come codice.



Efficienza dei token

La chiamata programmatica degli strumenti riduce il consumo di token in tre modi:

• 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 e altre trasformazioni non consumano token del modello
• Più chiamate di strumenti in un'unica esecuzione del codice - riduce l'overhead rispetto a 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.

Nelle valutazioni interne di Anthropic su un modello Claude di produzione:

• Su un benchmark di agente di gestione progetti con 75 strumenti, l'abilitazione della chiamata programmatica degli strumenti ha ridotto i token di input fatturati di circa il 38% senza alcun cambiamento nell'accuratezza del compito.
• Su τ²-bench (domini aereo, retail e telecomunicazioni), dove ogni turno effettua una o due chiamate sequenziali di strumenti, la chiamata programmatica degli strumenti ha lasciato i punteggi invariati ed è costata circa l'8% in più. I flussi di lavoro sequenziali a chiamata singola non ne traggono beneficio.
• Nel traffico API di produzione, le richieste il cui array 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 con la forma del carico di lavoro. Vedi Quando usare la chiamata programmatica.



Utilizzo e prezzi

La chiamata programmatica degli strumenti utilizza gli stessi prezzi dell'esecuzione del codice. Vedi 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 il formato (struttura JSON e tipi di campo)
• Restituisci dati strutturati: JSON o altri formati leggibili dalla macchina funzionano meglio per l'elaborazione programmatica
• Mantieni le risposte concise: Restituisci solo i dati necessari per ridurre al minimo l'overhead di elaborazione



Quando usare la chiamata programmatica

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 del modello. Se questo scambio conviene dipende dalla forma del carico di lavoro.

Adatto:

• Operazioni fan-out o parallele su molti elementi (ad esempio, controllare 50 endpoint o cercare 20 record)
• Grandi risultati di strumenti che possono essere filtrati, aggregati o riassunti prima di raggiungere il contesto di Claude
• Ricerca e recupero agentici, dove l'interrogazione iterativa e il filtraggio dei risultati dominano il flusso di lavoro

Poco adatto:

• Flussi di lavoro strettamente sequenziali in cui ogni chiamata dipende dal ragionamento di Claude sul risultato precedente, perché lo script non può saltare il round trip del modello in quel caso
• Un piccolo numero di chiamate di strumenti con risposte piccole, specialmente al primo turno di una conversazione, dove l'overhead del container e dello script può superare i risparmi
• Strumenti che richiedono un feedback immediato dell'utente tra le chiamate

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 su larga scala.



Ottimizzazione delle prestazioni

• Riutilizza i container 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

invalid_request_error quando si imposta tool_choice

• tool_choice non può indicare uno strumento il cui allowed_callers omette "direct". Aggiungi "direct" agli allowed_callers di quello strumento, oppure rimuovi lo strumento da tool_choice e lascia che Claude lo invochi dal codice.

Scadenza del container

• Rispondi a ogni chiamata programmatica di strumento ben prima del timestamp expires_at della risposta in pausa. Il codice di Claude smette di attendere un risultato dopo circa 4 minuti, e i container inattivi vengono attualmente recuperati dopo circa 5 minuti.
• Considera di implementare un'esecuzione più veloce degli strumenti

Risultato dello strumento non analizzato correttamente

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



Suggerimenti per il debug

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



Perché la chiamata programmatica degli strumenti funziona

Claude è addestrato su grandi quantità di codice, quindi presentare gli strumenti come funzioni Python chiamabili gli consente di sfruttare questo punto di forza:

• Composizione degli strumenti: Chiamate concatenate, cicli e condizionali sono normale flusso di controllo Python invece di una serie di round trip del modello
• Elaborazione dei risultati: Il codice di Claude filtra e aggrega grandi output degli strumenti, o li scrive su file, e solo l'output finale entra nella finestra di contesto
• Latency: Il modello non viene ricampionato tra le chiamate degli strumenti all'interno di un'unica esecuzione del codice



Implementazioni alternative

La chiamata programmatica degli strumenti è un pattern generalizzabile che può anche essere implementato sulla tua infrastruttura. Ecco come si confrontano gli 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:

• Riprogettazione minima della tua applicazione
• 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 di code injection

Usalo quando: La tua applicazione può eseguire in sicurezza codice arbitrario, vuoi l'implementazione più piccola e l'offerta gestita di Anthropic non soddisfa le tue esigenze.



Esecuzione sandbox autogestita

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

Vantaggi:

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

Svantaggi:

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

Usalo quando: La sicurezza è critica e la soluzione gestita di Anthropic non soddisfa i tuoi requisiti.



Esecuzione gestita da Anthropic

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 delle invocazioni degli strumenti.

Vantaggi:

• Sicuro e protetto per impostazione predefinita
• Abilitato con una definizione di strumento, senza infrastruttura da gestire
• Ambiente e istruzioni ottimizzati per Claude

Considera l'uso della soluzione gestita di Anthropic se stai usando la Claude API, Claude Platform on AWS o Microsoft Foundry. Su Microsoft Foundry, la chiamata programmatica degli strumenti richiede un deployment Hosted on Anthropic.



Conservazione dei dati

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 in tutte le funzionalità, vedi API e conservazione dei dati.



Prossimi passi