Tool Runner (SDK)

Il tool runner gestisce il ciclo agentico, il wrapping degli errori e la sicurezza dei tipi al posto tuo. Quando hai bisogno di approvazione human-in-the-loop, logging personalizzato o esecuzione condizionale, usa invece il ciclo manuale.

Invece di gestire manualmente le chiamate agli strumenti, i risultati degli strumenti e la gestione della conversazione, il tool runner automaticamente:

• Esegue gli strumenti quando Claude li chiama
• Gestisce il ciclo richiesta/risposta
• Gestisce lo stato della conversazione
• Fornisce sicurezza dei tipi e validazione



Utilizzo di base

Definisci gli strumenti usando gli helper dell'SDK, quindi usa il tool runner per eseguirli.

A seconda della firma dello strumento nell'SDK, uno strumento restituisce il suo risultato come stringa o come blocchi di contenuto (blocchi di testo, immagine o documento), quindi uno strumento può restituire risultati multimodali. Una stringa restituita diventa un singolo blocco di contenuto di testo. Per restituire dati strutturati, come un oggetto JSON o un numero, codificali prima come stringa.



Iterare sul tool runner

Il tool runner è un iterabile che produce messaggi da Claude. A ogni iterazione, il runner verifica se Claude ha richiesto l'uso di uno strumento. In tal caso, esegue lo strumento e invia automaticamente il risultato a Claude, quindi produce il messaggio successivo da Claude per continuare il tuo ciclo.

Puoi terminare il ciclo a qualsiasi iterazione con un'istruzione break. Il runner continua a ciclare finché Claude non restituisce un messaggio senza uso di strumenti, o finché non raggiunge max_iterations se lo hai impostato.

Se non hai bisogno dei messaggi intermedi, puoi ottenere direttamente il messaggio finale:



Utilizzo avanzato

All'interno del ciclo, puoi leggere ogni messaggio di risposta e modificare lo stato del runner prima della successiva chiamata API. Ogni iterazione segue questo ciclo di vita:

1. Il runner invia una richiesta alla Messages API con il suo stato corrente.
2. Il runner produce il messaggio di risposta al corpo del tuo ciclo.
3. Il corpo del tuo ciclo viene eseguito. Puoi leggere il messaggio e opzionalmente modificare lo stato del runner.
4. Quando il corpo del tuo ciclo ritorna, il runner verifica se hai modificato la sua cronologia dei messaggi.
   • Se non hai modificato la cronologia dei messaggi: Il runner aggiunge il messaggio dell'assistente al suo stato. Se il messaggio contiene chiamate a strumenti, il runner le esegue e aggiunge i risultati. Se non ci sono chiamate a strumenti, il ciclo termina.
   • Se hai modificato la cronologia dei messaggi: Il runner salta la sua aggiunta automatica e usa il tuo stato invariato. Vedi Prendere il controllo della cronologia dei messaggi.



Prendere il controllo della cronologia dei messaggi

Per impostazione predefinita, il runner gestisce lo stato della conversazione al posto tuo: dopo ogni turno, aggiunge il messaggio dell'assistente e gli eventuali risultati degli strumenti alla propria cronologia dei messaggi. Prendi il controllo della cronologia dei messaggi quando vuoi riprovare un turno (scartare la risposta e reinviare), iniettare un messaggio di follow-up o costruire tu stesso il risultato dello strumento.

Prendi il controllo modificando i messaggi del runner dall'interno del corpo del ciclo. Il metodo esatto dipende dall'SDK. Vedi le schede per linguaggio che seguono.

Quando prendi il controllo per un'iterazione, il runner non aggiunge il messaggio dell'assistente o i risultati degli strumenti di quel turno. Diventi responsabile di mantenere valida la conversazione: aggiungi tu stesso il messaggio dell'assistente e un risultato dello strumento (se vuoi che il turno conti), modifica lo stato in modo condizionale così che il ciclo possa comunque terminare quando non ci sono chiamate a strumenti, e passa max_iterations per limitare il ciclo. Tutti e sette gli SDK supportano max_iterations.



Gestione automatica del contesto

Per attività agentiche di lunga durata, i tool runner Python, TypeScript e Ruby supportano la compaction (compattazione) automatica, che genera riepiloghi quando l'utilizzo dei token supera una soglia, così la conversazione può continuare oltre i limiti della "context window" (finestra di contesto). Tutti e tre gli SDK hanno deprecato questa opzione lato client a favore del context editing lato server, disponibile in ogni SDK. I tool runner Go, Java, C# e PHP non includono la compaction lato client.



Debug dell'esecuzione degli strumenti

Quando uno strumento lancia un'eccezione, il tool runner la cattura e restituisce l'errore a Claude come risultato dello strumento con is_error: true. Il risultato dello strumento contiene il messaggio dell'eccezione (in Python, il suo tipo e messaggio), non lo stack trace completo.

Ciò che l'SDK registra nei log è specifico per linguaggio. L'SDK Python registra l'eccezione completa, incluso il suo stack trace, attraverso il modulo standard logging ogni volta che uno strumento solleva un'eccezione non gestita. Gli SDK Python, TypeScript e Java leggono la variabile d'ambiente ANTHROPIC_LOG per attivare il logging dell'SDK, che include i dettagli di richiesta e risposta:

# Registra a livello info
export ANTHROPIC_LOG=info

# Registra a livello debug per un output più dettagliato
export ANTHROPIC_LOG=debug

Gli SDK Go, Ruby, C# e PHP non leggono ANTHROPIC_LOG. Al di fuori di Python, nessun SDK registra uno strumento fallito: per vedere perché uno strumento è fallito, cattura e registra l'eccezione all'interno della funzione dello strumento prima di restituirla o rilanciarla.



Intercettare gli errori degli strumenti

Per impostazione predefinita, gli errori degli strumenti vengono passati a Claude, che può quindi rispondere in modo appropriato. Tuttavia, potresti voler rilevare gli errori e gestirli diversamente, ad esempio per interrompere l'esecuzione in anticipo o implementare una gestione degli errori personalizzata.

Negli SDK Python e TypeScript, usa il metodo di risposta dello strumento (generate_tool_call_response() in Python, generateToolResponse() in TypeScript) per intercettare i risultati degli strumenti e verificare la presenza di errori prima che vengano inviati a Claude. Gli altri SDK non espongono questo hook. Le loro schede descrivono l'alternativa più vicina:



Modificare i risultati degli strumenti

Puoi modificare i risultati degli strumenti prima che vengano inviati a Claude. Questo è utile per aggiungere metadati come cache_control per abilitare la cache dei prompt sui risultati degli strumenti, o per trasformare l'output dello strumento.

Negli SDK Python e TypeScript, usa il metodo di risposta dello strumento per ottenere il risultato dello strumento, quindi modificalo prima che il runner proceda. Se devi aggiungere esplicitamente il risultato modificato o mutarlo sul posto dipende dall'SDK. Vedi i commenti nel codice in ogni scheda.



Streaming

Abilita lo streaming per elaborare la risposta di ogni turno in modo incrementale. Ogni iterazione produce un oggetto stream che puoi iterare per ottenere gli eventi.



Passaggi successivi