Tool Runner (SDK)

Tool Runner gère la boucle agentique, l'enveloppe d'erreurs et la sécurité des types pour que vous n'ayez pas à le faire. Utilisez la boucle manuelle uniquement lorsque vous avez besoin d'une approbation humaine dans la boucle, d'une journalisation personnalisée ou d'une exécution conditionnelle. Disponible dans les SDK Python, TypeScript et Ruby.

Le tool runner fournit une solution prête à l'emploi pour exécuter des outils avec Claude. Au lieu de gérer manuellement les appels d'outils, les résultats d'outils et la gestion des conversations, le tool runner effectue automatiquement :

• Exécute les outils lorsque Claude les appelle
• Gère le cycle requête/réponse
• Gère l'état de la conversation
• Fournit la sécurité des types et la validation

Utilisez le tool runner pour la plupart des implémentations d'utilisation d'outils.

Utilisation de base

Définissez les outils en utilisant les assistants du SDK, puis utilisez le tool runner pour les exécuter.

La fonction d'outil doit retourner un bloc de contenu ou un tableau de blocs de contenu, incluant du texte, des images ou des blocs de documents. Cela permet aux outils de retourner des réponses riches et multimodales. Les chaînes retournées seront converties en bloc de contenu texte. Si vous voulez retourner un objet JSON structuré à Claude, encodez-le en chaîne JSON avant de le retourner. Les nombres, booléens ou autres primitives non-chaîne doivent également être convertis en chaînes.

Itération sur le tool runner

Le tool runner est un itérable qui produit des messages de Claude. Ceci est souvent appelé une « boucle d'appel d'outil ». À chaque itération, le runner vérifie si Claude a demandé une utilisation d'outil. Si c'est le cas, il appelle l'outil et envoie le résultat à Claude automatiquement, puis produit le message suivant de Claude pour continuer votre boucle.

Vous pouvez terminer la boucle à n'importe quelle itération avec une instruction break. Le runner boucle jusqu'à ce que Claude retourne un message sans utilisation d'outil.

Si vous n'avez pas besoin de messages intermédiaires, vous pouvez obtenir le message final directement :

Utilisation avancée

Dans la boucle, vous pouvez personnaliser complètement la prochaine requête du tool runner à l'API Messages. Le runner ajoute automatiquement les résultats des outils à l'historique des messages, vous n'avez donc pas besoin de les gérer manuellement. Vous pouvez optionnellement inspecter le résultat de l'outil pour la journalisation ou le débogage, et modifier les paramètres de la requête avant le prochain appel API.

Débogage de l'exécution des outils

Lorsqu'un outil lève une exception, le tool runner la capture et retourne l'erreur à Claude en tant que résultat d'outil avec is_error: true. Par défaut, seul le message d'exception est inclus, pas la trace de pile complète.

Pour afficher les traces de pile complètes et les informations de débogage, définissez la variable d'environnement 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

Lorsqu'elle est activée, le SDK enregistre les détails complets des exceptions (en utilisant le module logging de Python, la console en TypeScript ou le logger de Ruby), y compris la trace de pile complète lorsqu'un outil échoue.

Interception des erreurs d'outils

Par défaut, les erreurs d'outils sont renvoyées à Claude, qui peut alors répondre de manière appropriée. Cependant, vous pouvez vouloir détecter les erreurs et les gérer différemment, par exemple pour arrêter l'exécution plus tôt ou implémenter une gestion d'erreurs personnalisée.

Utilisez la méthode de réponse d'outil pour intercepter les résultats d'outils et vérifier les erreurs avant qu'elles ne soient envoyées à Claude :

Modification des résultats d'outils

Vous pouvez modifier les résultats d'outils avant qu'ils ne soient renvoyés à Claude. Ceci est utile pour ajouter des métadonnées comme cache_control pour activer la mise en cache des invites sur les résultats d'outils, ou pour transformer la sortie de l'outil.

Utilisez la méthode de réponse d'outil pour obtenir le résultat de l'outil, puis modifiez-le avant que le runner ne continue. Que vous ajoutiez explicitement le résultat modifié ou que vous le motiez sur place dépend du SDK ; voir les commentaires de code dans chaque onglet.

Streaming

Activez le streaming pour recevoir les événements à mesure qu'ils arrivent. Chaque itération produit un objet de flux que vous pouvez itérer pour les événements.

Étapes suivantes

• Pour un contrôle manuel sur la boucle d'appel d'outil, voir Gérer les appels d'outils.
• Pour exécuter plusieurs outils simultanément, voir Utilisation parallèle d'outils.
• Pour le flux de travail complet d'utilisation d'outils, voir Définir les outils.