Cargando
Cargando

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 comprender cuándo y cómo llamar a tus herramientas.

Entendiendo JSON Schema

JSON Schema no es específico de la IA ni de 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 parámetros de funciones y validar datos.

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

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

Cómo escribir 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 debe usarla
  • Explica qué tipo de datos devuelve
  • Proporciona descripciones detalladas para cada argumento

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

La forma fácil de generar esquemas

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

  1. Copia el código de 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

El prompt 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 listadas en la documentación adjunta."

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

Implementando el esquema en el código

Una vez que Claude genere tu esquema, cópialo en tu archivo de código. Aquí tienes 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.