Comment implémenter l'utilisation d'outils

Choisir un modèle

Nous recommandons d'utiliser le dernier modèle Claude Sonnet (4.5) ou Claude Opus (4.1) pour les outils complexes et les requêtes ambiguës ; ils gèrent mieux plusieurs outils et demandent des clarifications si nécessaire.

Utilisez les modèles Claude Haiku pour les outils simples, mais notez qu'ils peuvent déduire 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 niveau supérieur tools de la requête API. Chaque définition d'outil comprend :

Invite système d'utilisation d'outils

Lorsque vous appelez l'API Claude 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 d'utiliser les outils spécifiés et de fournir le contexte nécessaire pour que l'outil fonctionne correctement :

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

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 les performances 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
  • Toutes les mises en garde ou limitations importantes, comme les informations que l'outil ne retourne 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 d'accompagnement, c'est moins important que d'avoir une explication claire et complète de l'objectif et des paramètres de l'outil. Ajoutez des exemples uniquement après avoir complètement développé la description.

La bonne description explique clairement ce que fait l'outil, quand l'utiliser, quelles données elle retourne 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.

Exécuteur d'outils (bêta)

L'exécuteur d'outils fournit une solution prête à l'emploi pour exécuter des outils avec Claude. Au lieu de gérer manuellement les appels d'outils, les résultats des outils et la gestion des conversations, l'exécuteur d'outils exécute automatiquement :

• Exécute les outils lorsque Claude les appelle
• Gère le cycle requête/réponse
• Gère l'état de la conversation
• Fournit la sécurité des types et la validation

Nous recommandons d'utiliser l'exécuteur d'outils pour la plupart des implémentations d'utilisation d'outils.

Utilisation de base

Contrôler la sortie de Claude

Forcer l'utilisation d'outils

Dans certains cas, vous souhaiterez peut-être 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 suit :

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 l'un des outils fournis ou non. C'est la valeur par défaut lorsque 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 réponse en langage naturel ou d'explication avant les blocs de contenu tool_use, même s'ils sont explicitement demandés de le faire.

Nos tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez que le modèle fournisse un contexte en langage naturel ou des explications tout en demandant au modèle d'utiliser un outil spécifique, vous pouvez utiliser {"type": "auto"} pour tool_choice (par défaut) et ajouter des instructions explicites dans un message user. Par exemple : Quel est le temps à Londres ? Utilisez l'outil get_weather dans votre réponse.

Sortie JSON

Les outils n'ont pas nécessairement besoin d'être des fonctions clients — vous pouvez utiliser des outils chaque fois que vous souhaitez que le modèle retourne une sortie JSON qui suit un schéma fourni. Par exemple, vous pourriez utiliser un outil record_summary avec un schéma particulier. Voir Utilisation d'outils avec Claude pour un exemple complet de travail.

Réponses du modèle avec outils

Lors de l'utilisation d'outils, Claude commentera souvent ce qu'il fait ou répondra naturellement à l'utilisateur avant d'invoquer des outils.

Par exemple, étant donné l'invite « Quel est le temps à San Francisco en ce moment, et quelle heure est-il là-bas ? », Claude pourrait répondre avec :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Ce style de réponse naturelle aide les utilisateurs à comprendre ce que Claude fait et crée une interaction plus conversationnelle. Vous pouvez guider le style et le contenu de ces réponses par vos invites système et en fournissant <examples> dans vos invites.

Il est important de noter que Claude peut utiliser diverses formulations et approches pour expliquer ses actions. Votre code doit traiter ces réponses comme n'importe quel autre texte généré par l'assistant, et ne pas s'appuyer sur des conventions de formatage spécifiques.

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

Maximiser l'utilisation parallèle d'outils

Bien que les modèles Claude 4 aient d'excellentes capacités d'utilisation parallèle d'outils par défaut, vous pouvez augmenter la probabilité d'exécution parallèle d'outils sur tous les modèles avec des invites ciblées :

Gestion des blocs de contenu d'utilisation d'outils et de résultats d'outils

La réponse de Claude diffère selon qu'elle utilise un outil client ou serveur.

Gestion des résultats des outils clients

La réponse aura un 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. Ceci sera utilisé pour faire correspondre les résultats des outils plus tard.
• name : Le nom de l'outil utilisé.
• input : Un objet contenant l'entrée transmise à l'outil, conforme à input_schema de l'outil.

Lorsque vous recevez une réponse d'utilisation d'outil pour un outil client, vous devez :

1. Extraire 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 transmettant l'input de l'outil.
3. 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 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 degrees"), une liste de blocs de contenu imbriqués (par exemple "content": [{"type": "text", "text": "15 degrees"}]), ou une liste de blocs de documents (par exemple "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Ces blocs de contenu peuvent utiliser les types text, image ou document.
   • is_error (optionnel) : Définissez sur true si l'exécution de l'outil a entraîné une erreur.

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Text after tool_result
]}

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.

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 max_tokens

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

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Gestion de la raison d'arrêt pause_turn

Lors de l'utilisation d'outils serveur comme la recherche Web, l'API peut retourner 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()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Send the continuation request
    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 : Passez la réponse mise en pause telle quelle dans une requête ultérieure pour laisser Claude 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 des outils : Incluez les mêmes outils dans la requête de continuation pour maintenir la fonctionnalité

Dépannage des erreurs

Il existe plusieurs types d'erreurs qui peuvent survenir lors de l'utilisation d'outils avec Claude :