Gestión de errores y mecanismos de respaldo
En esta página
Gestión de errores y mecanismos de respaldo
La llamada a funciones introduce un desafío que el código clásico no enfrenta: cuando tu función falla, hay dos destinatarios para ese error. Tu aplicación, como es habitual, y el modelo, que está esperando un resultado para continuar. Olvidar esto crea el síntoma más desconcertante en producción: una conversación que se detiene en seco sin explicación, porque una excepción fue silenciada en el servidor y el modelo sigue esperando.
La regla que estructura toda esta lección es la siguiente: devuelve siempre un function_call_output, incluso en caso de fallo. Un modelo informado de que una API no está disponible puede proponer una alternativa, pedir aclaraciones o explicar la situación al usuario. Un modelo que no recibe nada no puede hacer nada.
Devolución de errores al modelo
El formato del error es tan importante como el hecho de enviarlo. Un simple «Error» no enseña nada al modelo; un objeto JSON que distinga el tipo de error, si es transitorio o permanente, y los siguientes pasos, permite que el modelo decida. Esto resulta contraintuitivo: estás escribiendo mensajes de error destinados a ser leídos por una máquina de razonamiento, no registrados para humanos.
import json
from openai import OpenAI
client = OpenAI()
def execute_function(name: str, arguments: str, call_id: str) -> dict:
try:
args = json.loads(arguments)
result = dispatcher[name](**args)
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
except KeyError:
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps({
"error": "unknown_function",
"message": f"La función '{name}' no existe"
})
}
except json.JSONDecodeError:
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps({
"error": "invalid_arguments",
"message": "Los argumentos JSON tienen un formato incorrecto"
})
}
except Exception as e:
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps({
"error": "internal_error",
"message": str(e)
})
}
Reintento con retroceso exponencial
El reintento solo tiene sentido para problemas que podrían resolverse en un segundo intento: cortes de red, códigos de estado 429 o interrupciones temporales. Reintentar una solicitud rechazada por autenticación inválida o parámetros incorrectos solo retrasa el fallo mientras multiplica las llamadas. Por eso el código de abajo filtra explícitamente los errores: el filtrado hace el trabajo, mientras que el retroceso es simplemente la cortesía que debes al servicio remoto.
import time
import random
def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
"""Reintento con retroceso exponencial y jitter."""
for attempt in range(max_retries + 1):
try:
return func(**args)
except (ConnectionError, TimeoutError) as e:
if attempt == max_retries:
raise
delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
time.sleep(delay)
except ValueError:
# Error de datos: no reintentar
raise
def execute_function_robust(name, arguments, call_id):
args = json.loads(arguments)
try:
result = execute_with_retry(dispatcher[name], args)
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
except Exception as e:
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps({
"error": type(e).__name__,
"message": str(e),
"retries_performed": 3
})
}
Tiempos de espera por función
Un único tiempo de espera para todas las funciones siempre estará mal configurado: si es demasiado corto, mata el procesamiento pesado; si es demasiado largo, hace que el usuario espere en una consulta de caché simple. Basa cada valor en las duraciones observadas en condiciones normales, con un margen, no en el peor caso imaginable, lo que efectivamente significaría no tener ningún tiempo de espera.
import signal
from functools import wraps
TIMEOUTS = {
"search_client": 5,
"generate_report": 30,
"send_email": 10,
}
def with_timeout(func, timeout_seconds):
"""Ejecuta una función con un tiempo de espera."""
import concurrent.futures
with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
future = executor.submit(func)
try:
return future.result(timeout=timeout_seconds)
except concurrent.futures.TimeoutError:
raise TimeoutError(
f"Función interrumpida tras {timeout_seconds}s"
)
def execute_with_timeout(name, arguments, call_id):
args = json.loads(arguments)
timeout = TIMEOUTS.get(name, 10) # 10s por defecto
try:
result = with_timeout(
lambda: dispatcher[name](**args),
timeout
)
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
except TimeoutError as e:
return {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps({
"error": "timeout",
"message": str(e),
"suggestion": "Reintentar con criterios más específicos"
})
}
Respaldo entre funciones
El mecanismo de respaldo es una compensación, no un reflejo: servir datos en caché de hace seis horas es mejor que nada para un panel de control, y mucho peor que nada para un saldo bancario. Cuando degradas el servicio, dilo explícitamente en el resultado devuelto al modelo, para que pueda advertir al usuario en lugar de presentar datos obsoletos como si fueran actuales.
async def search_product(term: str) -> dict:
"""Búsqueda con respaldo: API principal -> caché -> base de datos local."""
# Intento 1: API de catálogo
try:
return await api_catalog.search(term)
except Exception:
pass
# Intento 2: Caché Redis
try:
cached = await redis_client.get(f"product:{term}")
if cached:
result = json.loads(cached)
result["_source"] = "cache"
result["_warning"] = "Los datos pueden estar desactualizados"
return result
except Exception:
pass
# Intento 3: Base de datos local SQLite
try:
row = db.execute(
"SELECT * FROM products WHERE name LIKE ?",
(f"%{term}%",)
).fetchone()
if row:
return {
"name": row["name"],
"price": row["price"],
"_source": "local_db",
"_warning": "Datos de la última sincronización"
}
except Exception:
pass
return {
"error": "unavailable",
"message": "Ninguna fuente de datos accesible para esta búsqueda"
}
Interruptor de circuito (Circuit Breaker)
El interruptor de circuito gestiona lo que el reintento no puede: un servicio que lleva mucho tiempo caído. Tras N fallos, se dispara y devuelve un error inmediatamente, sin ni siquiera intentarlo, y luego permite ocasionalmente una solicitud de prueba para comprobar la recuperación. La ganancia es doble: tus usuarios dejan de esperar un tiempo de agotamiento en cada solicitud y el servicio que lucha no se mantiene caído por tus reintentos.
from datetime import datetime, timedelta
class CircuitBreaker:
def __init__(self, failure_threshold=5, open_duration=60):
self.threshold = failure_threshold
self.duration = open_duration
self.failures = 0
self.last_failure = None
self.state = "closed" # closed, open, half-open
def can_execute(self) -> bool:
if self.state == "closed":
return True
if self.state == "open":
if datetime.now() - self.last_failure > timedelta(seconds=self.duration):
self.state = "half-open"
return True
return False
return True # half-open: permitir un intento de prueba
def record_success(self):
self.failures = 0
self.state = "closed"
def record_failure(self):
self.failures += 1
self.last_failure = datetime.now()
if self.failures >= self.threshold:
self.state = "open"
# Un interruptor de circuito por servicio externo
breakers = {
"weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
"catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}
Bucle robusto completo
El patrón completo reúne los cinco mecanismos anteriores. Una precaución lo hace realmente seguro y es fácil de pasar por alto: limita el número de iteraciones. Es raro que un modelo entre en bucle llamando a una función cuyo resultado no le gusta, pero sin un techo agotará tu presupuesto hasta el límite, y ese es el tipo de incidente que descubres en la factura.
def robust_loop(prompt, tools, max_turns=10):
messages = prompt
for turn in range(max_turns):
response = client.responses.create(
model="gpt-5.6-terra",
input=messages,
tools=tools
)
calls = [i for i in response.output if i.type == "function_call"]
if not calls:
return response.output_text
results = []
for call in calls:
result = execute_function_robust(
call.name, call.arguments, call.call_id
)
results.append(result)
messages = response.output + results
return "Flujo de trabajo interrumpido: se alcanzó el límite de turnos"
Puntos clave
- Devuelve siempre un
function_call_output, incluso en caso de error - Estructura los errores como JSON para que el modelo pueda utilizarlos
- Reintenta solo errores transitorios con retroceso exponencial
- Implementa mecanismos de respaldo entre fuentes de datos
- Utiliza un interruptor de circuito para proteger los servicios que fallan