Comment implémenter l'utilisation d'outils
Guide complet pour implémenter l’utilisation d’outils avec Claude, incluant la définition d’outils, le contrôle de sortie et la gestion des erreurs.
Choisir un modèle
En général, utilisez Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 ou Claude Opus 3 pour les outils complexes et les requêtes ambiguës ; ils gèrent mieux les outils multiples et cherchent des clarifications quand nécessaire.
Utilisez Claude Haiku 3.5 ou Claude Haiku 3 pour les outils simples, mais notez qu’ils peuvent inférer des paramètres manquants.
Si vous utilisez Claude Sonnet 3.7 avec l’utilisation d’outils et la réflexion étendue, consultez notre guide ici pour plus d’informations.
Spécifier les outils client
Les outils client (définis par Anthropic et définis par l’utilisateur) sont spécifiés dans le paramètre de niveau supérieur tools
de la requête API. Chaque définition d’outil inclut :
Paramètre | Description |
---|---|
name | Le nom de l’outil. Doit correspondre à la regex ^[a-zA-Z0-9_-]{1,64}$ . |
description | Une description détaillée en texte brut de ce que fait l’outil, quand il doit être utilisé et comment il se comporte. |
input_schema | Un objet JSON Schema définissant les paramètres attendus pour l’outil. |
Prompt système d’utilisation d’outils
Lorsque vous appelez l’API Anthropic avec le paramètre tools
, nous construisons un prompt système spécial à partir des définitions d’outils, de la configuration d’outils et de tout prompt système spécifié par l’utilisateur. Le prompt construit est conçu pour instruire le modèle à utiliser le ou les outils spécifiés et fournir le contexte nécessaire pour que l’outil fonctionne correctement :
Meilleures pratiques pour les définitions d’outils
Pour obtenir les meilleures performances de Claude lors de l’utilisation d’outils, suivez ces directives :
- Fournissez des descriptions extrêmement détaillées. C’est de loin le facteur le plus important dans les performances d’outils. Vos descriptions doivent expliquer chaque détail sur l’outil, incluant :
- Ce que fait l’outil
- Quand il doit être utilisé (et quand il ne doit pas l’être)
- Ce que signifie chaque paramètre et comment il affecte le comportement de l’outil
- Toute mise en garde ou limitation importante, comme les informations que l’outil ne retourne pas si le nom de l’outil n’est pas clair. Plus vous pouvez donner de contexte à Claude sur vos outils, mieux il sera à décider quand et comment les utiliser. Visez au moins 3-4 phrases par description d’outil, plus si l’outil est complexe.
- Priorisez les descriptions par rapport aux exemples. Bien que vous puissiez inclure des exemples d’utilisation d’un outil dans sa description ou dans le prompt d’accompagnement, c’est moins important que d’avoir une explication claire et complète du but et des paramètres de l’outil. N’ajoutez des exemples qu’après avoir entièrement développé la description.
La bonne description explique clairement ce que fait l’outil, quand l’utiliser, quelles données il retourne et ce que signifie le paramètre ticker
. La mauvaise description est trop brève et laisse Claude avec de nombreuses questions ouvertes sur le comportement et l’utilisation de l’outil.
Contrôler la sortie de Claude
Forcer l’utilisation d’outils
Dans certains cas, vous pourriez vouloir que Claude utilise un outil spécifique pour répondre à la question de l’utilisateur, même si Claude pense pouvoir fournir une réponse sans utiliser d’outil. Vous pouvez faire cela en spécifiant l’outil dans le champ tool_choice
comme ceci :
Lorsque vous travaillez avec le paramètre tool_choice, nous avons quatre options possibles :
auto
permet à Claude de décider s’il faut appeler les outils fournis ou non. C’est la valeur par défaut quand destools
sont fournis.any
dit à Claude qu’il doit utiliser un des outils fournis, mais ne force pas un outil particulier.tool
nous permet de forcer Claude à toujours utiliser un outil particulier.none
empêche Claude d’utiliser des outils. C’est la valeur par défaut quand aucuntools
n’est fourni.
Lors de l’utilisation du cache de prompt, les changements au paramètre tool_choice
invalideront les blocs de messages mis en cache. Les définitions d’outils et les prompts système restent en cache, mais le contenu des messages doit être retraité.
Ce diagramme illustre comment chaque option fonctionne :
Notez que lorsque vous avez tool_choice
comme any
ou tool
, nous pré-remplirons le message assistant pour forcer l’utilisation d’un outil. Cela signifie que les modèles n’émettront pas de bloc de contenu text
de chaîne de pensée avant les blocs de contenu tool_use
, même si explicitement demandé.
Lors de l’utilisation de la réflexion étendue avec l’utilisation d’outils, tool_choice: {"type": "any"}
et tool_choice: {"type": "tool", "name": "..."}
ne sont pas supportés et résulteront en une erreur. Seuls tool_choice: {"type": "auto"}
(par défaut) et tool_choice: {"type": "none"}
sont compatibles avec la réflexion étendue.
Nos tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez conserver la chaîne de pensée (particulièrement avec Opus) tout en demandant que le modèle utilise un outil spécifique, vous pouvez utiliser {"type": "auto"}
pour tool_choice
(par défaut) et ajouter des instructions explicites dans un message user
. Par exemple : Quel temps fait-il à Londres ? Utilisez l'outil get_weather dans votre réponse.
Sortie JSON
Les outils n’ont pas nécessairement besoin d’être des fonctions client — vous pouvez utiliser des outils chaque fois que vous voulez que le modèle retourne une sortie JSON qui suit un schéma fourni. Par exemple, vous pourriez utiliser un outil record_summary
avec un schéma particulier. Voir Utilisation d’outils avec Claude pour un exemple complet fonctionnel.
Chaîne de pensée
Lors de l’utilisation d’outils, Claude montrera souvent sa “chaîne de pensée”, c’est-à-dire le raisonnement étape par étape qu’il utilise pour décomposer le problème et décider quels outils utiliser. Le modèle Claude Opus 3 fera cela si tool_choice
est défini sur auto
(c’est la valeur par défaut, voir Forcer l’utilisation d’outils), et Sonnet et Haiku peuvent être incités à le faire.
Par exemple, étant donné le prompt “Quel temps fait-il à San Francisco maintenant, et quelle heure est-il là-bas ?”, Claude pourrait répondre avec :
Cette chaîne de pensée donne un aperçu du processus de raisonnement de Claude et peut vous aider à déboguer un comportement inattendu.
Avec le modèle Claude Sonnet 3, la chaîne de pensée est moins commune par défaut, mais vous pouvez inciter Claude à montrer son raisonnement en ajoutant quelque chose comme "Avant de répondre, expliquez votre raisonnement étape par étape dans des balises."
au message utilisateur ou au prompt système.
Il est important de noter que bien que les balises <thinking>
soient une convention commune que Claude utilise pour dénoter sa chaîne de pensée, le format exact (comme le nom de cette balise XML) peut changer avec le temps. Votre code devrait traiter la chaîne de pensée comme tout autre texte généré par l’assistant, et ne pas s’appuyer sur la présence ou le formatage spécifique des balises <thinking>
.
Utilisation d’outils en parallèle
Par défaut, Claude peut utiliser plusieurs outils pour répondre à une requête utilisateur. Vous pouvez désactiver ce comportement en :
- Définissant
disable_parallel_tool_use=true
quand le type tool_choice estauto
, ce qui assure que Claude utilise au plus un outil - Définissant
disable_parallel_tool_use=true
quand le type tool_choice estany
outool
, ce qui assure que Claude utilise exactement un outil
Maximiser l’utilisation d’outils en parallèle
Bien que les modèles Claude 4 aient d’excellentes capacités d’utilisation d’outils en parallèle par défaut, vous pouvez augmenter la probabilité d’exécution d’outils en parallèle sur tous les modèles avec un prompting ciblé :
Utilisation d’outils en parallèle avec Claude Sonnet 3.7
Claude Sonnet 3.7 peut être moins susceptible de faire des appels d’outils en parallèle dans une réponse, même quand vous n’avez pas défini disable_parallel_tool_use
. Pour contourner cela, nous recommandons d’activer l’utilisation d’outils efficace en tokens, qui aide à encourager Claude à utiliser des outils en parallèle. Cette fonctionnalité bêta réduit aussi la latence et économise en moyenne 14% en tokens de sortie.
Si vous préférez ne pas opter pour la bêta d’utilisation d’outils efficace en tokens, vous pouvez aussi introduire un “outil batch” qui peut agir comme un méta-outil pour envelopper les invocations à d’autres outils simultanément. Nous trouvons que si cet outil est présent, le modèle l’utilisera pour appeler simultanément plusieurs outils en parallèle pour vous.
Voir cet exemple dans notre cookbook pour savoir comment utiliser cette solution de contournement.
Gérer les blocs de contenu d’utilisation d’outils et de résultats d’outils
La réponse de Claude diffère selon qu’il utilise un outil client ou serveur.
Gérer les résultats d’outils client
La réponse aura un stop_reason
de tool_use
et un ou plusieurs blocs de contenu tool_use
qui incluent :
id
: Un identifiant unique pour ce bloc d’utilisation d’outil particulier. Ceci sera utilisé pour faire correspondre les résultats d’outils plus tard.name
: Le nom de l’outil utilisé.input
: Un objet contenant l’entrée passée à l’outil, conforme auinput_schema
de l’outil.
Quand vous recevez une réponse d’utilisation d’outil pour un outil client, vous devriez :
- Extraire le
name
,id
, etinput
du bloctool_use
. - Exécuter l’outil réel dans votre base de code correspondant à ce nom d’outil, en passant l’
input
de l’outil. - Continuer la conversation en envoyant un nouveau message avec le
role
deuser
, et un bloccontent
contenant le typetool_result
et les informations suivantes :tool_use_id
: L’id
de la requête d’utilisation d’outil pour laquelle c’est un résultat.content
: Le résultat de l’outil, comme une chaîne (par exemple"content": "15 degrés"
) ou une liste de blocs de contenu imbriqués (par exemple"content": [{"type": "text", "text": "15 degrés"}]
). Ces blocs de contenu peuvent utiliser les typestext
ouimage
.is_error
(optionnel) : Définir àtrue
si l’exécution de l’outil a résulté en une erreur.
Exigences de formatage importantes :
- Les blocs de résultats d’outils doivent immédiatement suivre leurs blocs d’utilisation d’outils correspondants dans l’historique des messages. Vous ne pouvez pas inclure de messages entre le message d’utilisation d’outil de l’assistant et le message de résultat d’outil de l’utilisateur.
- Dans le message utilisateur contenant les résultats d’outils, les blocs tool_result doivent venir EN PREMIER dans le tableau de contenu. Tout texte doit venir APRÈS tous les résultats d’outils.
Par exemple, ceci causera une erreur 400 :
Ceci est correct :
Si vous recevez une erreur comme “tool_use ids were found without tool_result blocks immediately after”, vérifiez que vos résultats d’outils sont formatés correctement.
Après avoir reçu le résultat d’outil, Claude utilisera cette information pour continuer à générer une réponse au prompt utilisateur original.
Gérer les résultats d’outils serveur
Claude exécute l’outil en interne et incorpore les résultats directement dans sa réponse sans nécessiter d’interaction utilisateur supplémentaire.
Différences par rapport aux autres APIs
Contrairement aux APIs qui séparent l’utilisation d’outils ou utilisent des rôles spéciaux comme tool
ou function
, l’API d’Anthropic intègre les outils directement dans la structure de messages user
et assistant
.
Les messages contiennent des tableaux de blocs text
, image
, tool_use
, et tool_result
. Les messages user
incluent le contenu client et tool_result
, tandis que les messages assistant
contiennent le contenu généré par l’IA et tool_use
.
Gérer la raison d’arrêt max_tokens
Si la réponse de Claude est coupée à cause d’avoir atteint la limite max_tokens
, et que la réponse tronquée contient un bloc d’utilisation d’outil incomplet, vous devrez réessayer la requête avec une valeur max_tokens
plus élevée pour obtenir l’utilisation d’outil complète.
Gérer la raison d’arrêt pause_turn
Lors de l’utilisation d’outils serveur comme la recherche web, l’API peut retourner une raison d’arrêt pause_turn
, indiquant que l’API a mis en pause un tour de longue durée.
Voici comment gérer la raison d’arrêt pause_turn
:
Lors de la gestion de pause_turn
:
- Continuer la conversation : Passez la réponse en pause telle quelle dans une requête subséquente pour laisser Claude continuer son tour
- Modifier si nécessaire : Vous pouvez optionnellement modifier le contenu avant de continuer si vous voulez interrompre ou rediriger la conversation
- Préserver l’état des outils : Incluez les mêmes outils dans la requête de continuation pour maintenir la fonctionnalité
Dépannage des erreurs
Il y a quelques types différents d’erreurs qui peuvent survenir lors de l’utilisation d’outils avec Claude :