Claude est capable d’interagir avec des outils et des fonctions externes côté client, vous permettant d’équiper Claude de vos propres outils personnalisés pour effectuer une plus grande variété de tâches.

Bêta publique d’utilisation d’outils

Nous sommes ravis d’annoncer que l’utilisation d’outils est maintenant en bêta publique ! Pour accéder à cette fonctionnalité, vous devrez inclure l’en-tête anthropic-beta: tools-2024-05-16 dans vos requêtes API.

Streaming, forcer l’utilisation d’outils, et images sont maintenant pris en charge ! Voir plus dans l’historique des versions bêta.

Nous itérerons sur cette bêta ouverte au cours des prochaines semaines, donc nous apprécions tous vos commentaires. Veuillez partager vos idées et suggestions en utilisant ce formulaire.

Voici un exemple de comment fournir des outils à Claude en utilisant l’API Messages :

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: tools-2024-05-16" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle pour un lieu donné",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "La ville et l'état, par ex. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Quel temps fait-il à San Francisco ?"
      }
    ]
  }'

Veuillez noter que pendant la période bêta :

  • Bien que la fonctionnalité soit prête pour la production, nous pouvons introduire plusieurs versions bêta avant la version finale.
  • L’utilisation d’outils n’est pas encore disponible sur les plateformes tierces comme Vertex AI ou AWS Bedrock, mais arrive bientôt. Voir Utilisation d’outils héritée pour des conseils sur comment utiliser les outils sur Vertex AI et AWS Bedrock dès maintenant.

Comment fonctionne l’utilisation d’outils

L’utilisation d’outils avec Claude implique les étapes suivantes :

  1. Fournir à Claude des outils et une invite utilisateur : (requête API)
    • Définir l’ensemble des outils auxquels vous voulez que Claude ait accès, y compris leurs noms, descriptions et schémas d’entrée.
    • Fournir une invite utilisateur qui peut nécessiter l’utilisation d’un ou plusieurs de ces outils pour répondre, comme “Quel temps fait-il à San Francisco ?“.
  2. Claude utilise un outil : (réponse API)
    • Claude évalue l’invite utilisateur et décide si l’un des outils disponibles aiderait à répondre à la requête ou à la tâche de l’utilisateur. Si oui, il décide également quel(s) outil(s) utiliser et avec quelles entrées.
    • Claude construit une requête d’utilisation d’outil correctement formatée.
    • La réponse API aura une stop_reason de tool_use, indiquant que Claude veut utiliser un outil externe.
  3. Extraire l’entrée de l’outil, exécuter le code et renvoyer les résultats : (requête API)
    • Côté client, vous devez extraire le nom de l’outil et l’entrée de la requête d’utilisation d’outil de Claude.
    • Exécuter le code réel de l’outil côté client.
    • Renvoyer les résultats à Claude en poursuivant 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 : (réponse API)
    • Après avoir reçu les résultats de l’outil, Claude utilisera ces informations pour formuler sa réponse finale à l’invite utilisateur d’origine.

Les étapes (3) et (4) sont facultatives - pour certains workflows, l’utilisation de l’outil par Claude est toute l’information dont vous avez besoin, et vous n’avez peut-être pas besoin de renvoyer les résultats de l’outil à 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.


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 :

  • 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.

Voici un exemple de définition d’outil simple :

JSON
{
  "name": "get_weather",
  "description": "Obtenir la météo actuelle pour un lieu donné",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La ville et l'état, par ex. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "L'unité de température, soit 'celsius' soit 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Cet outil, nommé get_weather, attend un objet d’entrée avec une chaîne location requise et une chaîne unit optionnelle qui doit être soit “celsius” soit “fahrenheit”.

Meilleures pratiques pour les définitions d’outils

Pour obtenir les meilleures performances de Claude lors de l’utilisation d’outils, suivez ces directives :

  • Fournir 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 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 quelles informations 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.
  • Prioriser les descriptions par rapport 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 de l’objectif et des paramètres de l’outil. N’ajoutez des exemples qu’après avoir entièrement développé la description.

Voici un exemple de bonne description d’outil :

JSON
{
  "name": "get_stock_price",
  "description": "Récupère le cours actuel de l'action pour un symbole boursier donné. Le symbole boursier doit être un symbole valide pour une société cotée en bourse sur une grande bourse américaine comme le NYSE ou le NASDAQ. L'outil renverra le dernier prix de transaction en USD. Il doit être utilisé lorsque l'utilisateur demande le prix actuel ou le plus récent d'une action spécifique. Il ne fournira aucune autre information sur l'action ou la société.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Le symbole boursier, par ex. AAPL pour Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

En revanche, voici un exemple de mauvaise description d’outil :

JSON
{
  "name": "get_stock_price",
  "description": "Obtient le cours de l'action pour un symbole boursier.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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.


Blocs de contenu d’utilisation d’outil et de résultat d’outil

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

Voici un exemple de réponse API avec un bloc de contenu tool_use :

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>J'ai besoin d'utiliser get_weather, et l'utilisateur veut SF, qui est probablement San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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. [facultatif] Continuer la conversation en envoyant un nouveau message avec le role de user, et un bloc 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 de 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 (facultatif) : Définir à true si l’exécution de l’outil a entraîné une erreur.

Voici un exemple de renvoi d’un résultat d’outil réussi :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrés"
    }
  ]
}

