Cómo depurar Hermes Agent: logs, trazas, huecos

Tu agente ha hecho algo raro. ¿Dónde miras?

Hermes Agent tiene dos modos de fallo, dolorosos cada uno a su manera. El primero es ruidoso: una excepción con traza o un crash de arranque. El segundo es silencioso: el agente devuelve una respuesta coherente pero equivocada, llama a la herramienta que no es o se apaga después del resultado de una tool. El ruidoso aparece en errors.log. El silencioso es el debug complicado y vive en el audit log de la sesión concreta que se torció.

Esto es un mapa práctico de dónde están los logs, qué archivo corresponde a qué síntoma y las pequeñas herramientas alrededor que convierten 800 líneas de JSONL en algo que puedes leer de verdad. También nombra los huecos que siguen abiertos, para que sepas qué no te va a contar Hermes hoy.

Dónde viven los logs

Todo lo que Hermes escribe aterriza en tu directorio de Hermes, por defecto ~/.hermes/logs/ (y en <profile>/logs/ para perfiles no predeterminados). Importan cuatro archivos:

Los cuatro los escribe el RotatingFileHandler de Python. Cuando un archivo llega a su tope de tamaño rota a agent.log.1, agent.log.2, y así hasta el backup_count configurado. El archivo activo es siempre el que no tiene sufijo. Esto importa cuando persigues un bug de ayer, porque "ayer" ya puede haber rotado. Coge también los numerados, no solo el actual.

El punto de entrada para todo esto es hermes_logging.setup_logging(). El gateway lo llama con mode="gateway" al arrancar y solo adjunta handlers de archivo, nunca un handler de consola. Así que hermes gateway start es silencioso por diseño. Si tu gateway parece muerto, no lo está. Haz tail a gateway.log.

Qué log abrir primero

El síntoma marca el archivo, no al revés. Un árbol de decisión rápido:

• El agente ha crasheado al arrancar o una petición devuelve 500. Abre errors.log con hermes logs errors --since 30m -f. Las trazas caen aquí primero.
• El agente ha respondido, pero la respuesta está mal. Salta errors.log. Las tool calls que produjeron esa respuesta viven en el transcript JSONL de esa sesión (ver la sección siguiente sobre trace-tree).
• Un usuario de Telegram o Discord dice "se ha quedado callado". Abre gateway.log y filtra por su sesión. hermes logs gateway --session abc123 acota.
• El dashboard no se actualiza. gui.log. Los cortes de websocket y los errores de sync del TUI-gateway asoman aquí antes que en ningún otro sitio.
• No sabes qué está pasando en absoluto. hermes logs -f sobre agent.log con un segundo panel en errors.log. La inmensa mayoría de las respuestas a "qué está haciendo mi agente" están a un tail -f de distancia.

La CLI hermes logs es tu aliada. Algunos flags se ganan el sueldo en una sesión de debug en vivo:

hermes logs                              # últimas 50 líneas de agent.log
hermes logs -f                           # sigue agent.log en tiempo real
hermes logs gateway -n 100               # últimas 100 líneas de gateway.log
hermes logs --level WARNING --since 1h   # última hora, warnings y errores
hermes logs --session abc123             # acota por id de sesión
hermes logs errors --since 30m -f        # sigue errores desde hace 30 min
hermes logs list                         # inventario de archivos y tamaños

Leer una sesión como árbol, no como un muro de JSONL

Cuando una sesión termina, su trayectoria completa se escribe en JSON por líneas en el archivo de transcript. Es el artefacto más útil para depurar la clase de bug "coherente pero equivocado", porque cada llamada al modelo, cada tool call y cada resultado quedan capturados en orden con sus argumentos. Y también es, en crudo, ilegible. 800 líneas de audit log para una sesión medianamente compleja es lo normal.

La herramienta comunitaria trace-tree (ver el post de Mukunda Katta en dev.to) lee ese JSONL e imprime un árbol en el terminal. Una sesión se vuelve raíz, cada tool call es hijo, las llamadas denegadas aparecen como hijos con su error adjunto. La abres, lees el árbol, la cierras. Sin login, sin subida, sin vendor lock-in. Apúntala a un archivo de sesión:

trace-tree ~/.hermes/logs/sessions/2026-07-21T09-42-11.jsonl

Para diagnósticos más profundos también puedes pipear el mismo JSONL a jq y filtrar por nombre de tool, latencia o estado de error. Los transcripts son estables entre versiones de una forma que agent.log no lo es, así que construye tus queries puntuales contra el transcript, no contra grep sobre el log humano.

