Comment fonctionne l'utilisation des outils

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

Le contrat d'utilisation des outils

L'utilisation des 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 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 des outils de la même manière qu'ils le feraient avec n'importe quelle autre interface typée : définir le schéma, gérer le callback, retourner 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 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 retournez les résultats. C'est l'essentiel : la grande majorité du trafic d'utilisation des 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 l'action de l'outil), et renvoie le résultat dans un bloc tool_result lors de la prochaine requête. 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 retourné.

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

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

Le modèle d'exécution est identique aux 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 utilisant exactement ces signatures d'outils, il les appelle donc de manière plus fiable et se remet des erreurs plus gracieusement qu'il ne le ferait avec un outil personnalisé qui fait 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 car la boucle côté serveur exécute l'opération et renvoie le résultat au modèle avant que la réponse ne vous parvienne.

La réponse que vous recevez contient des blocs server_tool_use montrant ce qui a été exécuté et ce qui est revenu, mais au moment où vous les voyez, l'exécution est déjà terminée. Le rôle de votre application est d'activer l'outil et de lire la réponse finale, et non de participer à la boucle d'exécution.

La boucle agentique (outils client)

Les outils exécutés côté client (à la fois définis par l'utilisateur et à 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 rapportez, 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 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 originaux, 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 comme suit : tant que stop_reason == "tool_use", exécutez les outils et continuez la conversation. La boucle se termine sur tout autre motif 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, la gestion des appels d'outils parallèles et le formatage des résultats, consultez Gérer les appels d'outils.

La boucle côté serveur

Les outils exécutés côté serveur font tourner leur propre boucle dans 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 des recherches, lit les résultats, décide d'effectuer une nouvelle recherche et itère jusqu'à ce qu'il ait ce dont il a besoin, tout cela sans que votre application ne participe.

Cette boucle interne a une limite d'itération. Si le modèle itère encore 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 continuer là où il s'est arrêté. Consultez Outils serveur pour le modèle de continuation.

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

L'utilisation des 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 secondaires. 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 fraîches ou externes. Les prix actuels, la météo du jour, le contenu d'une base de données. Tout ce qui est en dehors des données d'entraînement ou 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 l'information, un schéma d'outil impose la forme.
• Appel vers des systèmes existants. Bases de données, API internes, systèmes de fichiers. L'utilisation des outils est le pont entre les requêtes en langage naturel et les systèmes qui les satisfont.

Le signe que vous devriez utiliser des outils : si vous écrivez une regex 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 des outils ne convient pas lorsque :

• Le modèle peut répondre à partir de son entraînement seul. La résumé, la traduction et les questions de culture générale n'ont pas besoin d'un aller-retour d'outil.
• L'interaction est une question-réponse unique sans effets secondaires. S'il n'y a rien à exécuter, il n'y a rien pour un outil à faire.
• 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

Prochaines étapes