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 code execution (esecuzione del codice), anziché richiedere round trip attraverso il modello per ogni invocazione dello strumento. Questo riduce la "latency" (latenza) per i flussi di lavoro multi-strumento e diminuisce il consumo di token consentendo a Claude di filtrare o elaborare i dati prima che raggiungano la "context window" (finestra di contesto) del modello. Sui benchmark di ricerca agentica come BrowseComp e DeepSearchQA, che testano la ricerca web multi-step e il recupero di informazioni complesse, l'aggiunta della chiamata programmatica degli strumenti sopra gli strumenti di ricerca di base ha migliorato le prestazioni in media dell'11% utilizzando il 24% di token di input in meno (vedi Improved web search with dynamic filtering).

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

Per la matrice completa delle versioni dello strumento di esecuzione del codice, consulta la tabella di compatibilità dei modelli dello strumento di esecuzione del codice. La chiamata programmatica degli strumenti è disponibile sull'API di Claude, su Claude Platform on AWS e su Microsoft Foundry. Su Microsoft Foundry, la chiamata programmatica degli strumenti richiede un deployment Hosted on Anthropic. Attualmente non è 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-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

La risposta si interrompe 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 Passaggio 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 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, includendo potenzialmente più chiamate a 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 le chiamate agli 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"] - 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 delle due versioni dello strumento di esecuzione del codice soddisfa gli strumenti che elencano uno dei due caller. I blocchi di risposta contrassegnano sempre il caller come code_execution_20260120 indipendentemente dalla versione dichiarata nella richiesta.



Il campo caller nelle risposte

Ogni blocco tool use 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, così 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: Viene creato un nuovo container per ogni richiesta a meno che 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 a uno strumento è in attesa del tuo risultato, l'ID del container è obbligatorio in quella richiesta, non opzionale: l'API rifiuta la richiesta senza di esso.
• Scadenza: expires_at ti indica quanto tempo rimane al container. I container inattivi vengono attualmente recuperati dopo circa 5 minuti, e nessun container può essere riutilizzato oltre 30 giorni dopo la sua creazione.



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 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 passaggi rimanenti in questo flusso di lavoro utilizzano il messaggio utente "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".



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



Passaggio 3: Fornisci il risultato dello strumento

Invia l'intera cronologia 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 agli 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 possa riprendere, e gli strumenti che invii in questa richiesta sono le definizioni che Claude e il codice in esecuzione possono utilizzare per il resto del turno.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll query the purchase history and analyze the results.",
                },
                {
                    "type": "server_tool_use",
                    "id": "srvtoolu_abc123",
                    "name": "code_execution",
                    "input": {"code": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    # 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)



Passaggio 4: Chiamata successiva allo strumento 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 (Passaggio 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 ripeti il Passaggio 3 con un tool_result per ogni chiamata programmatica in sospeso in un unico messaggio utente.



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: [{'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 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 restituirli 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 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 del tuo strumento viene passato al codice in esecuzione:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}



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 risultato del tuo strumento non arriva entro circa 4 minuti, la chiamata in sospeso genera un TimeoutError all'interno del codice in esecuzione di Claude. Claude vede l'errore in stderr e in genere 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 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à di funzionalità

• Output strutturati: Gli strumenti con strict: true non sono supportati con la chiamata programmatica
• Tool choice: 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



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 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 agli strumenti.

Per aggirare questo problema, esegui una delle seguenti operazioni:

• Mantieni lo strumento solo diretto omettendo allowed_callers (o impostandolo su ["direct"]). Altri strumenti nella stessa richiesta possono comunque utilizzare la chiamata programmatica.
• Rimuovi il ciclo dallo schema. Ad esempio, srotola la ricorsione fino 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 sugli strumenti

I seguenti strumenti non possono essere chiamati in modo programmatico:

• Strumenti forniti da un connettore MCP



Restrizioni di formattazione dei messaggi

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

Risposte solo con tool result: Se ci sono chiamate programmatiche agli strumenti in sospeso in attesa di risultati, il tuo messaggio di risposta deve contenere solo blocchi tool_result. Non puoi includere alcun contenuto di testo, nemmeno dopo i risultati degli strumenti.

Non valido - Non è possibile includere testo quando si risponde a chiamate programmatiche agli strumenti:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Valido - Solo risultati degli strumenti quando si risponde a chiamate programmatiche agli strumenti:

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

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

Contenuto del tool result solo testo: 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 agli strumenti sono soggette agli stessi limiti di velocità delle normali chiamate agli strumenti. Ogni chiamata a uno 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 agli strumenti in una singola 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 project management con 75 strumenti, l'abilitazione della chiamata programmatica degli strumenti ha ridotto i token di input fatturati di circa il 38% senza alcuna variazione nell'accuratezza del compito.
• Su τ²-bench (domini airline, retail e telecom), dove ogni turno effettua una o due chiamate sequenziali agli 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 registrano risparmi tipici di token dal 20% al 40% con la chiamata programmatica degli strumenti abilitata.

I risparmi effettivi variano in base alla forma del carico di lavoro. Vedi Quando usare la chiamata programmatica.



Utilizzo e prezzi

La chiamata programmatica degli 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 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)
• Risultati di strumenti di grandi dimensioni 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 agli 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 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 ampiamente.



Ottimizzazione delle prestazioni

• Riutilizza i container quando effettui più richieste correlate per mantenere lo stato
• Raggruppa operazioni simili in una singola 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" all'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 allo 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ù 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 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 output di strumenti di grandi dimensioni, o li scrive su file, e solo l'output finale entra nella finestra di contesto
• Latenza: Il modello non viene ricampionato tra le chiamate agli strumenti all'interno di una singola 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 del codice, la tua applicazione lo esegue localmente dove quelle funzioni sono definite.

Vantaggi:

• Ri-architettura minima della tua applicazione
• Controllo completo 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 sicurezza codice arbitrario, desideri 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 traffico di rete in uscita). Se i tuoi strumenti richiedono risorse esterne, avrai bisogno di un protocollo per eseguire le chiamate agli strumenti al di fuori della sandbox.

Vantaggi:

• Chiamata programmatica sicura degli strumenti sulla tua infrastruttura
• Controllo completo 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 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 eseguire
• Ambiente e istruzioni ottimizzati per Claude

Considera di utilizzare la soluzione gestita di Anthropic se stai utilizzando l'API di Claude, 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 su tutte le funzionalità, consulta API e conservazione dei dati.



Passaggi successivi