Manejo de errores y flujos de fallback

Concepto clave

En el desarrollo de agentes de IA con LangGraph, el manejo de errores y flujos de fallback no es solo una característica opcional, sino el sistema nervioso que permite a tu agente adaptarse a un mundo imperfecto. Piensa en un conductor experto: no solo sabe seguir la ruta ideal, sino que tambien anticipa desvíos, fallos mecánicos o condiciones climáticas adversas, teniendo siempre un plan B, C y D listo para ejecutar.

En LangGraph, esto se traduce en diseñar grafos que no se rompan ante errores de herramientas, respuestas inesperadas de modelos de lenguaje, o estados de memoria corruptos. Un flujo de fallback efectivo actúa como un paracaídas de contingencia: cuando una rama del grafo falla, el sistema redirige el flujo hacia una ruta alternativa que puede recuperar, registrar o reiniciar la operación sin perder el contexto completo.

"Un agente sin manejo de errores es como un barco sin botes salvavidas: puede navegar en aguas tranquilas, pero un solo fallo lo hunde."

Cómo funciona en la práctica

Imagina que estás construyendo un agente que analiza informes financieros usando herramientas de búsqueda en bases de datos y APIs externas. El grafo básico podría verse así:

1. Recibir consulta del usuario
2. Buscar en memoria histórica
3. Ejecutar herramienta de búsqueda en base de datos
4. Procesar resultados con LLM
5. Generar respuesta

Ahora, añadimos manejo de errores:

from langgraph.graph import StateGraph, END
from typing import TypedDict

class AgentState(TypedDict):
    query: str
    memory: list
    tool_results: dict
    error: str
    fallback_activated: bool

def tool_execution(state):
    try:
        # Lógica de herramienta
        result = call_external_api(state['query'])
        return {'tool_results': result, 'error': None}
    except Exception as e:
        return {'tool_results': None, 'error': str(e), 'fallback_activated': True}

def fallback_strategy(state):
    if state['error']:
        # 1. Registrar error en memoria
        # 2. Usar datos cacheados
        # 3. Reformular consulta
        return {'response': 'Usando datos alternativos...', 'fallback_activated': False}
    return {'response': state['tool_results']}

workflow = StateGraph(AgentState)
workflow.add_node('tool_execution', tool_execution)
workflow.add_node('fallback', fallback_strategy)
workflow.add_conditional_edges(
    'tool_execution',
    lambda state: 'fallback' if state['error'] else END,
    {'fallback': 'fallback', END: END}
)
workflow.set_entry_point('tool_execution')

Este diseño permite que cuando la API falle, el grafo automáticamente redirija a una estrategia de fallback que puede usar datos cacheados o reformular la consulta.

Caso de estudio

Vamos a examinar un agente de soporte técnico para una plataforma SaaS. Este agente usa:

• Memoria: Historial de tickets del usuario
• Herramientas: Base de conocimiento, API de monitoreo, sistema de tickets
• Lógica condicional: Decide qué herramienta usar basado en la urgencia

Implementamos un sistema de fallback de tres niveles:

La implementación en LangGraph incluye nodos condicionales que evalúan códigos de error y redirigen el flujo hacia el nivel apropiado de fallback, manteniendo siempre una respuesta al usuario dentro de los límites de SLA.

Errores comunes

1. Fallback infinito: Crear ciclos donde el fallback llama a otra función que también falla. Solución: Implementar contadores de intentos y límites máximos de recursión.
2. Pérdida de contexto: Al activar fallback, no preservar la información útil ya obtenida. Solución: Diseñar estados que retengan datos parciales y metadatos de error.
3. Silenciar errores críticos: Usar try-catch demasiado amplio que oculta problemas de infraestructura. Solución: Diferenciar entre errores recuperables (timeouts) y no recuperables (autenticación).
4. Fallback demasiado genérico: Respuestas como "Ha ocurrido un error" sin valor para el usuario. Solución: Personalizar mensajes de fallback con información específica del contexto.
5. No probar caminos de fallback: Asumir que funcionarán sin pruebas reales. Solución: Implementar pruebas que simulen fallos de cada herramienta y validen los flujos alternativos.

Checklist de dominio

• ¿Tu grafo maneja al menos tres tipos diferentes de errores (herramientas, LLM, memoria)?
• ¿Los flujos de fallback mantienen coherencia con el estado anterior del agente?
• ¿Has implementado límites de reintentos para evitar loops infinitos?
• ¿Los mensajes de error son informativos para debugging pero seguros para usuarios finales?
• ¿Has probado cada camino de fallback con datos realistas de error?
• ¿El sistema registra métricas de activación de fallback para monitoreo?
• ¿Existe una ruta de escalación final cuando todos los fallbacks fallan?

Implementación de un sistema de fallback multi-nivel para agente de reservas

Construye un agente de reservas de vuelos con LangGraph que implemente un sistema de fallback de tres niveles. Sigue estos pasos:

1. Define el estado del agente: Crea una clase TypedDict que incluya: query_usuario, resultados_busqueda, error_actual, nivel_fallback_activado, intentos_realizados.
2. Implementa tres herramientas simuladas:
   • busqueda_vuelos_directos(): Simula búsqueda en API principal (falla 30% del tiempo)
   • busqueda_vuelos_alternativos(): Simula búsqueda en API secundaria
   • busqueda_historico(): Usa datos cacheados de últimas 24h
3. Diseña el grafo con nodos condicionales:
   • Nodo principal intenta busqueda_vuelos_directos
   • Si falla (error o timeout), activa nivel 1: busqueda_vuelos_alternativos
   • Si nivel 1 falla, activa nivel 2: busqueda_historico
   • Si nivel 2 falla, nivel 3: respuesta predefinida + escalar a humano
4. Añade mecanismos de seguridad:
   • Límite de 2 intentos por nivel
   • Registro de errores en memoria del agente
   • Tiempo máximo de 10 segundos por búsqueda
5. Prueba con casos específicos:
   • Simula fallo en API principal pero éxito en secundaria
   • Simula fallo en ambas APIs pero éxito en histórico
   • Simula fallo total y verifica escalación correcta

Entrega el código completo del grafo y muestra cómo maneja al menos dos escenarios de error diferentes.

• Usa decoradores @retry para implementar límites de reintentos de forma limpia
• Considera usar un enum para los niveles de fallback en lugar de strings
• No olvides que el estado debe preservar información entre niveles de fallback

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.