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 dont vous avez besoin pour maîtriser l’utilisation d’outils avec Claude via notre nouveau cours complet sur l’utilisation d’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 :

1

Fournir à Claude des outils et une invite utilisateur

  • Définissez les outils avec des noms, descriptions et schémas d’entrée dans votre requête API.
  • Incluez une invite utilisateur qui pourrait nécessiter ces outils, par ex. “Quel temps fait-il à San Francisco ?”
2

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 API a une stop_reason de tool_use, signalant l’intention de Claude.
3

Extraire l'entrée de l'outil, exécuter le code et retourner 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.
  • Continuez la conversation avec un nouveau message user contenant un bloc de contenu tool_result.
4

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 à l’invite utilisateur originale.

Note : Les étapes 3 et 4 sont optionnelles. Pour certains flux de travail, la requête d’utilisation d’outil de Claude (étape 2) pourrait être tout ce dont vous avez besoin, sans envoyer de résultats à Claude.

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.

La fonctionnalité utilisation d’ordinateur (bêta) est une exception - elle introduit des outils qui sont fournis par Anthropic mais implémentés par vous, l’utilisateur.


Comment implémenter l’utilisation d’outils

Choisir un modèle

En général, utilisez Claude 3.5 Sonnet ou Claude 3 Opus pour les outils complexes et les requêtes ambiguës ; ils gèrent mieux plusieurs outils et demandent des clarifications si nécessaire.

Utilisez Claude 3.5 Haiku ou Claude 3 Haiku pour les outils simples, mais notez qu’ils peuvent déduire des 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 inclut :

ParamètreDescription
nameLe nom de l’outil. Doit correspondre à la regex ^[a-zA-Z0-9_-]{1,64}$.
descriptionUne description détaillée en texte brut de ce que fait l’outil, quand il doit être utilisé et comment il se comporte.
input_schemaUn objet JSON Schema définissant les paramètres attendus pour l’outil.

Invite système pour l’utilisation d’outils

Lorsque vous appelez l’API Anthropic avec le paramètre tools, nous construisons une invite système spéciale à partir des définitions d’outils, de la configuration des outils et de toute invite système spécifiée par l’utilisateur. L’invite construite est conçue pour instruire le modèle à utiliser le(s) outil(s) spécifié(s) et fournir le contexte nécessaire pour que l’outil fonctionne correctement :

Dans cet environnement, vous avez accès à un ensemble d'outils que vous pouvez utiliser pour répondre à la question de l'utilisateur.
{{ INSTRUCTIONS DE FORMATAGE }}
Les paramètres de type chaîne et scalaire doivent être spécifiés tels quels, tandis que les listes et les objets doivent utiliser le format JSON. Notez que les espaces pour les valeurs de chaîne ne sont pas supprimés. La sortie n'est pas censée être du XML valide et est analysée avec des expressions régulières.
Voici les fonctions disponibles au format JSONSchema :
{{ DÉFINITIONS D'OUTILS EN JSON SCHEMA }}
{{ INVITE SYSTÈME UTILISATEUR }}
{{ CONFIGURATION DES OUTILS }}

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 la performance des outils. Vos descriptions doivent expliquer chaque détail concernant l’outil, notamment :
    • 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
    • Toutes les mises en garde ou limitations importantes, 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 en mesure 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 aux exemples. Bien que vous puissiez inclure des exemples d’utilisation d’un outil dans sa description ou dans l’invite qui l’accompagne, 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 renvoie et ce que signifie le paramètre ticker. La mauvaise description est trop brève et laisse à Claude 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 pouvez vouloir que Claude utilise un outil spécifique pour répondre à la question de l’utilisateur, même si Claude pense qu’il peut 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 s’il doit 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 comment chaque option fonctionne :

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 on leur demande explicitement de le faire.

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 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 pourriez 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’outils), et Sonnet et Haiku peuvent être invités à le faire.

Par exemple, étant donné l’invite “Quel temps fait-il à San Francisco maintenant, et quelle heure est-il là-bas ?”, Claude pourrait répondre avec :

JSON
{
  "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 inviter 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 se fier à la présence ou au formatage spécifique des balises <thinking>.

Désactiver l’utilisation parallèle d’outils

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 dans le champ tool_choice.

  • Lorsque le type de tool_choice est auto, cela garantit que Claude utilise au plus un outil
  • Lorsque le type de tool_choice est any ou tool, cela garantit que Claude utilise exactement un outil

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 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 transmise à l’outil, conforme au input_schema de l’outil.

Lorsque vous recevez une réponse d’utilisation d’outil, vous devez :

  1. Extraire le name, id, et input du bloc tool_use.
  2. Exécuter l’outil réel dans votre base de code correspondant à ce nom d’outil, en passant l’input de l’outil.
  3. [optionnel] Continuer la conversation en envoyant un nouveau message avec le role de user, et un bloc de content contenant le type tool_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 liste de blocs de contenu imbriqués (par ex. "content": [{"type": "text", "text": "15 degrés"}]). Ces blocs de contenu peuvent utiliser les types text ou image.
    • is_error (optionnel) : Défini sur true si l’exécution de l’outil a résulté en une erreur.

Après avoir reçu le résultat de l’outil, Claude utilisera cette information pour continuer à générer une réponse à l’invite utilisateur originale.

Différences avec les 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 des messages 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épanner les erreurs

Il existe plusieurs types d’erreurs qui peuvent survenir 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 brièveté, les outils sont des outils simples, et les descriptions d’outils sont plus courtes que ce qui serait idéal pour assurer 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 API Claude, basée sur le nombre total de tokens d’entrée envoyés au modèle (y compris dans le paramètre tools) et le 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 API (noms d’outils, descriptions et schémas)
  • Les blocs de contenu tool_use dans les requêtes et réponses API
  • Les blocs de contenu tool_result dans les requêtes 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 listé ci-dessous (excluant les tokens supplémentaires listés ci-dessus) :

ModèleChoix d’outilNombre de tokens d’invite système pour l’utilisation d’outils
Claude 3.5 Sonnet (Oct)auto
any, tool
346 tokens
313 tokens
Claude 3 Opusauto
any, tool
530 tokens
281 tokens
Claude 3 Sonnetauto
any, tool
159 tokens
235 tokens
Claude 3 Haikuauto
any, tool
264 tokens
340 tokens
Claude 3.5 Sonnet (Juin)auto
any, tool
294 tokens
261 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. Référez-vous à notre tableau de comparaison des modèles pour les prix actuels par modèle.

Lorsque vous envoyez une invite d’utilisation d’outil, comme toute autre requête API, la réponse produira à 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 dépôt d’exemples de code d’utilisation d’outils prêts à implémenter dans nos cookbooks :