Error Handling Estructurado: JARVIS y el Arte de Fallar Bien
Por qué el error handling es parte del contrato de la herramienta, los 3 tipos de errores en tool use, cómo devolver errores accionables, y los 4 patrones de retry y fallback.
ERROR 500 vs. JARVIS
Batalla de Nueva York. El suit de Iron Man toma daño. El sistema de repulsores falla.
Opción A: la pantalla de Tony dice 'ERROR 500'. Nada más.
Opción B: JARVIS dice — 'Repulsor array offline. Causa: sobrecalentamiento en sector 4. Sistemas activos: thrusters de emergencia, escudo de energía. Capacidad de vuelo al 43%. Recomendación: cambiar a modo de combate terrestre.'
Con la opción A, Tony no sabe qué pasó ni qué puede hacer. La misión termina ahí.
Con la opción B, Tony tiene toda la información que necesita para adaptar su estrategia. La misión continúa.
Error handling no es un detalle de implementación. Es parte del contrato de la herramienta. Y en producción — donde todo falla eventualmente — es lo que determina si el agente se recupera o crashea.
El error es parte del contrato de la herramienta
Cuando diseñás una herramienta — volvemos a M2V1 — pensás en nombre, description, input_schema y return value. La mayoría piensa en el return value como 'el resultado exitoso'. Pero el return value tiene dos casos: éxito y error. Y el agente necesita saber sobre los dos.
Pensá en cómo JARVIS describe sus propias capacidades a Tony. No solo 'el radar de largo alcance puede detectar objetos a 500km'. También: 'el radar puede fallar si hay interferencia electromagnética — en ese caso, cambio automáticamente a sensores de corto alcance'. El protocolo de fallo es parte de la descripción del sistema.
En tool design, eso se traduce en dos cosas concretas. Primero: la description tiene que mencionar cuándo la herramienta puede fallar y qué error retorna en cada caso. Segundo: los errores tienen que tener estructura consistente para que el agente pueda parsearlos y tomar decisiones.
El contrato completo de una herramienta documenta éxito Y fallo, ambos con estructura predecible. Una herramienta que no documenta sus errores le quita al agente la capacidad de recuperarse cuando algo sale mal.
Los 3 tipos de errores en tool use
Hay exactamente tres tipos de errores que pueden ocurrir cuando un agente llama a una herramienta. Los Avengers los enfrentan todos en cada misión.
El error del LLM — cuando el modelo genera argumentos inválidos — se previene mayormente con schemas bien tipados. Si definís un enum para un campo, el modelo solo puede elegir entre las opciones válidas. Un schema preciso reduce dramáticamente estos errores. Pero no los elimina — siempre validá los inputs antes de ejecutar.
El error de red o timeout es el más peligroso si no se implementa correctamente. Sin un límite de reintentos, el agente puede quedar en un loop infinito esperando una respuesta que nunca llega.
💡 EXAMEN: Los 3 tipos de errores tienen causas distintas y soluciones distintas. El examen puede describir un escenario y preguntarte qué tipo de error es y cómo manejarlo. Aprendé a distinguirlos por la causa, no por el síntoma.
Errores inútiles vs. errores accionables
La diferencia entre un error inútil y un error accionable es concreta.
Los errores de la columna izquierda tienen algo en común: el agente no puede hacer nada con ellos. 'NullPointerError at line 47' no le dice qué herramienta usar en su lugar, ni si tiene sentido reintentar, ni qué parámetros cambiar.
Los errores de la columna derecha son diccionarios con estructura consistente. Tienen siempre un campo 'error' con el tipo, un campo 'causa' con la razón específica, y un campo que orienta al agente hacia la próxima acción. El agente puede leer ese dict y tomar una decisión informada en su próximo paso.
⚠️ CRÍTICO: el error estructurado va como tool_result exactamente igual que un éxito — como string (JSON serializado). No como excepción de Python, no como None, no como raise. El agente lo recibe en su contexto y lo usa para razonar.
Los 4 patrones de retry y fallback
Los Avengers tienen un protocolo claro cuando algo falla en misión. No es improvisación — es un playbook pre-definido.
El retry inmediato es para errores que probablemente se resuelven solos en segundos. Máximo dos reintentos sin espera. Si sigue fallando, no es un error transitorio.
El retry con backoff exponencial es para cuando el servicio está sobrecargado. Reintentar inmediatamente solo agrava el problema. Los Avengers esperan a que el canal de comunicaciones se despeje antes de volver a intentar.
El escalado humano es el último recurso — y es obligatorio en sistemas con acciones irreversibles. JARVIS no improvisa cuando Tony está incapacitado. El sistema se detiene y alerta al humano.
Demo: JARVIS con error handling completo
Dos herramientas: el radar de SHIELD como principal (puede fallar) y el sensor local de Vision como fallback (siempre disponible). El radar falla intencionalmente en el primer intento para mostrar el flujo completo.
El flujo que vas a ver: radar_shield falla con error estructurado → el agente lee 'reintentable: False' y 'accion_sugerida: usar sensor_local' → elige sensor_local → misión completada. El agente tomó la decisión correcta sin que nadie se la hardcodeara. Eso es lo que hace un error estructurado: convierte el fallo en información accionable.
Resumen del Módulo 2: Tool Design & MCP
Con M2V5 cerrás el Módulo 2 completo. Cinco videos, 18% del examen.
El hilo conductor del Módulo 2: una herramienta bien diseñada tiene contrato completo — éxito y error documentados, schema tipado, single responsibility. MCP te permite compartir esas herramientas entre múltiples agentes. La distribución define qué agente accede a qué según menor privilegio. Y el error handling garantiza que cuando algo falla — y siempre falla en producción — el agente tiene la información para continuar.
Las 4 trampas del examen sobre error handling
Trampa 1: 'Los errores deben lanzarse como excepciones de Python para que el agente los maneje'
FALSO. El error tiene que ser retornado como tool_result con el mismo formato que un éxito exitoso — un string (generalmente JSON serializado). Si lanzás una excepción sin capturarla, el agente no recibe nada en su contexto y no puede tomar ninguna decisión. El manejo de errores en el nivel del Python es tu responsabilidad como developer; el agente recibe el resultado final serializado.
Trampa 2: 'Retry con backoff solo es necesario para errores de red'
FALSO. El backoff exponencial es relevante para cualquier error con causa externa sobrecargada — no solo red. Si un servicio externo devuelve 'rate limit exceeded', reintentar inmediatamente lo va a seguir rechazando. El criterio no es el tipo técnico del error sino si el servicio está temporalmente saturado.
Trampa 3: 'Una tool que siempre falla con el mismo error no necesita documentarlo en la description'
FALSO. Si la herramienta tiene un modo de falla conocido, documentarlo en la description le da al agente la capacidad de anticiparse. Si la description dice 'puede fallar con interferencia_electromagnetica — en ese caso usar sensor_local', el agente puede hacer el fallback automáticamente sin necesitar ver el error primero. La documentación preventiva es mejor que la reactiva.
Trampa 4: 'El escalado humano es el patrón de último recurso — nunca el primero'
VERDADERO en general, pero hay excepciones para el examen. En sistemas con acciones irreversibles de alto riesgo (eliminar datos, enviar emails masivos, ejecutar transacciones financieras), el escalado humano puede ser el primer paso requerido — no el último. La regla general es 'último recurso', pero para acciones críticas irreversibles puede ser obligatorio como paso previo.