Para la investigación relacionada de "el agente está callado, ¿está atascado?" en canales de mensajería, nuestra guía de troubleshooting de Telegram recorre primero los síntomas del lado de la entrega (bot token, webhook, permisos de grupo), que muchas veces resultan ser la causa real antes de necesitar el árbol de trazas.

Subir el nivel de log sin filtrar secretos

El modo verbose está a un flag. hermes chat --verbose (o -v) pone verbose_logging=True en AIAgent, que llama a setup_verbose_logging() y añade un StreamHandler de consola en nivel DEBUG encima de los handlers de archivo. Ves todo lo que ve el agente, en vivo.

El detalle crítico es que cada registro de log, en cualquier nivel, pasa por RedactingFormatter de agent/redact.py antes de escribirse. El formatter reconoce formas conocidas de credencial (sk-, sk-or-, sk-ant-, patrones OAuth comunes y secretos con forma de variable de entorno) y sustituye el valor en línea. En la práctica esto significa que puedes subir el nivel de log en producción, o pegar un agent.log redactado en un informe de bug, sin filtrar tu clave de OpenRouter.

Hay un solo detalle que conviene nombrar. Si escribes tu propio logger o tu propio formatter y te saltas la pipeline, la redacción no aplica. El crash de arranque del gateway NameError: name 'RedactingFormatter' is not defined reportado como issue #8090 es la misma clase de error a la inversa. Asume que el formatter es crítico, no lo esquives, y si escribes logging a medida, envuélvelo a través de hermes_logging.setup_logging(), no alrededor.

Los huecos de observabilidad que siguen abiertos

Hermes es honesto sobre lo que aún no hace. Dos feature requests abiertas describen el techo actual:

• Spans estructurados con timestamps de inicio y fin. Hoy la mayoría de filas de log llevan un solo timestamp y algunas salidas de tool incluyen un duration_seconds ad-hoc. No hay un esquema estable para start_ts, end_ts, duration_ms y parent_id en toda la trayectoria. Es la issue #6741, y bloquea los dashboards limpios de latencia por herramienta que querrás cuando una sesión se ponga lenta.
• Attach en vivo a una sesión de gateway en curso. A día de hoy, una vez que una sesión de gateway está corriendo no puedes observarla en tiempo real desde fuera. agent.log se pone al día cuando la sesión termina, pero no hay un hook de "mira la sesión de este usuario mientras pasa". Es la issue #18127 y es el hueco más grande para cualquiera que corra Hermes como servicio compartido.

Dos workarounds cubren parte del hueco mientras tanto. El primero es tracing con forma OpenTelemetry hacia un backend como SigNoz, que te permite convertir la actividad de Hermes en spans río abajo aunque no haya emisión nativa de spans. El segundo es Langfuse (issue #1501), que algunos equipos cablean por turno como capa de instrumentación manual. Ninguno es oficialmente first-class todavía, pero los dos están en producción en algún sitio hoy.

Cuando prefieres directamente no ser dueño de la capa de logs

Todo lo anterior asume que tú ejecutas el agente. Si esa es precisamente la parte que preferirías delegar, Hermify ejecuta un Hermes Agent gestionado por ti en Telegram, con el mismo logging y audit trail disponibles en el contenedor subyacente. Te llevas la memoria persistente, los transcripts de sesión y la posibilidad de escalarnos una incidencia concreta, sin tener que mantener hermes logs -f abierto en tu propio VPS. Si estás dudando entre self-hosting y una configuración gestionada por motivos que incluyen la carga operativa de la observabilidad, nuestra opinión sobre Hermes gestionado frente a self-hosted cubre los pros y contras al completo.

Empieza con Hermify y sáltate el trabajo de rotación de logs y observabilidad por completo. O quédate con los logs locales y usa esta guía la próxima vez que tu agente se quede callado. Las dos vías son válidas y el mismo audit trail está disponible en cualquiera.

Sources

• Chapter 9: Observability and Debugging (Claude Code vs. Hermes Agent) - Ken Huang
• Put a Microscope on Hermes: Full Visibility into Agent Execution - Alibaba Cloud
• I had 800 lines of Hermes agent audit log. trace-tree turned it into a tree I could read.
• hermes-agent/hermes_logging.py source
• Issue #18127: Observability for in-flight gateway sessions
• Issue #6741: Structured session tracing with start/end timestamps
• Hermes Monitoring and Observability with OpenTelemetry - SigNoz