Définir des outils

Prérequis

• Une familiarité avec la présentation de l'utilisation d'outils
• Une clé API Claude et une configuration SDK ou cURL fonctionnelle

Spécifier des outils client

Les « client tools » (outils client) sont spécifiés dans le paramètre de premier niveau tools de la requête API. Les outils client à schéma Anthropic, tels que les outils bash et éditeur de texte, sont déclarés par un type versionné par date ; consultez la page de chaque outil, accessible depuis la Référence des outils, pour connaître les champs qu'il accepte. Les outils d'utilisation de l'ordinateur et d'utilisation du navigateur sont des ensembles d'outils client : une entrée unique sans name qui déclare un ensemble fixe d'outils membres. Une définition d'outil définie par l'utilisateur comprend :

Pour l'ensemble complet des propriétés facultatives disponibles sur toute définition d'outil individuelle, y compris cache_control, strict, defer_loading et allowed_callers, consultez la Référence des outils. Une entrée d'ensemble d'outils client accepte cache_control et allowed_callers sur l'entrée et définit defer_loading par membre ; consultez Ensembles d'outils client.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Invite système pour l'utilisation d'outils

Lorsque vous appelez l'API Claude avec le paramètre tools, l'API construit une « system prompt » (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. Le prompt construit est conçu pour indiquer au modèle d'utiliser le ou les outils spécifiés et fournir le contexte nécessaire au bon fonctionnement de l'outil :

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

Bonnes pratiques pour les définitions d'outils

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

• Fournissez des descriptions extrêmement détaillées. C'est de loin le facteur le plus important pour les performances des outils. Vos descriptions doivent expliquer chaque détail de 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
  • 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 saura décider quand et comment les utiliser. Visez au moins 3 à 4 phrases pour chaque description d'outil, davantage si l'outil est complexe.
• Privilégiez les descriptions, mais envisagez d'utiliser input_examples pour les outils complexes. Des descriptions claires sont le plus important, mais pour les outils avec des entrées complexes, des objets imbriqués ou des paramètres sensibles au format, vous pouvez utiliser le champ input_examples pour fournir des exemples validés par le schéma. Consultez Fournir des exemples d'utilisation d'outils pour plus de détails.
• Regroupez les opérations connexes en moins d'outils. Plutôt que de créer un outil distinct pour chaque action (create_pr, review_pr, merge_pr), regroupez-les en un seul outil avec un paramètre action. Des outils moins nombreux et plus performants réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à parcourir pour Claude.
• Utilisez des espaces de noms significatifs dans les noms d'outils. Lorsque vos outils couvrent plusieurs services ou ressources, préfixez les noms avec le service (par exemple, github_list_prs, slack_send_message). Cela rend la sélection d'outils sans ambiguïté à mesure que votre bibliothèque s'agrandit, et c'est particulièrement important lors de l'utilisation de la recherche d'outils.
• Concevez les réponses des outils pour ne renvoyer que des informations à fort signal. Renvoyez des identifiants sémantiques et stables (par exemple, des slugs ou des UUID) plutôt que des références internes opaques, et n'incluez que les champs dont Claude a besoin pour raisonner sur sa prochaine étape. Des réponses surchargées gaspillent du contexte et rendent plus difficile pour Claude d'extraire ce qui compte.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "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.

Fournir des exemples d'utilisation d'outils

Vous pouvez fournir des exemples concrets d'entrées d'outils valides pour aider Claude à comprendre comment utiliser vos outils plus efficacement. C'est particulièrement utile pour les outils complexes avec des objets imbriqués, des paramètres facultatifs ou des entrées sensibles au format.

Utilisation de base

Ajoutez un champ facultatif input_examples à votre définition d'outil avec un tableau d'objets d'entrée d'exemple. Chaque exemple doit être valide selon le input_schema de l'outil :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Les exemples sont inclus dans le prompt aux côtés de votre schéma d'outil, montrant à Claude des modèles concrets d'appels d'outils bien formés. Cela aide Claude à comprendre quand inclure des paramètres facultatifs, quels formats utiliser et comment structurer des entrées complexes.

Exigences et limitations

• Validation du schéma - Chaque exemple doit être valide selon le input_schema de l'outil. Les exemples invalides renvoient une erreur 400
• Non pris en charge pour les outils côté serveur ou les ensembles d'outils client - Les exemples d'entrée fonctionnent sur les outils client définis par l'utilisateur et à schéma Anthropic autres que les ensembles d'outils d'utilisation de l'ordinateur et d'utilisation du navigateur, mais pas sur les outils serveur tels que la recherche web ou l'exécution de code
• Coût en tokens - Les exemples s'ajoutent aux tokens du prompt : environ 20 à 50 tokens pour les exemples simples, environ 100 à 200 tokens pour les objets imbriqués complexes

Contrôler la sortie de Claude

Forcer l'utilisation d'outils

Dans certains cas, vous pouvez souhaiter que Claude utilise un outil spécifique pour répondre à la question de l'utilisateur, même si Claude répondrait autrement directement sans appeler d'outil. Vous pouvez le faire en spécifiant l'outil dans le champ tool_choice de la requête.

Tous les modèles et paramètres ne prennent pas en charge l'utilisation forcée d'outils. Lorsqu'elle n'est pas prise en charge, tool_choice: {"type": "any"} et tool_choice: {"type": "tool", "name": "..."} échouent, tandis que tool_choice: {"type": "auto"} (la valeur par défaut) et tool_choice: {"type": "none"} fonctionnent toujours :

Sur les modèles qui la prennent en charge, les lignes mises en évidence sont la seule différence par rapport à une requête d'utilisation d'outils standard :

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Lorsque vous travaillez avec le paramètre tool_choice, il existe quatre options possibles :

• auto permet à Claude de décider d'appeler ou non l'un des 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 force 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 tool_choice est défini sur any ou tool, l'API préremplit le message de l'assistant pour forcer l'utilisation d'un outil. Cela signifie que les modèles n'émettront pas de réponse ou d'explication en langage naturel avant les blocs de contenu tool_use, même si cela leur est explicitement demandé.

Les tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez que le modèle fournisse un contexte ou des explications en langage naturel 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 : What's the weather like in London? Use the get_weather tool in your response.

Réponses du modèle avec des outils

Lors de l'utilisation d'outils, Claude commente souvent ce qu'il fait ou répond naturellement à l'utilisateur avant d'appeler des outils.

Par exemple, avec le prompt « What's the weather like in San Francisco right now, and what time is it there? », Claude pourrait répondre :

{
  "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 naturel aide les utilisateurs à comprendre ce que fait Claude et crée une interaction plus conversationnelle. Vous pouvez orienter le style et le contenu de ces réponses via vos invites système et en fournissant des <examples> dans vos prompts.

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 tout autre texte généré par l'assistant, et ne pas s'appuyer sur des conventions de formatage spécifiques.

Étapes suivantes