MessagesOutils

Fonctionnement de l'utilisation d'outils

Copy page



Comprenez la boucle d'utilisation d'outils, où les outils s'exécutent et quand utiliser des outils plutôt que de la prose.

Cette page explique les concepts qui sous-tendent le « tool use » (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 Créer un agent utilisant des outils ou le guide Définir des outils.

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 leurs sorties ; Claude détermine 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 revient 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 classique des API peuvent intégrer l'utilisation d'outils de la même manière qu'ils le feraient pour toute 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 appeler 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 de trois catégories, et la 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 le plus courant : la grande majorité du trafic d'utilisation d'outils provient d'outils définis par l'utilisateur qui appellent une logique propre à l'application.

Lorsque Claude appelle 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, quoi que fasse 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 (gérer une mémoire de travail, exécuter des commandes shell, modifier des fichiers, contrôler un bureau ou 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, computer et browser.

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 exactement ces signatures d'outils, 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 indiquant ce qui a été exécuté et ce qui en est revenu. 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 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) exigent 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 conditionnée par stop_reason :

1. Envoyez une requête avec votre tableau tools et le message de l'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 vaut "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 recherche, lit les résultats, détermine s'il doit rechercher à nouveau et itère jusqu'à obtenir 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 encore 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 en pause signifie que le travail n'est pas terminé ; renvoyez la conversation (y compris la réponse en pause) pour permettre au modèle de reprendre là où il s'est 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. Les prix actuels, la météo du jour, le contenu d'une base de données. Tout ce qui se trouve en dehors des données d'entraînement ou qui est propre à 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'une prose qui contient par hasard l'information, un schéma d'outil impose la forme.
• Appels vers 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.

Un signe clair 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 retrouver 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 seul entraînement. 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 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

Étapes suivantes