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

Gestión de errores

Lección 10 de 14 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Los errores son inevitables
  2. Nunca ocultes un error al modelo
  3. Un ejecutor que no deja pasar nada
  4. Distingue entre fallos transitorios y permanentes
  5. La API de Mistral también puede fallar
  6. Observa qué está ocurriendo realmente
  7. Puntos clave

Los errores son inevitables

En producción, las funciones fallan. Las API externas se caen, los IDs no existen, los parámetros son inválidos y se agotan los tiempos de espera. La pregunta no es «¿fallará?», sino «¿cómo gestionamos el fallo con elegancia?». Un rastreador de pagos que se bloquea porque un usuario ha escrito T9999 en lugar de T1001 no es un sistema de producción; es una demo.

La buena noticia es que cuentas con un recurso del que carecen las arquitecturas clásicas: el modelo Mistral puede entender los mensajes de error que le devuelves y adaptar su respuesta en consecuencia. Mientras que un backend tradicional debe redactar un mensaje de interfaz para cada código de error, tú puedes dejar que el modelo traduzca el fallo en una frase útil para el usuario. Solo tienes que proporcionarle la información.

Nunca ocultes un error al modelo

Esta es la regla de oro de esta lección. Devuelve un error en el mensaje tool exactamente igual que harías con un resultado normal: como JSON estructurado. El reflejo contrario —capturar la excepción y devolver una cadena vacía o null— hace que el modelo crea que la función se ha ejecutado correctamente pero que simplemente no tenía nada que decir. Esto genera las respuestas más confusas posibles.

def retrieve_payment_status(df, transaction_id: str) -> str:
    """Recupera el estado con gestión completa de errores."""
    try:
        if transaction_id not in df["transaction_id"].values:
            return json.dumps({
                "error": "transaction_not_found",
                "message": f"La transacción {transaction_id} no existe en la base de datos."
            })

        status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
        return json.dumps({"status": status, "transaction_id": transaction_id})

    except Exception as e:
        return json.dumps({
            "error": "internal_error",
            "message": f"Error al recuperar los datos: {str(e)}"
        })

Dos campos son suficientes: un código máquina en error y una explicación legible para humanos en message. El código permite que tu sistema de monitorización cuente las ocurrencias; la explicación permite que el modelo formule una respuesta útil. Observa qué ocurre con una transacción inexistente.

# El usuario solicita una transacción inexistente
messages = [{"role": "user", "content": "¿Estado del pago T9999?"}]

# El modelo llama a retrieve_payment_status(transaction_id="T9999")
# Tu función devuelve: {"error": "transaction_not_found", ...}

# El modelo formula:
# → "No he podido encontrar una transacción con el ID T9999.
#     ¿Podrías verificar el número e intentarlo de nuevo?"

Nadie ha escrito esa frase. Surge del código de error e incluso sugiere una acción correctiva al usuario.

Un ejecutor que no deja pasar nada

Proteger una función no es suficiente: la capa que despacha las tool_calls tiene sus propios modos de fallo, independientes de tu lógica de negocio. El modelo podría alucinar un nombre de función que no existe en tu diccionario. Podría generar argumentos JSON malformados —un caso raro pero real con esquemas complejos—. También podría proporcionar un JSON válido cuyas claves no coincidan con la firma de Python, provocando un TypeError durante **function_params. Cada uno de estos tres casos merece su propio código de error, ya que cada uno requiere una solución diferente por tu parte.

def execute_tool_call(tool_call, available_functions):
    """Ejecuta una tool_call con gestión completa de errores."""
    function_name = tool_call.function.name

    # Comprobar si la función existe
    if function_name not in available_functions:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "function_not_found",
                "message": f"La función {function_name} no está disponible."
            }),
            "tool_call_id": tool_call.id
        }

    # Analizar argumentos
    try:
        function_params = json.loads(tool_call.function.arguments)
    except json.JSONDecodeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_arguments",
                "message": f"Argumentos JSON inválidos: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

    # Ejecutar función
    try:
        result = available_functions[function_name](**function_params)
        return {
            "role": "tool",
            "name": function_name,
            "content": result,
            "tool_call_id": tool_call.id
        }
    except TypeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_params",
                "message": f"Parámetros incompatibles: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }
    except Exception as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "execution_error",
                "message": f"Error de ejecución: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

