Chargement

Schéma JSON pour les outils

Leçon 235 min
Chargement

Après avoir créé votre fonction d'outil, l'étape suivante consiste à écrire un schéma JSON pour la décrire. Ce schéma indique à Claude quels arguments votre fonction attend et comment l'utiliser correctement. Bien que la configuration puisse sembler intimidante au premier abord, elle est en réalité simple une fois que vous avez compris le processus.

Comprendre le schéma JSON

Le schéma JSON n'est pas quelque chose inventé uniquement pour les outils d'IA - il existe depuis des années en tant que norme pour valider des données. Le schéma comporte deux parties principales : le nom et la description en haut (qui aident Claude à comprendre quand utiliser l'outil), et le schéma proprement dit qui décrit les arguments de la fonction.

Un toolSpec get_weather avec son nom et sa description encadrés en haut et un inputSchema exigeant "location" encadré en dessous.

La section supérieure contient le nom et la description de l'outil, ce qui aide Claude à comprendre quand l'utiliser. La section inférieure est le schéma proprement dit qui décrit en détail les arguments de votre fonction.

Créer un schéma JSON : étape par étape

Voici la façon la plus simple de créer un schéma JSON pour n'importe quelle fonction :

Étape 1 : Rédiger un dictionnaire avec des données d'exemple

Prenez votre fonction et créez un dictionnaire de tous les arguments nommés avec des données d'exemple. Par exemple, si vous avez une fonction comme celle-ci :

python
def process_data(ids, profile, primary_id, value):
    pass

Créez un dictionnaire avec des valeurs d'exemple :

Dictionnaire pour process_data : "ids" est une liste contenant 1, "profile" a "active" à True, "primary_id" vaut "abc", "value" vaut 20.

Étape 2 : Convertir en JSON

Convertissez votre dictionnaire Python au format JSON approprié. La principale différence est le remplacement du True de Python par le true de JSON.

Le dictionnaire de l'étape 1 en JSON, avec les mêmes valeurs ids 1, primary_id "abc" et value 20, sauf que "active" est maintenant en minuscules, true.

Étape 3 : Utiliser un convertisseur en ligne

Recherchez "JSON to JSON Schema converter" et utilisez l'un des nombreux outils gratuits en ligne. Collez vos données JSON et laissez-le générer le schéma automatiquement.

Convertisseur JSON vers schéma JSON en ligne : l'exemple JSON collé, un bouton Generate Schema, et le schéma déduit en dessous.

L'outil analysera vos données d'exemple et créera une structure de schéma appropriée. Supprimez toute déclaration $schema du résultat - vous n'en avez pas besoin.

Étape 4 : Ajouter des descriptions

L'étape la plus importante consiste à ajouter des descriptions détaillées à chaque propriété. Ces descriptions aident Claude à comprendre exactement ce que fait chaque argument et comment l'utiliser.

Schéma JSON où le tableau de nombres ids et la chaîne primary_id reçoivent chacun une clé "description" définie sur trois points.

Rédiger de bonnes descriptions

Lorsque vous rédigez des descriptions pour vos outils et propriétés, suivez ces bonnes pratiques :

  • Expliquez ce que fait l'outil, quand l'utiliser et ce qu'il renvoie
  • Visez 3 à 4 phrases pour la description de votre outil
  • Fournissez des descriptions très détaillées pour chaque propriété
  • Si vous êtes bloqué, collez votre fonction dans Claude et demandez-lui de rédiger les descriptions pour vous

Voici un exemple de schéma d'outil bien décrit :

Schéma JSON pour get_weather, renvoyant temperature, conditions et humidity, avec un "location" obligatoire tel que "London,UK".

Remarquez comment la description explique clairement ce que fait l'outil météo, quand l'utiliser, quelles données il renvoie, et fournit des exemples précis de formats de localisation valides.

Assembler le tout

Votre schéma JSON final devrait ressembler à cette structure, avec le toolSpec contenant le nom, la description, et inputSchema avec les spécifications détaillées des arguments :

Le schéma toolSpec de get_weather : name, une description de plusieurs phrases, et inputSchema avec une chaîne location obligatoire.

Le schéma agit comme un contrat entre votre code et Claude, garantissant que lorsque Claude décide d'utiliser votre outil, il sait exactement quelles informations fournir et dans quel format. Cette communication claire est ce qui rend l'utilisation d'outils fiable et efficace.