Utilisation d'outils (appel de fonctions)
Claude est capable d’interagir avec des outils et des fonctions externes côté client, vous permettant d’équiper Claude avec vos propres outils personnalisés pour effectuer une plus grande variété de tâches.
Apprenez tout ce que vous devez savoir pour maîtriser l’utilisation des outils avec Claude via notre nouveau cours complet sur l’utilisation des outils ! Continuez à partager vos idées et suggestions en utilisant ce formulaire.
Voici un exemple de comment fournir des outils à Claude en utilisant l’API Messages :
Comment fonctionne l’utilisation d’outils
Intégrez des outils externes avec Claude en suivant ces étapes :
Fournissez à Claude des outils et une requête utilisateur
- Définissez les outils avec des noms, des descriptions et des schémas d’entrée dans votre requête API.
- Incluez une requête utilisateur qui pourrait nécessiter ces outils, par ex. “Quel temps fait-il à San Francisco ?”
Claude décide d'utiliser un outil
- Claude évalue si des outils peuvent aider à répondre à la requête de l’utilisateur.
- Si oui, Claude construit une requête d’utilisation d’outil correctement formatée.
- La réponse de l’API a une
stop_reason
detool_use
, signalant l’intention de Claude.
Extrayez l'entrée de l'outil, exécutez le code et renvoyez les résultats
- De votre côté, extrayez le nom de l’outil et l’entrée de la requête de Claude.
- Exécutez le code réel de l’outil côté client.
- Poursuivez la conversation avec un nouveau message
user
contenant un bloc de contenutool_result
.
Claude utilise le résultat de l'outil pour formuler une réponse
- Claude analyse les résultats de l’outil pour élaborer sa réponse finale à la requête initiale de l’utilisateur.
Note : Les étapes 3 et 4 sont facultatives. Pour certains workflows, la requête d’utilisation d’outil de Claude (étape 2) peut être tout ce dont vous avez besoin, sans renvoyer les résultats à Claude.
Tous les outils sont fournis par l’utilisateur
Il est important de noter que Claude n’a accès à aucun outil intégré côté serveur. Tous les outils doivent être explicitement fournis par vous, l’utilisateur, dans chaque requête API. Cela vous donne un contrôle total et une flexibilité sur les outils que Claude peut utiliser.
Comment implémenter l’utilisation d’outils
Choisir un modèle
En général, utilisez Claude 3 Opus pour les outils complexes et les requêtes ambiguës ; il gère mieux plusieurs outils et demande des clarifications si nécessaire.
Utilisez Haiku pour les outils simples, mais notez qu’il peut déduire les paramètres manquants.
Spécifier les outils
Les outils sont spécifiés dans le paramètre de niveau supérieur tools
de la requête API. Chaque définition d’outil comprend :
Paramètre | Description |
---|---|
name | Le nom de l’outil. Doit correspondre à l’expression régulière ^[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. |
Bonnes 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 pour la performance des outils. Vos descriptions doivent expliquer chaque détail sur l’outil, y compris :
- 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 renvoie pas si le nom de l’outil n’est pas clair. Plus vous pouvez donner de contexte à Claude sur vos outils, mieux il sera capable de décider quand et comment les utiliser. Visez au moins 3-4 phrases par description d’outil, plus si l’outil est complexe.
- Privilégiez les descriptions par rapport aux exemples. Bien que vous puissiez inclure des exemples d’utilisation d’un outil dans sa description ou dans la requête qui l’accompagne, c’est moins important que d’avoir une explication claire et complète de l’objectif et des paramètres de l’outil. N’ajoutez des exemples qu’après avoir pleinement développé la description.
La bonne description explique clairement ce que fait l’outil, quand l’utiliser, quelles données il renvoie 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’un outil
Dans certains cas, vous pouvez 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 le faire en spécifiant l’outil dans le champ tool_choice
comme ceci :
tool_choice = {"type": "tool", "name": "get_weather"}
Lorsque vous travaillez avec le paramètre tool_choice, nous avons trois options possibles :
auto
permet à Claude de décider d’appeler ou non les outils fournis. C’est la valeur par défaut.any
indique à Claude qu’il doit utiliser l’un des outils fournis, mais ne force pas un outil particulier.tool
nous permet de forcer Claude à toujours utiliser un outil particulier.
Ce diagramme illustre le fonctionnement de chaque option :
Notez que lorsque vous avez tool_choice
comme any
ou tool
, nous pré-remplirons le message de l’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 cela est explicitement demandé.
Nos tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez conserver la chaîne de pensée (en particulier avec Opus) tout en demandant au modèle d’utiliser un outil spécifique, vous pouvez utiliser {"type": "auto"}
pour tool_choice
(la valeur 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 ne doivent pas nécessairement être des fonctions côté client - vous pouvez utiliser des outils chaque fois que vous voulez que le modèle renvoie une sortie JSON qui suit un schéma fourni. Par exemple, vous pouvez utiliser un outil record_summary
avec un schéma particulier. Voir exemples d’utilisation d’outils 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 3 Opus le fera si tool_choice
est défini sur auto
(c’est la valeur par défaut, voir Forcer l’utilisation d’un outil), et Sonnet et Haiku peuvent être incités à le faire.
Par exemple, étant donné la requête “Quel temps fait-il à San Francisco en ce moment, et quelle heure est-il là-bas ?”, Claude pourrait répondre avec :
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "<thinking>Pour répondre à cette question, je vais : 1. Utiliser l'outil get_weather pour obtenir la météo actuelle à San Francisco. 2. Utiliser l'outil get_time pour obtenir l'heure actuelle dans le fuseau horaire America/Los_Angeles, qui couvre San Francisco, CA.</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "San Francisco, CA"}
}
]
}
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 3 Sonnet, la chaîne de pensée est moins courante 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 à l’invite système.
Il est important de noter que bien que les balises <thinking>
soient une convention courante que Claude utilise pour désigner sa chaîne de pensée, le format exact (comme le nom de cette balise XML) peut changer au fil du temps. Votre code doit traiter la chaîne de pensée comme n’importe quel autre texte généré par l’assistant, et ne pas compter sur la présence ou le formatage spécifique des balises <thinking>
.
Gérer les blocs de contenu tool_use et tool_result
Lorsque Claude décide d’utiliser l’un des outils que vous avez fournis, il renverra une réponse avec une stop_reason
de tool_use
et un ou plusieurs blocs de contenu tool_use
dans la réponse de l’API qui incluent :
id
: Un identifiant unique pour ce bloc d’utilisation d’outil particulier. Il sera utilisé pour faire correspondre les résultats de l’outil 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.
Lorsque vous recevez une réponse d’utilisation d’outil, vous devez :
- Extraire le
name
, l’id
et l’input
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. - [facultatif] Poursuivre 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, sous forme de chaîne (par ex."content": "15 degrés"
) ou de liste de blocs de contenu imbriqués (par ex."content": [{"type": "text", "text": "15 degrés"}]
). Ces blocs de contenu peuvent utiliser les typestext
ouimage
.is_error
(facultatif) : Définir àtrue
si l’exécution de l’outil a entraîné une erreur.
Après avoir reçu le résultat de l’outil, Claude utilisera ces informations pour continuer à générer une réponse à la requête initiale de l’utilisateur.
Différences par rapport aux autres API
Contrairement aux API 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 message user
et assistant
.
Les messages contiennent des tableaux de blocs text
, image
, tool_use
et tool_result
. Les messages user
incluent le contenu côté client et tool_result
, tandis que les messages assistant
contiennent le contenu généré par l’IA et tool_use
.
Dépannage des erreurs
Il existe quelques types d’erreurs différents qui peuvent se produire lors de l’utilisation d’outils avec Claude :
Exemples d’utilisation d’outils
Voici quelques exemples de code démontrant divers modèles et techniques d’utilisation d’outils. Par souci de concision, les outils sont des outils simples et les descriptions d’outils sont plus courtes que ce qui serait idéal pour garantir les meilleures performances.
Tarification
Les requêtes d’utilisation d’outils sont facturées de la même manière que toute autre requête d’API Claude, en fonction du nombre total de tokens d’entrée envoyés au modèle (y compris dans le paramètre tools
) et du nombre de tokens de sortie générés.”
Les tokens supplémentaires de l’utilisation d’outils proviennent de :
- Le paramètre
tools
dans les requêtes d’API (noms d’outils, descriptions et schémas) - Les blocs de contenu
tool_use
dans les requêtes et réponses d’API - Les blocs de contenu
tool_result
dans les requêtes d’API
Lorsque vous utilisez tools
, nous incluons également automatiquement une invite système spéciale pour le modèle qui active l’utilisation d’outils. Le nombre de tokens d’utilisation d’outils requis pour chaque modèle est indiqué ci-dessous (à l’exclusion des tokens supplémentaires listés ci-dessus) :
Modèle | Choix d’outil | Nombre de tokens de l’invite système d’utilisation d’outils |
---|---|---|
Claude 3.5 Sonnet | auto any , tool | 294 tokens 261 tokens |
Claude 3 Opus | auto any , tool | 530 tokens 281 tokens |
Claude 3 Sonnet | auto any , tool | 159 tokens 235 tokens |
Claude 3 Haiku | auto any , tool | 264 tokens 340 tokens |
Ces nombres de tokens sont ajoutés à vos tokens d’entrée et de sortie normaux pour calculer le coût total d’une requête. Reportez-vous à notre tableau de présentation des modèles pour les prix actuels par modèle.
Lorsque vous envoyez une invite d’utilisation d’outil, comme pour toute autre requête d’API, la réponse affichera à la fois les nombres de tokens d’entrée et de sortie dans le cadre des métriques d’usage
rapportées.
Prochaines étapes
Explorez notre référentiel d’exemples de code d’utilisation d’outils prêts à implémenter dans nos recueils :
Outil Calculatrice
Apprenez à intégrer un simple outil de calculatrice avec Claude pour des calculs numériques précis.
Agent de service client
Construisez un bot de service client réactif qui tire parti d’outils côté client pour améliorer l’assistance.
Extracteur JSON
Voyez comment Claude et l’utilisation d’outils peuvent extraire des données structurées à partir de texte non structuré.