Cuando los agentes LLM pasan de prototipos a producción, los fallos más peligrosos no suelen ser respuestas incorrectas, sino que el sistema se caiga a las 2 a.m. por un 429, un log descomunal o una API key expirada. Muchos frameworks dejan eso al try/except del desarrollador. Hermes Agent lo integra en el runtime.

Este artículo analiza las seis capas de tolerancia a fallos de Hermes Agent: clasificación de errores, reintento adaptativo, fallback de proveedor, compresión de contexto, rollback por checkpoints y recuperación de sesiones. Verás exactamente cómo Hermes se recupera cuando algo sale mal.

1. Clasifica primero, decide después: el clasificador de errores

Hermes enruta cada fallo de API a través de classify_api_error() en agent/error_classifier.py. No trata cada excepción como un problema de red genérico, sino que la mapea a un FailoverReason concreto: rate_limit, overloaded, context_overflow, payload_too_large, long_context_tier, auth, billing, content_policy_blocked, ssl_cert_verification, timeout, stream_drop, thinking_signature, model_incompatible e invalid_request.

Cada razón lleva tres banderas: retryable, should_fallback y should_compress. El bucle de recuperación actúa sobre esas banderas, no sobre el texto del error. Eso hace que la estrategia sea predecible, testable y extensible.

2. Reintento adaptativo: lee Retry-After, no solo duerma

Hermes implementa adaptive_rate_limit_backoff() en agent/retry_utils.py. No es un backoff exponencial ingenuo. También:

• Lee el header Retry-After de la respuesta HTTP.
• Limita la espera a 600 segundos para que un proveedor no bloquee la sesión indefinidamente.
• Usa políticas especiales de backoff largo/corto para la sobrecarga de Z.AI Coding.
• Añade jitter para evitar que varias instancias de Hermes vuelvan a golpear al proveedor al mismo tiempo.

Durante el bucle de reintento, Hermes imprime un bloque conciso con el error, proveedor, modelo, tiempo transcurrido, tamaño del contexto y cuenta regresiva. Esa transparencia es esencial para depurar gateways o cron jobs 24×7.

3. Fallback de proveedor: del reintento local al escape cruzado

Hermes no se queda mirando a un solo proveedor. Elige una ruta según el tipo de error.

• Reintento transitorio local: para cortes de conexión, 5xx y 408, reintenta varias veces en el mismo proveedor.
• Refresco de autenticación y pools de credenciales: en errores auth, intenta refrescar credenciales, refrescar el runtime de Nous Portal y rotar keys si hay un pool.
• Facturación y rate limits: marca el proveedor como unhealthy y cambia a la cadena de fallback configurada, luego a la global, y finalmente a la cadena de auto-descubrimiento interna.
• Políticas de contenido: en content_policy_blocked, no reintenta; le dice al usuario cómo reformular o configurar un fallback.

Para los 429 de Nous Portal, Hermes escribe un registro de rate_limit compartido entre sesiones, evitando que todos los workers sigan golpeando el mismo bucket agotado. Es una protección pensada para despliegues de alta concurrencia.

4. Compresión de contexto: convierte la “explosión de contexto” en un evento rutinario

El fallo más común en conversaciones largas es superar la ventana de contexto. Hermes lo maneja con precisión:

• Errores de output-cap: si max_tokens excede el límite del proveedor, pide al usuario que baje model.max_tokens sin reintentar.
• Input-too-large: extrae el límite real del mensaje de error, actualiza el context_length del compresor y comprime los mensajes.
• Caso especial Minimax: si el proveedor solo dice “excedido por X tokens”, mantiene la ventana original y comprime.

La compresión no es de un solo paso: primero resume mensajes, luego reduce payloads de imagen, y solo entonces pide al usuario /new o /compress para un 413 verdadero. En errores de tier de contexto largo de Anthropic, baja temporalmente de 1M a 200K tokens y comprime, sin persistir el downgrade.

5. Checkpoints y rollback: seguro para archivos y estado

Hermes incluye un checkpoint manager de sistema de archivos en tools/checkpoint_manager.py. En cualquier momento puedes ejecutar /rollback para listar y restaurar checkpoints. Para refactorizaciones, cambios de configuración o operaciones masivas, es una capa de deshacer ligera.

