Tool Runner (SDK)

Le « tool runner » (exécuteur d'outils) gère la boucle agentique, l'encapsulation des erreurs et la sécurité des types afin que vous n'ayez pas à le faire. Lorsque vous avez besoin d'une approbation humaine dans la boucle, d'une journalisation personnalisée ou d'une exécution conditionnelle, utilisez plutôt la boucle manuelle.

Au lieu de gérer manuellement les appels d'outils, les résultats d'outils et la gestion de la conversation, le tool runner effectue automatiquement les opérations suivantes :

• 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



Utilisation de base

Définissez les outils à l'aide des helpers du SDK, puis utilisez le tool runner pour les exécuter.

Selon la signature d'outil du SDK, un outil renvoie son résultat sous forme de chaîne de caractères ou de blocs de contenu (blocs de texte, d'image ou de document), de sorte qu'un outil peut renvoyer des résultats multimodaux. Une chaîne renvoyée devient un bloc de contenu texte unique. Pour renvoyer des données structurées, telles qu'un objet JSON ou un nombre, encodez-les d'abord sous forme de chaîne.



Itération sur le tool runner

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

Vous pouvez mettre fin à la boucle à n'importe quelle itération avec une instruction break. Le runner boucle jusqu'à ce que Claude renvoie un message sans utilisation d'outils, ou jusqu'à ce qu'il atteigne max_iterations si vous l'avez défini.

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



Utilisation avancée

Dans la boucle, vous pouvez lire chaque message de réponse et modifier l'état du runner avant le prochain appel API. Chaque itération suit ce cycle de vie :

1. Le runner envoie une requête à l'API Messages avec son état actuel.
2. Le runner produit le message de réponse dans le corps de votre boucle.
3. Le corps de votre boucle s'exécute. Vous pouvez lire le message et éventuellement modifier l'état du runner.
4. Lorsque le corps de votre boucle retourne, le runner vérifie si vous avez modifié son historique de messages.
   • Si vous n'avez pas modifié l'historique des messages : Le runner ajoute le message de l'assistant à son état. Si le message contient des appels d'outils, le runner les exécute et ajoute les résultats. S'il n'y a pas d'appels d'outils, la boucle se termine.
   • Si vous avez modifié l'historique des messages : Le runner ignore son ajout automatique et utilise votre état tel quel. Voir Prendre le contrôle de l'historique des messages.



Prendre le contrôle de l'historique des messages

Par défaut, le runner gère l'état de la conversation pour vous : après chaque tour, il ajoute le message de l'assistant et tous les résultats d'outils à son propre historique de messages. Vous prenez le contrôle de l'historique des messages lorsque vous souhaitez réessayer un tour (ignorer la réponse et renvoyer), injecter un message de suivi ou construire vous-même le résultat de l'outil.

Vous prenez le contrôle en modifiant les messages du runner depuis l'intérieur du corps de la boucle. La méthode exacte dépend du SDK. Consultez les onglets par langage qui suivent.

Lorsque vous prenez le contrôle pour une itération, le runner n'ajoute pas le message de l'assistant ni les résultats d'outils de ce tour. Vous devenez responsable de maintenir la validité de la conversation : ajoutez vous-même le message de l'assistant et un résultat d'outil (si vous voulez que le tour compte), modifiez l'état de manière conditionnelle afin que la boucle puisse toujours se terminer lorsqu'il n'y a pas d'appels d'outils, et passez max_iterations pour borner la boucle. Les sept SDK prennent en charge max_iterations.



Gestion automatique du contexte

Pour les tâches agentiques de longue durée, les tool runners Python, TypeScript et Ruby prennent en charge la compaction automatique, qui génère des résumés lorsque l'utilisation de tokens dépasse un seuil afin que la conversation puisse continuer au-delà des limites de la fenêtre de contexte. Les trois SDK ont déprécié cette option côté client en faveur de l'édition de contexte côté serveur, qui est disponible dans tous les SDK. Les tool runners Go, Java, C# et PHP n'incluent pas de compaction côté client.



Débogage de l'exécution des outils

Lorsqu'un outil lève une exception, le tool runner l'intercepte et renvoie l'erreur à Claude sous forme de résultat d'outil avec is_error: true. Le résultat de l'outil contient le message de l'exception (en Python, son type et son message), et non la trace de pile complète.

Ce que le SDK journalise dépend du langage. Le SDK Python journalise l'exception complète, y compris sa trace de pile, via le module standard logging chaque fois qu'un outil lève une exception non gérée. Les SDK Python, TypeScript et Java lisent la variable d'environnement ANTHROPIC_LOG pour activer la journalisation du SDK, qui inclut les détails des requêtes et des réponses :

# Journaliser au niveau info
export ANTHROPIC_LOG=info

# Journaliser au niveau debug pour une sortie plus détaillée
export ANTHROPIC_LOG=debug

Les SDK Go, Ruby, C# et PHP ne lisent pas ANTHROPIC_LOG. En dehors de Python, aucun SDK ne journalise un outil en échec : pour voir pourquoi un outil a échoué, interceptez et journalisez l'exception à l'intérieur de la fonction de l'outil avant de la renvoyer ou de la relancer.



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 pourriez vouloir détecter les erreurs et les gérer différemment, par exemple pour arrêter l'exécution prématurément ou implémenter une gestion d'erreurs personnalisée.

Dans les SDK Python et TypeScript, utilisez la méthode de réponse d'outil (generate_tool_call_response() en Python, generateToolResponse() en TypeScript) pour intercepter les résultats d'outils et vérifier les erreurs avant qu'ils ne soient envoyés à Claude. Les autres SDK n'exposent pas ce hook. Leurs onglets décrivent l'alternative la plus proche :



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 telles que cache_control afin d'activer la mise en cache des prompts sur les résultats d'outils, ou pour transformer la sortie de l'outil.

Dans les SDK Python et TypeScript, 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. Le fait d'ajouter explicitement le résultat modifié ou de le muter en place dépend du SDK. Consultez les commentaires de code dans chaque onglet.



Streaming

Activez le streaming pour traiter la réponse de chaque tour de manière incrémentielle. Chaque itération produit un objet stream sur lequel vous pouvez itérer pour obtenir les événements.



Étapes suivantes