Définir les outils

Choisir un modèle

Utilisez le dernier modèle Claude Opus (4.7) pour les outils complexes et les requêtes ambiguës ; il gère mieux plusieurs outils et demande 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 (schéma 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 inclut :

Pour l'ensemble complet des propriétés optionnelles disponibles sur toute définition d'outil, y compris cache_control, strict, defer_loading et allowed_callers, consultez la référence des outils.

Invite système d'utilisation d'outils

Lorsque vous appelez l'API Claude avec le paramètre tools, l'API construit 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 le(s) outil(s) 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 :

• 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 de 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.
• Priorisez les descriptions, mais envisagez d'utiliser input_examples pour les outils complexes. Les descriptions claires sont les plus importantes, 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. Voir Fournir des exemples d'utilisation d'outils pour plus de détails.
• Plutôt que de créer un outil séparé pour chaque action (, , ), regroupez-les dans un seul outil avec un paramètre . Moins d'outils, plus capables, réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à naviguer pour Claude.

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

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 optionnels ou des entrées sensibles au format.

Utilisation de base

Ajoutez un champ optionnel 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 :

Les exemples sont inclus dans l'invite aux côtés de votre schéma d'outil, montrant à Claude des modèles concrets pour des appels d'outils bien formés. Cela aide Claude à comprendre quand inclure les paramètres optionnels, quels formats utiliser et comment structurer les 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 retournent une erreur 400
• Non pris en charge pour les outils côté serveur - Les exemples d'entrée fonctionnent sur les outils clients définis par l'utilisateur et schéma Anthropic, mais pas sur les outils serveur comme la recherche Web ou l'exécution de code
• Coût en jetons - Les exemples s'ajoutent aux jetons d'invite : ~20-50 jetons pour les exemples simples, ~100-200 jetons pour les objets imbriqués complexes

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 répondrait autrement directement sans appeler un 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, il y a 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 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 comment chaque option fonctionne :

Notez que lorsque vous avez tool_choice comme any ou tool, l'API préremplissage 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.

Les 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 : 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 commentera souvent ce qu'il fait ou répondra naturellement à l'utilisateur avant d'invoquer des outils.

Par exemple, étant donné l'invite « What's the weather like in San Francisco right now, and what time is it there? », 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 dépendre de conventions de formatage spécifiques.

Étapes suivantes