Claude Academy
Cargando

Esquemas de herramientas

Lección 237 min

Después de escribir tu función de 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 ni del uso de 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 parámetros de funciones y validar datos.

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

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

Escribiendo descripciones efectivas

La descripción de tu herramienta es crucial para ayudar a Claude a entender cuándo usar tu función. Las mejores prácticas incluyen:

  • Apunta a 3-4 oraciones que expliquen qué hace la herramienta
  • Describe cuándo Claude debería usarla
  • Explica qué tipo de datos devuelve
  • Proporciona descripciones detalladas para cada argumento

La forma fácil de generar esquemas

En lugar de escribir esquemas JSON desde cero, puedes usar a Claude mismo para generarlos. Este es el proceso:

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

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

Implementando el esquema en el código

Una vez que Claude genera tu esquema, cópialo en tu archivo de código. Aquí hay un buen patrón de nomenclatura a seguir:

python
def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

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": []
    }
}

Usa el patrón de function_name seguido de function_name_schema para mantener tus esquemas organizados y fáciles de relacionar con sus funciones correspondientes.

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({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    # ... resto del esquema
})

Aunque no es estrictamente necesario para la funcionalidad, esto evita errores de tipo cuando usas el esquema con la API de Claude y hace que tu código sea más robusto.