Tool Runner (SDK)

Tool Runner gestisce il ciclo agentico, il wrapping degli errori e la type safety in modo che tu non debba farlo. Usa il ciclo manuale solo quando hai bisogno dell'approvazione umana nel ciclo, del logging personalizzato o dell'esecuzione condizionale. Disponibile negli SDK Python, TypeScript e Ruby.

Il tool runner fornisce una soluzione pronta all'uso per eseguire strumenti con Claude. 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 di richiesta/risposta
Gestisce lo stato della conversazione
Fornisce type safety e validazione

Usa il tool runner per la maggior parte delle implementazioni di tool use.

Il tool runner è attualmente in beta ed è disponibile negli SDK Python, TypeScript e Ruby.

Gestione automatica del contesto con compattazione

Il tool runner supporta la compattazione automatica, che genera riassunti quando l'utilizzo dei token supera una soglia. Questo consente ai compiti agentici di lunga durata di continuare oltre i limiti della finestra di contesto.

Utilizzo di base

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

La funzione dello strumento deve restituire un blocco di contenuto o un array di blocchi di contenuto, inclusi testo, immagini o blocchi di documenti. Questo consente agli strumenti di restituire risposte ricche e multimodali. Le stringhe restituite verranno convertite in un blocco di contenuto di testo. Se vuoi restituire un oggetto JSON strutturato a Claude, codificalo in una stringa JSON prima di restituirlo. I numeri, i booleani o altri primitivi non-stringa devono essere convertiti anche in stringhe.

Iterazione sul tool runner

Il tool runner è un iterabile che restituisce messaggi da Claude. Questo è spesso indicato come un "ciclo di chiamate agli strumenti". Ad ogni iterazione, il runner controlla se Claude ha richiesto un tool use. Se è così, chiama lo strumento e invia il risultato a Claude automaticamente, quindi restituisce il messaggio successivo da Claude per continuare il tuo ciclo.

Puoi terminare il ciclo in qualsiasi iterazione con un'istruzione break. Il runner continuerà il ciclo fino a quando Claude non restituisce un messaggio senza un tool use.

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

Utilizzo avanzato

All'interno del ciclo, puoi personalizzare completamente la prossima richiesta del tool runner all'API Messages. Il runner aggiunge automaticamente i risultati degli strumenti alla cronologia dei messaggi, quindi non devi gestirli manualmente. Puoi facoltativamente ispezionare il risultato dello strumento per il logging o il debugging e modificare i parametri della richiesta prima della prossima chiamata API.

Debug dell'esecuzione degli strumenti

Quando uno strumento genera un'eccezione, il tool runner la cattura e restituisce l'errore a Claude come risultato dello strumento con is_error: true. Per impostazione predefinita, viene incluso solo il messaggio di eccezione, non la traccia dello stack completa.

Per visualizzare le tracce dello stack complete e le informazioni di debug, imposta la variabile di ambiente ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Quando abilitato, l'SDK registra i dettagli completi dell'eccezione (usando il modulo logging di Python, la console in TypeScript o il logger di Ruby), inclusa la traccia dello stack completa quando uno strumento fallisce.

Intercettazione degli 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 la gestione degli errori personalizzata.

Usa il metodo di risposta dello strumento per intercettare i risultati degli strumenti e verificare la presenza di errori prima che vengano inviati a Claude:

Modifica dei risultati degli strumenti

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

Usa il metodo di risposta dello strumento per ottenere il risultato dello strumento, quindi modificalo prima che il runner proceda. Se esplicitamente aggiungi il risultato modificato o lo muti sul posto dipende dall'SDK; vedi i commenti del codice in ogni scheda.

Aggiungere cache_control ai risultati degli strumenti è particolarmente utile quando gli strumenti restituiscono grandi quantità di dati (come i risultati della ricerca di documenti) che desideri memorizzare nella cache per le successive chiamate API. Vedi Prompt caching per ulteriori dettagli sulle strategie di caching.

Streaming

Abilita lo streaming per ricevere gli eventi man mano che arrivano. Ogni iterazione restituisce un oggetto stream che puoi iterare per gli eventi.

Passaggi successivi

Per il controllo manuale sul ciclo di chiamate agli strumenti, vedi Gestire le chiamate agli strumenti.
Per eseguire più strumenti contemporaneamente, vedi Utilizzo parallelo degli strumenti.
Per il flusso di lavoro completo di tool use, vedi Definire gli strumenti.