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

Gestión de errores y mecanismos de respaldo

Lección 4 de 20 Desarrollador
En esta página
  1. Gestión de errores y mecanismos de respaldo
  2. Devolución de errores al modelo
  3. Reintento con retroceso exponencial
  4. Tiempos de espera por función
  5. Respaldo entre funciones
  6. Interruptor de circuito (Circuit Breaker)
  7. Bucle robusto completo
  8. Puntos clave

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