Comment fonctionne l'utilisation d'outils

Cette page explique les concepts derrière l'utilisation d'outils : où les outils s'exécutent, comment fonctionne la boucle agentive 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 de lui-même. Il émet une demande 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 plus 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, 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 entre dans 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'événement principal : la grande majorité du trafic d'utilisation d'outils provient d'outils définis par l'utilisateur appelant une logique spécifique à l'application.

Quand 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, tout ce que l'outil fait), et envoie la sortie dans un bloc tool_result dans la demande 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 retourné.

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

Pour une poignée d'opérations courantes (exécuter des commandes shell, éditer des fichiers, contrôler un navigateur, gérer la mémoire du bloc-notes), Anthropic publie le schéma d'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 de schéma Anthropic au lieu de définir votre propre équivalent est que ces schémas sont entraînés. Claude a été optimisé sur des milliers de trajectoires réussies qui utilisent ces signatures d'outil exactes, donc il les appelle plus fiablement 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 demande et le serveur gère tout le reste. Vous ne construisez jamais un bloc tool_result pour ces outils car 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.

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

La boucle agentive (outils clients)

Les outils exécutés côté client (à la fois définis par l'utilisateur et de 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 signalez, le modèle continue.

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

1. Envoyez une demande 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 en tant que blocs tool_result.
4. Envoyez une nouvelle demande 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 tandis que stop_reason est "tool_use".

En pratique, cela se lit comme : tandis 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écaniques de construction de demandes, la gestion des appels d'outils parallèles et le formatage des résultats, voir Gérer les appels d'outils.

La boucle côté serveur

Les outils exécutés côté serveur exécutent leur propre boucle à l'intérieur de l'infrastructure d'Anthropic. Une seule demande de votre application pourrait 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écide de rechercher à nouveau, 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 toujours quand 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 où il s'était arrêté. Voir Outils serveur pour le modèle de continuation.

Quand utiliser les outils (et quand ne pas les utiliser)

L'utilisation d'outils convient quand 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 exécuter.
• Données fraîches ou externes. Prix actuels, météo d'aujourd'hui, contenu d'une base de données. Tout ce qui se trouve en dehors des données d'entraînement ou spécifique à votre système a besoin d'un outil pour le récupérer.
• Sorties structurées et de forme garantie. Quand vous avez besoin d'un objet JSON avec des champs spécifiques plutôt que de la prose qui contient simplement l'information, un schéma d'outil impose la forme.
• Appel dans les systèmes existants. Bases de données, API internes, systèmes de fichiers. L'utilisation d'outils est le pont entre les demandes en langage naturel et les systèmes qui les satisfont.

L'indicateur 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 d'outils ne convient pas quand :

• Le modèle peut répondre à partir de l'entraînement seul. La résumé, la traduction et les questions de connaissances générales n'ont pas besoin d'un aller-retour d'outil.
• L'interaction est une Q&A ponctuelle sans effets secondaires. S'il n'y a rien à exécuter, il n'y a rien pour un outil à faire.
• La latence d'appel d'outil dominerait une réponse triviale. Chaque appel d'outil est au moins un aller-retour supplémentaire ; pour les tâches légères, la surcharge peut dépasser le travail.

Choisir entre les approches

Prochaines étapes