Observa que cada rama, incluidas las de fallo, devuelve un mensaje tool completo con su tool_call_id. Esto es esencial: la API rechaza un historial donde una tool_call queda sin respuesta, y un fallo silencioso provocaría un error de validación en el siguiente turno, lejos de la causa real.

Distingue entre fallos transitorios y permanentes

No todos los errores son iguales. Una transacción faltante seguirá faltando en el segundo intento; reintentarlo solo supone una pérdida de tiempo. Sin embargo, un tiempo de espera de red o un servicio momentáneamente saturado suelen resolverse por sí solos. Para esta segunda categoría, un reintento con retroceso exponencial —un segundo, luego dos, luego cuatro— da tiempo al servicio para recuperarse sin saturarlo con peticiones. Tras agotar los intentos, vuelves al comportamiento habitual: un JSON de error destinado al modelo.

import time

def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
    """Ejecuta una función con reintento exponencial."""
    for attempt in range(max_retries):
        try:
            result = func(**params)
            return result
        except ConnectionError as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt)
                time.sleep(delay)
            else:
                return json.dumps({
                    "error": "service_unavailable",
                    "message": f"Servicio no disponible tras {max_retries} intentos.",
                    "details": str(e)
                })

La API de Mistral también puede fallar

Todo lo anterior concierne a tus funciones. La llamada a la propia API de Mistral es un punto de fallo distinto que se gestiona por separado: aquí no hay ningún modelo al que explicarle el problema, ya que el modelo es precisamente lo inaccesible. Un HTTPValidationError suele indicar un error en la estructura de tus mensajes o herramientas, que debes corregir en el código; otras excepciones se relacionan con la red o el servicio y se gestionan con la misma lógica de reintento vista anteriormente.

from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError

def safe_chat_complete(client, model, messages, tools):
    """Llamada a la API de Mistral con gestión de errores."""
    try:
        return client.chat.complete(
            model=model,
            messages=messages,
            tools=tools
        )
    except HTTPValidationError as e:
        print(f"Error de validación: {e}")
        return None
    except Exception as e:
        print(f"Error de API: {e}")
        return None

Observa qué está ocurriendo realmente

Un sistema de llamada a funciones es difícil de depurar a posteriori si no sabes qué función se ha llamado, con qué argumentos y qué ha devuelto. El registro (logging) no es un lujo; es la forma en que descubrirás que una descripción ambigua empuja al modelo a confundir dos funciones, o que uno de cada cinco usuarios desencadena sistemáticamente un transaction_not_found. Registra la llamada antes de la ejecución y luego el veredicto, diferenciando el nivel info del nivel error para que tus alertas puedan filtrar eficazmente.

import logging

logger = logging.getLogger("function_calling")

def execute_and_log(tool_call, available_functions):
    """Ejecuta y registra el resultado."""
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    logger.info(f"Llamada: {function_name}({function_params})")

    result = execute_tool_call(tool_call, available_functions)
    content = json.loads(result["content"])

    if "error" in content:
        logger.error(f"Fallo en {function_name}: {content['error']} - {content['message']}")
    else:
        logger.info(f"Éxito en {function_name}: {content}")

    return result

Puntos clave

  • Devuelve siempre los errores al modelo en el mensaje tool; sabe cómo interpretarlos.
  • Utiliza códigos de error estructurados (transaction_not_found, invalid_arguments, etc.).
  • Implementa reintentos con retroceso para errores transitorios.
  • Gestiona por separado los errores en tus funciones y los errores en la API de Mistral.
  • Registra cada llamada y cada error para la monitorización en producción.