Cargando

JSON Schema para herramientas

Lección 235 min
Cargando

Después de crear tu función de herramienta, el siguiente paso es escribir un JSON schema para describirla. Este esquema le indica a Claude qué argumentos espera tu función y cómo usarla correctamente. Aunque la configuración pueda parecer intimidante al principio, en realidad es sencilla una vez que entiendes el proceso.

Comprendiendo JSON Schema

JSON Schema no es algo inventado solo para herramientas de IA: existe desde hace años como una forma estándar de validar datos. El esquema tiene dos partes principales: el nombre y la descripción en la parte superior (que ayudan a Claude a entender cuándo usar la herramienta), y el esquema propiamente dicho que describe los argumentos de la función.

Un toolSpec de get_weather con su nombre y descripción recuadrados en la parte superior y un inputSchema que requiere "location" recuadrado debajo.

La sección superior contiene el nombre y la descripción de la herramienta, lo cual ayuda a Claude a entender cuándo usarla. La sección inferior es el esquema propiamente dicho que describe en detalle los argumentos de tu función.

Creando un JSON Schema: Paso a Paso

Aquí tienes la forma más sencilla de crear un JSON schema para cualquier función:

Paso 1: Escribe un Diccionario con Datos de Ejemplo

Toma tu función y crea un diccionario con todos los argumentos de palabra clave con datos de ejemplo. Por ejemplo, si tienes una función como esta:

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

Crea un diccionario con valores de ejemplo:

Diccionario para process_data: "ids" es una lista con 1, "profile" tiene "active" en True, "primary_id" es "abc", "value" es 20.

Paso 2: Convierte a JSON

Convierte tu diccionario de Python al formato JSON adecuado. La diferencia principal es cambiar True de Python por true de JSON.

El diccionario del paso 1 como JSON, con los mismos valores con ids 1, primary_id "abc" y value 20, excepto que "active" ahora está en minúsculas como true.

Paso 3: Usa un Conversor en Línea

Busca "JSON to JSON Schema converter" y usa una de las muchas herramientas gratuitas en línea. Pega tus datos JSON y deja que genere el esquema automáticamente.

Conversor en línea de JSON a JSON Schema: el JSON de ejemplo pegado, un botón Generate Schema y el esquema inferido debajo.

La herramienta analizará tus datos de ejemplo y creará una estructura de esquema adecuada. Elimina cualquier declaración $schema del resultado: no las necesitas.

Paso 4: Agrega Descripciones

El paso más importante es agregar descripciones detalladas a cada propiedad. Estas descripciones ayudan a Claude a entender exactamente qué hace cada argumento y cómo usarlo.

Esquema JSON donde el array de números ids y la cadena primary_id reciben cada uno una clave "description" con tres puntos.

Escribiendo Buenas Descripciones

Al escribir descripciones para tus herramientas y propiedades, sigue estas mejores prácticas:

  • Explica qué hace la herramienta, cuándo usarla y qué devuelve
  • Apunta a 3-4 oraciones en la descripción de tu herramienta
  • Proporciona descripciones súper detalladas para cada propiedad
  • Si estás atascado, pega tu función en Claude y pídele que escriba las descripciones por ti

Aquí tienes un ejemplo de un esquema de herramienta bien descrito:

JSON Schema para get_weather, que devuelve temperature, conditions y humidity, con un "location" requerido como "London,UK".

Observa cómo la descripción explica claramente qué hace la herramienta de clima, cuándo usarla, qué datos devuelve, y proporciona ejemplos específicos de formatos de ubicación válidos.

Uniendo Todo

Tu JSON schema final debería lucir algo como esta estructura, con el toolSpec conteniendo el nombre, la descripción, y el inputSchema con las especificaciones detalladas de los argumentos:

El esquema toolSpec de get_weather: name, una descripción de varias frases, e inputSchema con un string location requerido.

El esquema actúa como un contrato entre tu código y Claude, asegurando que cuando Claude decida usar tu herramienta, sepa exactamente qué información proporcionar y en qué formato. Esta comunicación clara es lo que hace que el uso de herramientas sea confiable y efectivo.