• Messaggi
  • Agenti gestiti
  • Amministrazione

Search...
⌘K
Primi passi
Introduzione a ClaudeGuida rapida
Sviluppare con Claude
Panoramica delle funzionalitàUtilizzo dell'API MessagesMotivi di interruzione e fallbackRifiuti e fallbackCredito di fallback
Capacità del modello
Pensiero estesoPensiero adattivoSforzoBudget delle attività (beta)Modalità veloce (anteprima di ricerca)Output strutturatiCitazioniStreaming dei messaggiElaborazione batchRisultati di ricercaStreaming dei rifiutiSupporto multilingueEmbedding
Strumenti
PanoramicaCome funziona l'uso degli strumentiTutorial: Creare un agente che usa strumentiDefinire gli strumentiGestire le chiamate agli strumentiUso degli strumenti in paralleloTool Runner (SDK)Uso degli strumenti rigorosoUso degli strumenti con cache dei promptStrumenti serverRisoluzione dei problemiStrumento di ricerca webStrumento di recupero webStrumento di esecuzione codiceStrumento advisorStrumento di memoriaStrumento BashStrumento di uso del computerStrumento editor di testo
Infrastruttura degli strumenti
Riferimento degli strumentiGestire il contesto degli strumentiCombinazioni di strumentiRicerca di strumentiChiamata programmatica degli strumentiStreaming granulare degli strumenti
Gestione del contesto
Finestre di contestoCompattazioneModifica del contestoCache dei promptMessaggi di sistema a metà conversazioneCreare una modalità di orchestrazioneDiagnostica della cache (beta)Conteggio dei token
Lavorare con i file
API FilesSupporto PDFImmagini e visione
Skill
PanoramicaGuida rapidaBest practiceSkill per le aziendeSkill nell'API
MCP
Server MCP remotiConnettore MCP
Claude su piattaforme cloud
Amazon BedrockAmazon Bedrock (legacy)Claude Platform su AWSMicrosoft FoundryVertex AI

Log in
Chiamata programmatica degli strumenti
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Claude on AWS
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Messaggi/Infrastruttura degli strumenti

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 di codice), invece di 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 permettendo 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).

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



Per un'analisi più approfondita dei costi di inferenza e di contesto che la chiamata programmatica degli strumenti affronta, consulta Advanced tool use.



Questa funzionalità richiede che lo strumento di esecuzione del codice sia abilitato.



Questa funzionalità non è idonea per Zero Data Retention (ZDR). I dati vengono conservati secondo la politica di conservazione standard della funzionalità.

Compatibilità dei modelli

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

Modello
Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

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. Attualmente non è disponibile su Amazon Bedrock o Vertex AI.

Guida rapida

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)

Come funziona la chiamata programmatica degli strumenti

Quando configuri uno strumento per essere chiamabile dall'esecuzione del codice e Claude decide di usare 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


Gli strumenti personalizzati vengono convertiti in funzioni Python asincrone per supportare la chiamata parallela degli strumenti. Quando Claude scrive codice che chiama i tuoi strumenti, usa await (ad esempio, result = await query_database("<sql>")) e include automaticamente la funzione wrapper asincrona appropriata.

Il wrapper asincrono è omesso dagli esempi di codice in questa documentazione per chiarezza.

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


Scegli ["direct"] oppure ["code_execution_20260120"] per ogni strumento invece di abilitare entrambi, poiché questo fornisce indicazioni più chiare a Claude su come utilizzare al meglio lo strumento.



allowed_callers controlla come lo strumento viene presentato a Claude ed è validato rispetto a tool_choice, ma non è un blocco rigido a livello di API sull'invocazione diretta. Claude è fortemente guidato a rispettarlo, ma il tuo client dovrebbe comunque essere preparato a gestire un tool_use diretto per qualsiasi strumento che definisce. Non fare affidamento su allowed_callers come confine di sicurezza.

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 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: Un nuovo container viene creato per ogni richiesta a meno che tu non ne riutilizzi uno esistente
  • Scadenza: I container hanno una durata massima di 30 giorni e vengono eliminati dopo 4,5 minuti di inattività
  • ID del container: Restituito nelle risposte nel campo container
  • Riutilizzo: Passa l'ID del container per mantenere lo stato tra le richieste


Quando uno strumento viene chiamato programmaticamente e il container è in attesa del risultato del tuo strumento, devi rispondere prima che il container scada. Monitora il campo expires_at. Se il container scade, Claude potrebbe trattare la chiamata allo strumento come andata in timeout e riprovarla.

Esempio di flusso di lavoro

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.



Fornisci descrizioni dettagliate del formato di output del tuo strumento nella descrizione dello strumento. Se specifichi che lo strumento restituisce JSON, Claude tenta di deserializzare ed elaborare il risultato nel codice. Più dettagli fornisci sullo schema di output, meglio Claude può gestire la risposta in modo programmatico.

La forma della richiesta è identica all'esempio della Guida rapida: 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 dell'API con chiamata allo strumento

Claude scrive codice che chiama il tuo strumento. L'API si mette in pausa e restituisce:

Output
{
  "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": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Passaggio 3: Fornisci il risultato dello strumento

Includi l'intera cronologia della conversazione più il risultato del tuo strumento:

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}, ...]',
                }
            ],
        },
    ],
    tools=[...],
)

print(response)

Passaggio 4: Chiamata successiva allo strumento o completamento

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

Passaggio 5: Risposta finale

