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 de vos propres outils personnalisés pour effectuer une plus grande variété de tâches.

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" \
  -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 ?"
      }
    ]
  }'

​

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éfinissez l’ensemble des outils auxquels vous voulez que Claude ait accès, y compris leurs noms, descriptions et schémas d’entrée.
   • Fournissez 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 c’est le cas, 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écutez le code réel de l’outil côté client.
   • Renvoyez 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, le fait que Claude utilise l’outil 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.

​

Spécification des 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 à 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.

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

{
  "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”.

​

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

{
  "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 :

{
  "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 :

{
  "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, l’id et l’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] Poursuivre 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éfinissez à 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 :

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

Les images sont également prises en charge dans content :

{
  "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 :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: l'API du service météo 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 :

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

​

Forcer l’utilisation d’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"}

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 :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: l'API du service météo 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 l’API du service météo n’est pas disponible. Veuillez réessayer plus tard.”

​

Nombre maximum de tokens dépassé

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 meilleure option pendant le développement est de réessayer la requête avec des valeurs de description plus détaillées dans vos définitions d’outils.

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

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

​

Utilisation d’outil 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’outil), 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 :

{
  "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 son action suivante. 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 obtenir 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 s’il manque des 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 ces 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

• 30 mai 2024 : L’utilisation d’outils est lancée en GA et n’est plus en version bêta
• tools-2024-05-16
  • Changement d’invite système pour Opus afin de 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 recueils d’utilisation d’outils : explorez notre référentiel d’exemples de code d’utilisation d’outils prêts à être implémentés, tels que :
  • Utilisation d’un outil de calculatrice avec Claude
  • Création d’un agent de service client avec des outils côté client
  • Extraction de JSON structuré à l’aide de Claude et de l’utilisation d’outils
• 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 obtenir 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 appeler des sous-agents de modèle plus petits, comme Haiku, pour effectuer des tâches en son nom.

Au fur et à mesure que vous construisez avec l’utilisation d’outils, nous aimerions avoir vos commentaires et voir ce que vous créez ! Rejoignez notre Discord de développ eurs pour partager vos projets et discuter des conseils 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 !