Gestión de errores
En esta página
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.