Los snapshots van más allá:

/snapshot create before-major-refactor
/snapshot restore 20260717_142030
/snapshot prune 10

/snapshot conserva configuración y estado de Hermes; /rollback conserva archivos del directorio de trabajo. Juntos cubren estado y archivos.

6. Recuperación de sesiones: handoff sin fisuras entre CLI y Telegram

Hermes persiste cada conversación en una base de datos SQLite en ~/.hermes/state.db, incluyendo historial completo, tool calls, conteos de tokens, snapshots del system prompt, timestamps e IDs de sesión padre. Eso significa que:

• hermes --continue o hermes -r <session_id> retoma la última conversación CLI.
• /new payments-refactor nombra una sesión y /resume payments-refactor la recupera.
• Puedes transferir una sesión entre plataformas: empieza en CLI, pásala a Telegram y retómala en escritorio con /resume.

Al retomar, Hermes muestra un resumen compacto para que no tengas que releer todo el log. Las sesiones largas se controlan con /compress.

7. Tabla de comandos de emergencia

Comando	Acción
/retry	Reenviar el último mensaje al agente.
/resume [name]	Reanudar una sesión previa.
/new [name] / /reset	Iniciar sesión nueva, opcionalmente nombrada.
/compress [here [N] | focus topic]	Comprimir el contexto manualmente.
/undo	Eliminar el último intercambio usuario/assistant.
/rollback [number]	Listar o restaurar un checkpoint.
/snapshot create/restore/prune	Guardar, restaurar o limpiar snapshots.
/stop	Matar todos los procesos en segundo plano.
hermes --continue	Reanudar la sesión CLI más reciente.
hermes -r <id>	Reanudar sesión por ID.
hermes -c "name"	Reanudar sesión por nombre.

8. Comparación con frameworks populares

Capacidad	Hermes Agent	OpenAI Agents	AutoGen/AG2	CrewAI	LangGraph
Clasificación de errores	FailoverReason integrado	Errores básicos del SDK	Más simple	A nivel de tool	Hay que diseñarlo
Fallback automático de proveedor	Cadena de fallback integrada	Implementación manual	Parcial	No soportado	Implementación manual
Compresión de contexto	Multi-etapa integrada	No soportado	No soportado	No soportado	No soportado
Persistencia/resumen de sesiones	SQLite + /resume	Guardar manualmente	Guardar manualmente	No soportado	Checkpoint de máquina de estados
Checkpoints de archivos	/rollback	No soportado	No soportado	No soportado	No soportado
Handoff entre plataformas	Integrado	No soportado	No soportado	No soportado	No soportado

La diferencia de Hermes es que el manejo de errores no es un plugin opcional: es parte del runtime. No escribes try/except, ni mantienes listas de proveedores, ni recortas contexto a mano. Todo eso es el comportamiento por defecto.

9. Recomendaciones prácticas para equipos de ingeniería

1. Configura un proveedor de fallback. Al menos uno en producción para que 429 y 402 no se conviertan en alertas a las 3 a.m.
2. Nombra sesiones importantes. Usa /new <task-name> para poder retomarlas y transferirlas entre plataformas.
3. Crea snapshots antes de cambios grandes. /snapshot create <label> permite revertir rápidamente.
4. Usa cron no-agent para tareas repetibles. Para jobs críticos recurrentes, scripts no_agent: true con stdout directo evitan la incertidumbre de la inferencia LLM.
5. Respalda ~/.hermes/state.db. Ahí vive todo tu historial de conversaciones.

Conclusión

El sistema de manejo de errores de Hermes Agent es mucho más que “reintentar un par de veces y rendirse”. Ataca los fallos comunes de operaciones LLM desde seis ángulos: clasificación, reintento, fallback, compresión, checkpoints y recuperación de sesiones. Para equipos que quieren ejecutar agentes en producción, esa capacidad de auto-recuperación es tan importante como la habilidad de razonamiento del modelo.

Si aún escribes scripts ad-hoc para caídas de proveedor, inflación de contexto o cambio de modelo, deja que Hermes se encargue de ese trabajo sucio. Configura tu fallback, luego presiona /resume y sigue adelante.