Les images sont également prises en charge dans content :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrés"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Et voici un exemple de renvoi d’un résultat d’erreur :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content":  "ConnectionError: le service météo API n'est pas disponible (HTTP 500)",
      "is_error": true
    }
  ]
}

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

Vous pouvez également renvoyer un résultat d’outil non erroné avec un content vide, indiquant que l’outil s’est exécuté avec succès sans aucune sortie :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Différences par rapport aux autres API

Vous connaissez peut-être d’autres API qui renvoient l’utilisation d’outil séparément de la sortie principale du modèle, ou qui utilisent un role de message spécial tool ou function.

En revanche, les modèles et l’API d’Anthropic sont construits autour de messages user et assistant alternés, où chaque message est un tableau de riches blocs de contenu : text, image, tool_use et tool_result.

Dans ce format, les messages user représentent le contenu géré par le client et l’utilisateur / humain, et les messages assistant représentent le contenu géré par le serveur et l’IA. En tant que tel, il n’y a pas de role de message spécial tool ou function, et vous devez inclure les blocs tool_result dans le content de vos messages user.


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 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"}

En disant explicitement à Claude d’utiliser l’outil get_weather, vous pouvez l’encourager à utiliser l’outil que vous voulez. Cette technique peut être utile pour tester et déboguer vos intégrations d’outils, ou lorsque vous savez que l’outil doit toujours être utilisé, quelle que soit l’entrée.

Vous pouvez également dire à Claude d’utiliser n’importe lequel des outils fournis via {"type": "any"}. Le tool_choice par défaut est {"type": "auto"}, ce qui permet à Claude de décider d’utiliser ou non un outil.

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.


Gestion des erreurs

Il existe quelques types d’erreurs différents qui peuvent se produire lors de l’utilisation d’outils avec Claude :

Erreur d’exécution d’outil

Si l’outil lui-même génère une erreur pendant l’exécution (par ex. une erreur réseau lors de la récupération des données météorologiques), vous pouvez renvoyer le message d’erreur dans le content avec "is_error": true :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: le service météo API n'est pas disponible (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude intégrera alors cette erreur dans sa réponse à l’utilisateur, par ex. “Je suis désolé, je n’ai pas pu récupérer la météo actuelle car le service météo API n’est pas disponible. Veuillez réessayer plus tard.”

Dépassement du nombre maximum de tokens

Si la réponse de Claude est coupée en raison de 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 complète de l’outil.

Utilisation d’outil invalide

Si la tentative d’utilisation d’un outil par Claude est invalide (par ex. paramètres requis manquants), cela signifie généralement qu’il n’y avait pas assez d’informations pour que Claude utilise correctement l’outil. Votre meilleur pari pendant le développement est d’essayer à nouveau la requête avec des valeurs description plus détaillées dans vos définitions d’outils.

Cependant, vous pouvez également continuer la conversation avec un tool_result qui indique l’erreur, et Claude essaiera d’utiliser à nouveau l’outil avec les informations manquantes remplies :

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erreur : Paramètre 'location' requis manquant",
      "is_error": true
    }
  ]
}

Utilisation d’outils avec 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 incités à le faire.

Par exemple, étant donné l’invite “Quel temps fait-il à San Francisco en ce moment, 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 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. Pour un exemple plus détaillé, voir exemple d’utilisation d’outil avec chaîne de pensée.

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>.


Meilleures pratiques et limitations de l’utilisation d’outils