Una volta completata l'esecuzione del codice, Claude fornisce la risposta finale:

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

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

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

Selezione condizionale 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:]:  # 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

ErroreDescrizioneSoluzione
invalid_tool_inputL'input dello strumento non corrisponde allo schemaValida l'input_schema del tuo strumento
invalid_request_error (su tool_choice)tool_choice nomina uno strumento il cui allowed_callers non include "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 durante la chiamata allo strumento

Se il tuo strumento impiega troppo tempo a rispondere, l'esecuzione del codice riceve un TimeoutError. Claude vede questo in stderr e tipicamente 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à con altre 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

Restrizioni sugli strumenti

I seguenti strumenti non possono essere chiamati programmaticamente:

  • Strumenti forniti da un connettore MCP

Restrizioni sulla formattazione dei messaggi

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

Risposte con solo risultati degli strumenti: 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 testuale, 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 testuale dopo i risultati degli strumenti.

Limiti di velocità

Le chiamate programmatiche agli strumenti sono soggette agli stessi limiti di velocità 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 implementi strumenti definiti dall'utente che verranno chiamati programmaticamente:

  • 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 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 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 programmaticamente 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 alcun cambiamento nell'accuratezza del compito.
  • Su τ²-bench (domini aereo, retail e telecomunicazioni), 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 beneficiano.
  • 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 in base alla forma del carico di lavoro; consulta 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.



Conteggio dei token per le chiamate programmatiche agli strumenti: i risultati degli strumenti dalle invocazioni programmatiche non contano ai fini dell'utilizzo dei token di input/output. Contano solo il risultato finale dell'esecuzione del codice e la risposta di Claude.

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 e tipi di campo)
  • 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 minimizzare 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 al modello. Se questo scambio conviene dipende dalla forma del carico di lavoro.

Adatta per:

  • 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 adatta per:

  • 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 al 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ò nominare 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

  • 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ù veloce degli strumenti

Risultato dello strumento non analizzato correttamente

  • Assicurati che il tuo strumento restituisca dati stringa che Claude può deserializzare
  • Fornisci documentazione chiara sul 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

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

  • Ragionare naturalmente sulla composizione degli strumenti: Concatenare operazioni e gestire dipendenze con la stessa naturalezza con cui si scrive qualsiasi codice Python
  • Elaborare grandi risultati in modo efficiente: Filtrare output di strumenti di grandi dimensioni, estrarre solo i dati rilevanti o scrivere risultati intermedi su file prima di restituire riepiloghi alla finestra di contesto
  • Ridurre significativamente la latenza: Eliminare l'overhead di ricampionare Claude tra ogni chiamata allo strumento nei flussi di lavoro multi-step

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

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:

  • Semplice da implementare con minima ri-architettura
  • 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 sicurezza codice arbitrario, vuoi una soluzione semplice e l'offerta gestita di Anthropic non soddisfa le tue esigenze.

Esecuzione sandbox auto-gestita

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 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 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 per l'invocazione degli strumenti.

Vantaggi:

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

Considera di utilizzare la soluzione gestita di Anthropic se stai usando l'API di Claude, Claude Platform on AWS o Microsoft Foundry.

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.

Funzionalità correlate


Strumento di esecuzione del codice

Scopri la capacità di esecuzione del codice sottostante che alimenta la chiamata programmatica degli strumenti.


Uso degli strumenti con Claude

Comprendi i fondamenti dell'uso degli strumenti con Claude.

Definire gli strumenti

Guida passo-passo per definire gli strumenti.

Was this page helpful?

  • Compatibilità dei modelli
  • Guida rapida
  • Come funziona la chiamata programmatica degli strumenti
  • Concetti fondamentali
  • Il campo allowed_callers
  • Il campo caller nelle risposte
  • Ciclo di vita del container
  • Esempio di flusso di lavoro
  • Passaggio 1: Richiesta iniziale
  • Passaggio 2: Risposta dell'API con chiamata allo strumento
  • Passaggio 3: Fornisci il risultato dello strumento
  • Passaggio 4: Chiamata successiva allo strumento o completamento
  • Passaggio 5: Risposta finale
  • Pattern avanzati
  • Elaborazione batch con cicli
  • Terminazione anticipata
  • Selezione condizionale degli strumenti
  • Filtraggio dei dati
  • Formato della risposta
  • Chiamata programmatica allo strumento
  • Gestione del risultato dello strumento
  • Completamento dell'esecuzione del codice
  • Gestione degli errori
  • Errori comuni
  • Scadenza del container durante la chiamata allo strumento
  • Errori di esecuzione dello strumento
  • Vincoli e limitazioni
  • Incompatibilità con altre funzionalità
  • Restrizioni sugli strumenti
  • Restrizioni sulla formattazione dei messaggi
  • Limiti di velocità
  • Valida i risultati degli strumenti prima dell'uso
  • Efficienza dei token
  • Utilizzo e prezzi
  • Best practice
  • Progettazione degli strumenti
  • Quando usare la chiamata programmatica
  • Ottimizzazione delle prestazioni
  • Risoluzione dei problemi
  • Problemi comuni
  • Suggerimenti per il debug
  • Perché la chiamata programmatica degli strumenti funziona
  • Implementazioni alternative
  • Esecuzione diretta lato client
  • Esecuzione sandbox auto-gestita
  • Esecuzione gestita da Anthropic
  • Conservazione dei dati
  • Funzionalità correlate