Fonctionnement de l'utilisation d'outils

Cette page explique les concepts qui sous-tendent l'utilisation d'outils : où les outils s'exécutent, comment fonctionne la boucle agentique et quand l'utilisation d'outils est la bonne approche. Pour des conseils pratiques, commencez par le tutoriel ou le guide d'implémentation.



Le contrat d'utilisation d'outils

L'utilisation d'outils est un contrat entre votre application et le modèle. Vous spécifiez quelles opérations sont disponibles et quelle forme prennent leurs entrées et sorties ; Claude décide quand et comment les appeler. Le modèle n'exécute jamais rien par lui-même. Il émet une requête structurée, votre code (ou les serveurs d'Anthropic) exécute l'opération, et le résultat est réinjecté dans la conversation.

Ce contrat fait que le modèle se comporte moins comme un générateur de texte et davantage comme une fonction que vous appelez. Les ingénieurs ayant une expérience des API classiques peuvent intégrer l'utilisation d'outils de la même manière que n'importe quelle autre interface typée : définir le schéma, gérer le rappel, renvoyer un résultat. La différence est que l'appelant de l'autre côté est un modèle de langage qui choisit quelle fonction invoquer en fonction de la conversation.



Où les outils s'exécutent

L'axe principal selon lequel les outils diffèrent est l'endroit où le code s'exécute. Chaque outil appartient à l'une des trois catégories, et cette catégorie détermine ce dont votre application est responsable.



Outils définis par l'utilisateur (exécutés côté client)

Vous écrivez le schéma, vous exécutez le code, vous renvoyez les résultats. C'est le cas principal : la grande majorité du trafic d'utilisation d'outils concerne des outils définis par l'utilisateur qui appellent une logique spécifique à l'application.

Lorsque Claude décide d'utiliser l'un de vos outils, la réponse de l'API contient un bloc tool_use avec le nom de l'outil et un objet JSON d'arguments. Votre application extrait ces arguments, exécute l'opération (une requête de base de données, un appel HTTP, une écriture de fichier, quelle que soit la fonction de l'outil) et renvoie la sortie dans un bloc tool_result lors de la requête suivante. Claude ne voit jamais votre implémentation ; il ne voit que le schéma que vous avez fourni et le résultat que vous avez renvoyé.



Outils à schéma Anthropic (exécutés côté client)

Pour une poignée d'opérations courantes (gestion de la mémoire de travail, exécution de commandes shell, édition de fichiers, contrôle d'un navigateur), Anthropic publie le schéma de l'outil et votre application gère l'exécution. Les outils de cette catégorie sont memory, bash, text_editor et computer.

Le modèle d'exécution est identique à celui des outils définis par l'utilisateur : la réponse contient un bloc tool_use, votre code exécute l'opération et vous renvoyez un tool_result. La raison d'utiliser un outil à schéma Anthropic plutôt que de définir votre propre équivalent est que ces schémas sont intégrés à l'entraînement. Claude a été optimisé sur des milliers de trajectoires réussies qui utilisent ces signatures d'outils exactes, de sorte qu'il les appelle de manière plus fiable et se remet des erreurs plus élégamment qu'il ne le ferait avec un outil personnalisé faisant la même chose. Le schéma est l'interface que le modèle attend déjà.



Outils exécutés côté serveur

Pour web_search, web_fetch, code_execution et tool_search, Anthropic exécute le code. Vous activez l'outil dans votre requête et le serveur gère tout le reste. Vous ne construisez jamais de bloc tool_result pour ces outils. Lorsqu'un tour n'appelle que des outils serveur, la boucle côté serveur exécute l'opération et renvoie la sortie au modèle avant que la réponse ne vous parvienne, sauf si la boucle s'arrête avant d'avoir terminé, le plus souvent parce qu'elle se met en pause.

La réponse que vous recevez contient des blocs server_tool_use montrant ce qui a été exécuté et ce qui a été renvoyé. Dans le cas courant, l'exécution est déjà terminée au moment où vous les voyez, et le rôle de votre application est d'activer l'outil et de lire la réponse finale plutôt que de participer à la boucle d'exécution ; les principales exceptions sont une boucle mise en pause (pause_turn) et un tour qui appelle également un outil client.



La boucle agentique (outils client)

Les outils exécutés côté client (qu'ils soient définis par l'utilisateur ou à schéma Anthropic) nécessitent que votre application pilote une boucle. Le modèle ne peut pas exécuter votre code, donc chaque appel d'outil est un aller-retour : le modèle demande, vous exécutez, vous rendez compte, le modèle continue.