Lorsque vous utilisez des outils avec Claude, gardez à l’esprit les limitations et les meilleures pratiques suivantes :

  • Utilisez Claude 3 Opus pour naviguer dans une utilisation complexe d’outils, Haiku pour des outils simples : Opus est capable de gérer le plus grand nombre d’outils simultanés et est meilleur pour détecter les arguments manquants par rapport aux autres modèles. Il est plus susceptible de demander des clarifications dans les cas ambigus où un argument n’est pas explicitement donné ou lorsqu’un outil peut ne pas être nécessaire pour répondre à la demande de l’utilisateur. Haiku essaie par défaut d’utiliser les outils plus fréquemment (même s’ils ne sont pas pertinents pour la requête) et déduira les paramètres manquants s’ils ne sont pas explicitement donnés.
  • Nombre d’outils : Tous les modèles Claude 3 peuvent maintenir une précision >90% même lorsqu’ils travaillent avec des centaines d’outils simples, et un plus petit nombre d’outils complexes. Un outil “complexe” serait un outil avec un grand nombre de paramètres ou des paramètres avec des schémas complexes (par ex. des objets imbriqués).
  • Outils complexes et profondément imbriqués : Tout comme un humain, Claude peut mieux travailler avec des interfaces et des outils plus simples. Si Claude a du mal à utiliser correctement votre outil, essayez d’aplatir le schéma d’entrée en évitant les objets json profondément imbriqués, et réduisez le nombre d’entrées.
  • Utilisation séquentielle d’outils : Claude préfère généralement utiliser un outil à la fois, puis utiliser la sortie de cet outil pour informer sa prochaine action. Bien que vous puissiez inciter Claude à utiliser plusieurs outils en parallèle en concevant soigneusement votre invite et vos outils, cela peut amener Claude à remplir des valeurs factices pour les paramètres qui dépendent des résultats d’une utilisation antérieure d’outil. Pour de meilleurs résultats, concevez votre workflow et vos outils pour susciter et travailler avec une série d’utilisations séquentielles d’outils de la part de Claude.
  • Nouvelles tentatives : Si la requête d’utilisation d’outil de Claude est invalide ou manque de paramètres requis, vous pouvez renvoyer une réponse d’erreur et Claude réessaiera généralement la requête avec les informations manquantes remplies. Cependant, après 2-3 tentatives infructueuses, Claude peut abandonner et renvoyer des excuses à l’utilisateur au lieu de réessayer.
  • Débogage : Lors du débogage d’un comportement inattendu d’utilisation d’outil, faites attention à la sortie de la chaîne de pensée de Claude (le cas échéant) pour comprendre pourquoi il fait les choix qu’il fait. Vous pouvez également essayer d’inciter Claude à utiliser un outil spécifique pour voir si cela conduit au comportement attendu. Si Claude utilise mal un outil, vérifiez à nouveau que vos descriptions d’outils et vos schémas sont clairs et sans ambiguïté.
  • Balises <search_quality_reflection> : Parfois, lors de l’utilisation d’outils de recherche, le modèle peut renvoyer des balises XML <search_quality_reflection> et un score de qualité de recherche dans sa réponse. Pour empêcher le modèle de le faire, ajoutez la phrase “Ne réfléchissez pas à la qualité des résultats de recherche renvoyés dans votre réponse.” à la fin de votre invite.

En gardant ces limitations et directives à l’esprit, vous pouvez concevoir des outils efficaces et des orchestrations agentiques qui étendent considérablement les capacités de Claude pour s’attaquer à une grande variété de tâches.


Historique des versions bêta

  • tools-2024-05-16
    • Changement d’invite système pour Opus pour mieux gérer les scénarios où plusieurs utilisations d’outils peuvent être nécessaires en un seul tour
  • tools-2024-04-04 : Version bêta initiale pour l’utilisation d’outils

Prochaines étapes

L’utilisation d’outils est une technique puissante pour étendre les capacités de Claude en le connectant à des sources de données et des fonctionnalités externes. Avec un ensemble d’outils bien conçus, vous pouvez permettre à Claude de s’attaquer à une énorme variété de tâches qui seraient impossibles avec ses seules connaissances de base.

Quelques prochaines étapes potentielles à explorer :

  • Parcourez nos recettes d’utilisation d’outils : explorez notre référentiel d’exemples de code d’utilisation d’outils prêts à implémenter, tels que :
  • Améliorez la qualité et la fiabilité de l’utilisation d’outils : Itérez et améliorez vos descriptions d’outils et vos invites pour susciter une utilisation d’outils plus fiable et précise de la part de Claude
  • Étendez les capacités de Claude :
    • Expérimentez avec différents outils et schémas pour voir comment Claude gère différents types de formats d’entrée et de sortie.
    • Enchaînez plusieurs outils pour décomposer des tâches complexes en une série d’étapes plus simples.
    • Construisez des orchestrations agentiques où Claude peut effectuer une variété de tâches de bout en bout comme s’il était un assistant.
    • Explorez des architectures complexes d’utilisation d’outils comme donner à Claude des outils pour faire une recherche RAG, ou pour faire appel à des sous-agents de modèles plus petits, comme Haiku, pour effectuer des tâches en son nom.

Pendant que vous construisez avec l’utilisation d’outils, nous aimerions entendre vos commentaires et voir ce que vous créez ! Rejoignez notre Discord de développeurs pour partager vos projets et discuter des astuces et techniques avec d’autres développeurs.

Nous sommes impatients de voir comment vous utilisez l’utilisation d’outils pour repousser les limites de ce qui est possible avec Claude. Bonne construction !