Cargando

Esquemas de herramientas

Lección 247 min
Cargando

Después de escribir la función de tu herramienta, el siguiente paso es crear un esquema JSON que le indique a Claude qué argumentos espera tu función y cómo usarla. Este esquema actúa como documentación que Claude lee para entender cuándo y cómo llamar a tus herramientas.

Entendiendo JSON Schema

JSON Schema no es específico de la IA o la llamada a herramientas: es una especificación de validación de datos ampliamente utilizada que existe desde hace años. La comunidad de IA la adoptó porque es una forma conveniente de describir los parámetros de una función y validar datos.

Esquema JSON para una herramienta get_weather: input_schema es un objeto con una propiedad string requerida "location".

La especificación completa de la herramienta tiene tres partes principales:

  • name - El nombre de la función (como "get_weather")
  • description - Qué hace la herramienta y cuándo usarla
  • input_schema - El esquema JSON real que describe los argumentos

Escribiendo descripciones efectivas

Esquema anotado de la herramienta get_weather con name, description y un input_schema que describe una cadena location requerida.

El campo description es crucial para ayudar a Claude a entender tu herramienta. Sigue estas mejores prácticas:

  • Explica qué hace la herramienta, cuándo usarla y qué devuelve
  • Apunta a 3-4 oraciones
  • Proporciona descripciones detalladas también para cada argumento

La sección input_schema describe los parámetros de tu función usando el formato estándar de JSON Schema, incluyendo información de tipo y descripciones detalladas para cada argumento.

La forma fácil: deja que Claude escriba tu esquema

En lugar de escribir esquemas JSON desde cero, puedes usar a Claude mismo para generarlos. Aquí está el proceso:

  1. Copia la función de tu herramienta
  2. Ve a Claude y pídele que escriba un esquema JSON para la llamada a herramientas
  3. Incluye como contexto la documentación de Anthropic sobre uso de herramientas
  4. Deja que Claude genere un esquema con el formato adecuado siguiendo las mejores prácticas

Nuevo chat de Claude.ai con la indicación y la función get_current_datetime en el cuadro de mensaje, y una pestaña de documentación de uso de herramientas.

La indicación debería ser algo como: "Escribe una especificación de esquema JSON válida para fines de llamada a herramientas para esta función. Sigue las mejores prácticas enumeradas en la documentación adjunta."

Implementando el esquema en código

Una vez que Claude genera tu esquema, cópialo en tu archivo de código. Usa un patrón de nomenclatura consistente como function_name_schema para mantener las cosas organizadas:

python
get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

Agregando seguridad de tipos

Para una mejor verificación de tipos, importa y usa el tipo ToolParam de la biblioteca de Anthropic:

python
from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    # tu diccionario de esquema aquí
})

Esto no es estrictamente necesario para la funcionalidad, pero evita errores de tipo cuando uses el esquema más adelante en tu código.

La combinación de una función de herramienta bien escrita y un esquema JSON detallado le da a Claude todo lo que necesita para entender y usar correctamente tus herramientas en las conversaciones.