La forme canonique est une boucle while basée sur stop_reason :

1. Envoyez une requête avec votre tableau tools et le message utilisateur.
2. Claude répond avec stop_reason: "tool_use" et un ou plusieurs blocs tool_use.
3. Exécutez chaque outil. Formatez les sorties sous forme de blocs tool_result.
4. Envoyez une nouvelle requête contenant les messages d'origine, la réponse de l'assistant et un message utilisateur avec les blocs tool_result.
5. Répétez à partir de l'étape 2 tant que stop_reason est "tool_use".

En pratique, cela se lit ainsi : tant que stop_reason == "tool_use", exécutez les outils et poursuivez la conversation. La boucle se termine sur toute autre raison d'arrêt ("end_turn", "max_tokens", "stop_sequence" ou "refusal"), ce qui signifie que Claude a soit produit une réponse finale, soit s'est arrêté pour une autre raison que votre application doit gérer.

Pour les mécanismes de construction des requêtes, de gestion des appels d'outils parallèles et de formatage des résultats, consultez Gérer les appels d'outils.



La boucle côté serveur

Les outils exécutés côté serveur exécutent leur propre boucle au sein de l'infrastructure d'Anthropic. Une seule requête de votre application peut déclencher plusieurs recherches web ou exécutions de code avant qu'une réponse ne revienne. Le modèle effectue une recherche, lit les résultats, décide de rechercher à nouveau et itère jusqu'à ce qu'il ait ce dont il a besoin, le tout sans que votre application ne participe.

Cette boucle interne a une limite d'itérations. Si le modèle est toujours en train d'itérer lorsqu'il atteint le plafond, la réponse revient avec stop_reason: "pause_turn" au lieu de "end_turn". Un tour mis en pause signifie que le travail n'est pas terminé ; renvoyez la conversation (y compris la réponse mise en pause) pour permettre au modèle de reprendre là où il s'était arrêté. Consultez Outils serveur pour le modèle de continuation.

La boucle vous rend également le contrôle avant l'exécution d'un outil serveur si Claude appelle cet outil serveur et un outil client dans le même groupe d'appels d'outils parallèles. La réponse revient alors avec stop_reason: "tool_use" et un bloc server_tool_use qui n'a pas encore de bloc de résultat ; l'API l'exécute après que vous avez renvoyé les résultats de l'outil client. Consultez Raisons d'arrêt et repli pour le contrat exact.



Quand utiliser des outils (et quand ne pas le faire)

L'utilisation d'outils convient lorsque la tâche nécessite quelque chose que le modèle ne peut pas faire à partir du texte seul :

• Actions avec effets de bord. Envoyer un e-mail, écrire un fichier, mettre à jour un enregistrement. Le modèle peut décrire ces actions, mais seul un outil peut les effectuer.
• Données récentes ou externes. Prix actuels, météo du jour, contenu d'une base de données. Tout ce qui se trouve en dehors des données d'entraînement ou qui est spécifique à votre système nécessite un outil pour le récupérer.
• Sorties structurées à forme garantie. Lorsque vous avez besoin d'un objet JSON avec des champs spécifiques plutôt que d'un texte libre qui contient par hasard l'information, un schéma d'outil impose la forme.
• Appels à des systèmes existants. Bases de données, API internes, systèmes de fichiers. L'utilisation d'outils est le pont entre les requêtes en langage naturel et les systèmes qui les satisfont.

Le signe révélateur que vous devriez utiliser des outils : si vous écrivez une expression régulière pour extraire une décision de la sortie du modèle, cette décision aurait dû être un appel d'outil. Analyser du texte libre pour récupérer une intention structurée est un signe que la structure appartient au schéma.

L'utilisation d'outils ne convient pas lorsque :

• Le modèle peut répondre à partir de son entraînement seul. Le résumé, la traduction et les questions de culture générale ne nécessitent pas d'aller-retour d'outil.
• L'interaction est une question-réponse ponctuelle sans effets de bord. S'il n'y a rien à exécuter, il n'y a rien à faire pour un outil.
• La « latency » (latence) des appels d'outils dominerait une réponse triviale. Chaque appel d'outil représente au moins un aller-retour supplémentaire ; pour les tâches légères, la surcharge peut dépasser le travail lui-même.



Choisir entre les approches



Prochaines étapes