Ir al contenido principal
Español— Elegir un idioma
Menú

Definir funciones con JSON Schema

Lección 3 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. El contrato entre tu código y el modelo
  2. Anatomía de una especificación de herramienta
  3. Tipos de JSON Schema compatibles
  4. Ejemplo completo: dos funciones complementarias
  5. Parámetros obligatorios frente a opcionales
  6. Buenas prácticas para las descripciones
  7. Puntos clave

El contrato entre tu código y el modelo

Para que el modelo Mistral pueda llamar a tus funciones, necesita saber qué existen y cómo utilizarlas. Esta es la función del JSON Schema: un formato estandarizado que describe cada función —su nombre, qué hace, qué parámetros espera y cuáles son obligatorios—.

Ten presente una cosa durante toda esta lección: el modelo nunca ve tu código Python. Solo ve esta especificación. Si tu función gestiona IDs en minúsculas sin problemas pero el esquema no lo indica, el modelo ignorará esa capacidad. Cuanto más preciso y documentado esté tu esquema, más exactos serán los argumentos generados.

Anatomía de una especificación de herramienta

Cada herramienta enviada a la API de Mistral sigue la misma estructura:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Descripción clara de lo que hace la función",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Descripción del parámetro"
                },
                "param2": {
                    "type": "integer",
                    "description": "Descripción del parámetro"
                }
            },
            "required": ["param1"]
        }
    }
}
CampoFunción
typeSiempre "function" (pueden existir otros tipos en el futuro)
function.nameEl nombre exacto de tu función Python; esto es lo que el modelo devuelve en tool_calls
function.descriptionUna frase clara que ayuda al modelo a elegir la función correcta
function.parametersUn objeto JSON Schema que describe los parámetros esperados
requiredLa lista de parámetros obligatorios

Tipos de JSON Schema compatibles

El vocabulario de tipos disponible para describir parámetros está restringido a propósito, y cada tipo guía al modelo de forma distinta. Un enum, en particular, hace algo más que documentar: cierra la puerta a valores inventados.

# String — texto libre o restringido
{"type": "string", "description": "ID de transacción"}

# String con enum — valores limitados
{"type": "string", "enum": ["asc", "desc"], "description": "Orden de clasificación"}

# Integer — número entero
{"type": "integer", "description": "Número de resultados a devolver"}

# Number — número decimal
{"type": "number", "description": "Importe en euros"}

# Boolean — verdadero/falso
{"type": "boolean", "description": "Incluir transacciones canceladas"}

# Array — lista de valores
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Lista de IDs de transacción"
}

# Object — objeto anidado
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Dirección de envío"
}

Distingue claramente entre integer y number: un importe en euros como 125,50 requiere un number, mientras que un recuento de resultados a devolver es un integer. Declarar un importe como integer hará que el modelo lo redondee.

Ejemplo completo: dos funciones complementarias

Aquí tienes un ejemplo realista con dos funciones relacionadas con pagos, inspirado en la documentación oficial de Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Recupera el estado de un pago (paid, pending, failed) "
                           "basándose en el ID de transacción.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "El ID de transacción único (p. ej., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Recupera la fecha en que se realizó un pago "
                           "basándose en el ID de transacción.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "El ID de transacción único (p. ej., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Ambas funciones esperan exactamente el mismo parámetro, transaction_id, pero el modelo debe elegir entre ellas. Esta elección depende enteramente de la descripción de la función. «¿Se ha completado este pago?» se asigna a retrieve_payment_status; «¿Cuándo fue?» se asigna a retrieve_payment_date. Si hubieras escrito dos descripciones vagas e intercambiables, el modelo fallaría la mitad de las veces, y culparías al modelo cuando la culpa reside en el esquema.

Parámetros obligatorios frente a opcionales

La distinción entre parámetros obligatorios y opcionales determina qué puede omitir el modelo.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Busca transacciones basándose en varios criterios",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filtrar por estado del pago"
                },
                "date_from": {
                    "type": "string",
                    "description": "Fecha de inicio en formato AAAA-MM-DD"
                },
                "date_to": {
                    "type": "string",
                    "description": "Fecha de fin en formato AAAA-MM-DD"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Importe mínimo en euros"
                }
            },
            "required": ["status"]
        }
    }
}

Aquí, solo status es obligatorio; los demás parámetros se incluyen únicamente si el usuario los menciona. Compara dos formulaciones. Para «Muéstrame los pagos fallidos», el modelo genera simplemente {"status": "failed"}. Para «Muéstrame los pagos fallidos desde marzo de 2026», añade date_from y date_to por su cuenta. Hacer obligatorias esas fechas habría roto la primera consulta o, peor aún, habría empujado al modelo a inventar un rango de fechas.

Buenas prácticas para las descripciones

La calidad de la descripción impacta directamente en la precisión del modelo. Los contraejemplos siguientes son más instructivos que cualquier regla abstracta.

# Malo — demasiado vago
{"description": "Recupera datos"}

# Bueno — preciso y contextual
{"description": "Recupera el estado de un pago (paid, pending, failed) "
                "basándose en el ID de transacción único"}

# Malo — sin descripción para el parámetro
{"transaction_id": {"type": "string"}}

# Bueno — descripción con ejemplo
{"transaction_id": {
    "type": "string",
    "description": "ID de transacción único (formato: T seguido de 4 dígitos, p. ej., T1001)"
}}

Una buena descripción indica en una frase qué hace la función, especifica el formato esperado para cada parámetro y proporciona un ejemplo siempre que ese formato no sea obvio —T1001 es mejor que «ID de transacción»—. Cuando los valores posibles son limitados, no los describas en prosa: decláralos con enum. Es la única manera de hacerlos vinculantes.

Puntos clave

  • JSON Schema es el contrato entre tu código y el modelo: describe tus funciones sin exponer el código
  • Cada herramienta tiene un name, una description y parameters tipados
  • Los tipos compatibles incluyen string, integer, number, boolean, array y object
  • La lista required distingue los parámetros obligatorios de los opcionales
  • Las descripciones precisas con ejemplos mejoran significativamente la precisión del modelo