Comment implémenter l'utilisation d'outils

​

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 plusieurs outils et demandent des clarifications lorsque nécessaire.

Utilisez Claude Haiku 3.5 ou Claude Haiku 3 pour les outils simples, mais notez qu’ils peuvent inférer les paramètres manquants.

​

Spécifier les outils clients

Les outils clients (définis par Anthropic et définis par l’utilisateur) sont spécifiés dans le paramètre de premier niveau tools de la requête API. Chaque définition d’outil comprend :

​

Prompt système pour l’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 des 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(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 }}
{{ PROMPT SYSTÈME UTILISATEUR }}
{{ CONFIGURATION D'OUTIL }}

​

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 pour 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 devrait 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 le prompt qui l’accompagne, cela 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.

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’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 quatre options possibles :

• auto permet à Claude de décider s’il doit appeler ou non les outils fournis. C’est la valeur par défaut lorsque des tools sont fournis.
• 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.
• none empêche Claude d’utiliser des outils. C’est la valeur par défaut lorsqu’aucun tools n’est fourni.

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 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 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 Opus 3 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é le prompt “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 Sonnet 3, 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 au prompt 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 devrait 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>.

​

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 lorsque le type de tool_choice est auto, ce qui garantit que Claude utilise au maximum un outil
• Définissant disable_parallel_tool_use=true lorsque le type de tool_choice est any ou tool, ce qui garantit que Claude utilise exactement un outil

​

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

​

Gestion des résultats des outils clients

La réponse aura une 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. Il sera utilisé pour faire correspondre les résultats de l’outil ultérieurement.
• name : Le nom de l’outil utilisé.
• input : Un objet contenant l’entrée transmise à l’outil, conforme à l’input_schema de l’outil.

Lorsque vous recevez une réponse d’utilisation d’outil pour un outil client, 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 transmettant l’input de l’outil.
3. 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 demande d’utilisation d’outil pour laquelle c’est un résultat.
   • content : Le résultat de l’outil, sous forme de chaîne (par exemple, "content": "15 degrés") ou de liste de blocs de contenu imbriqués (par exemple, "content": [{"type": "text", "text": "15 degrés"}]). Ces blocs de contenu peuvent utiliser les types text ou image.
   • is_error (facultatif) : Défini sur 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 au prompt utilisateur initial.

​

Gestion des résultats des 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.

​

Gestion de la raison d’arrêt pause_turn

Lors de l’utilisation d’outils serveur comme la recherche web, l’API peut renvoyer 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 :

import anthropic

client = anthropic.Anthropic()

# Requête initiale avec recherche web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Recherchez des informations complètes sur les percées en informatique quantique en 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Vérifier si la réponse a une raison d'arrêt pause_turn
if response.stop_reason == "pause_turn":
    # Continuer la conversation avec le contenu en pause
    messages = [
        {"role": "user", "content": "Recherchez des informations complètes sur les percées en informatique quantique en 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Envoyer la requête de continuation
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Lors de la gestion de pause_turn :

• Continuer la conversation : Transmettez la réponse en pause telle quelle dans une requête ultérieure pour permettre à Claude de continuer son tour
• Modifier si nécessaire : Vous pouvez éventuellement modifier le contenu avant de continuer si vous souhaitez interrompre ou rediriger la conversation
• Préserver l’état de l’outil : Incluez les mêmes outils dans la requête de continuation pour maintenir la fonctionnalité

​

Dépannage des erreurs

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