Como debugar Hermes Agent: logs, traces, lacunas

Seu agente fez algo estranho. Onde você olha?

O Hermes Agent tem dois modos de falha, cada um doloroso do seu jeito. O primeiro é barulhento: uma exceção com stack trace ou um crash na inicialização. O segundo é silencioso: o agente devolve uma resposta coerente porém errada, chama a ferramenta errada ou some depois do resultado de uma tool. O barulhento aparece em errors.log. O silencioso é o debug difícil e vive no audit log da sessão específica que descarrilou.

Este é um mapa prático de onde estão os logs, qual arquivo casa com qual sintoma e as pequenas ferramentas em volta que transformam 800 linhas de JSONL em algo que dá para ler de verdade. Ele também nomeia as lacunas que continuam abertas, para você saber o que o Hermes não vai te contar hoje.

Onde os logs moram

Tudo que o Hermes escreve cai no seu diretório do Hermes, por padrão ~/.hermes/logs/ (e em <profile>/logs/ para perfis não padrão). Quatro arquivos importam:

Os quatro são escritos pelo RotatingFileHandler do Python. Quando um arquivo bate no limite de tamanho, ele roda para agent.log.1, agent.log.2, e assim por diante até o backup_count configurado. O arquivo ativo é sempre o sem sufixo. Isso importa quando você caça um bug de ontem, porque "ontem" já pode ter rotacionado. Pegue os arquivos numerados também, não só o atual.

O ponto de entrada de tudo isso é hermes_logging.setup_logging(). O gateway o chama com mode="gateway" na inicialização e só anexa handlers de arquivo, nunca um handler de console. Ou seja, hermes gateway start é silencioso por design. Se seu gateway parece morto, não está. Faça tail no gateway.log.

Qual log abrir primeiro

O sintoma escolhe o arquivo, e não o contrário. Uma árvore de decisão rápida:

• O agente crashou na inicialização, ou uma request deu 500. Abra errors.log com hermes logs errors --since 30m -f. Stack traces caem aqui primeiro.
• O agente respondeu, mas a resposta está errada. Pule errors.log. As tool calls que produziram essa resposta ruim estão no transcript JSONL daquela sessão (veja a próxima seção sobre trace-tree).
• Um usuário de Telegram ou Discord diz "ficou mudo". Abra gateway.log e filtre pela sessão dele. hermes logs gateway --session abc123 estreita.
• O dashboard não está atualizando. gui.log. Desconexões de websocket e erros de sync do TUI-gateway aparecem aqui antes de aparecer em qualquer outro lugar.
• Você não sabe o que está acontecendo, ponto. hermes logs -f no agent.log com um segundo painel em errors.log. A maioria esmagadora das respostas para "o que meu agente está fazendo" está a um tail -f de distância.

A CLI hermes logs é sua parceira. Alguns flags valem cada centavo numa sessão de debug ao vivo:

hermes logs                              # últimas 50 linhas de agent.log
hermes logs -f                           # segue agent.log em tempo real
hermes logs gateway -n 100               # últimas 100 linhas de gateway.log
hermes logs --level WARNING --since 1h   # última hora, warnings e erros
hermes logs --session abc123             # estreita para um id de sessão
hermes logs errors --since 30m -f        # segue erros dos últimos 30 min
hermes logs list                         # inventário de arquivos e tamanhos

Ler uma sessão como árvore, não como uma parede de JSONL

Quando uma sessão termina, sua trajetória completa é escrita como JSON por linha no arquivo de transcript. É o artefato mais útil para debugar a classe de bug "coerente mas errado", porque cada chamada de modelo, cada tool call e cada resultado ficam capturados em ordem com seus argumentos. E, no formato cru, é ilegível. 800 linhas de audit log para uma sessão medianamente complexa é o normal.

A ferramenta comunitária trace-tree (veja o post de Mukunda Katta no dev.to) lê esse JSONL e imprime uma árvore no terminal. A sessão vira raiz, cada tool call é filha, as chamadas negadas aparecem como filhas com o erro anexado. Você abre, lê a árvore, fecha. Sem login, sem upload, sem vendor lock-in. Aponte para um arquivo de sessão:

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

Para diagnósticos mais profundos você também pode canalizar o mesmo JSONL para o jq e filtrar por nome de tool, latência ou status de erro. Os transcripts são estáveis entre versões de um jeito que o agent.log não é, então monte suas queries pontuais contra o transcript, não contra grep no log humano.

Para a investigação relacionada de "o agente está calado, será que travou?" nos canais de mensagens, nosso guia de troubleshooting do Telegram percorre primeiro os sintomas do lado da entrega (bot token, webhook, permissões de grupo), que várias vezes acabam sendo a causa real antes de você precisar da trace tree.

Subir o nível de log sem vazar segredos

O modo verbose está a uma flag. hermes chat --verbose (ou -v) coloca verbose_logging=True no AIAgent, que chama setup_verbose_logging() e adiciona um StreamHandler de console em nível DEBUG em cima dos handlers de arquivo. Você vê tudo que o agente vê, ao vivo.

O detalhe crítico é que cada registro de log, em qualquer nível, passa pelo RedactingFormatter de agent/redact.py antes de ser escrito. O formatter reconhece formatos conhecidos de credencial (sk-, sk-or-, sk-ant-, padrões OAuth comuns e segredos em formato de variável de ambiente) e substitui o valor no lugar. Na prática isso significa que você pode subir o nível de log em produção, ou colar um agent.log redigido num bug report, sem vazar sua chave da OpenRouter.

Tem um detalhe que vale nomear. Se você escrever seu próprio logger ou seu próprio formatter e pular a pipeline, a redação não se aplica. O crash na inicialização do gateway NameError: name 'RedactingFormatter' is not defined reportado como issue #8090 é a mesma classe de erro no sentido inverso. Assuma que o formatter é crítico, não o contorne, e se escrever logging customizado, envolva através de hermes_logging.setup_logging(), não em volta dele.

As lacunas de observabilidade que continuam abertas

O Hermes é honesto sobre o que ainda não faz. Dois feature requests abertos descrevem o teto atual:

• Spans estruturados com timestamps de início e fim. Hoje a maioria das linhas de log carrega um único timestamp e algumas saídas de tool incluem um duration_seconds ad-hoc. Não existe um schema estável para start_ts, end_ts, duration_ms e parent_id em toda a trajetória. É a issue #6741, e ela bloqueia os dashboards limpos de latência por ferramenta que você vai querer quando uma sessão ficar lenta.
• Attach ao vivo em uma sessão de gateway em curso. Na release atual, uma vez que uma sessão de gateway está rodando você não consegue observá-la em tempo real por fora. O agent.log corre atrás quando a sessão termina, mas não existe um hook de "acompanhe a sessão desse usuário enquanto ela acontece". É a issue #18127, e é a maior lacuna para quem roda Hermes como serviço compartilhado.

Dois workarounds cobrem parte da lacuna enquanto isso. O primeiro é tracing no formato OpenTelemetry para um backend como o SigNoz, que deixa você transformar a atividade do Hermes em spans lá na frente mesmo sem emissão nativa. O segundo é o Langfuse (issue #1501), que alguns times ligam por turno como uma camada de instrumentação manual. Nenhum é oficialmente first-class ainda, mas os dois estão em produção em algum lugar hoje.

Quando você prefere simplesmente não ser dono da camada de logs

Tudo acima assume que você está rodando o agente. Se essa é justamente a parte que você prefere delegar, a Hermify roda um Hermes Agent gerenciado para você no Telegram, com o mesmo logging e audit trail disponíveis no container por baixo. Você fica com a memória persistente, os transcripts de sessão e a possibilidade de escalar um problema específico com a gente, sem precisar manter hermes logs -f aberto no seu próprio VPS. Se você está em cima do muro entre self-hosting e um setup gerenciado por motivos que incluem a carga operacional da observabilidade, nossa análise sobre Hermes gerenciado versus self-hosted cobre os prós e contras por completo.

Comece com a Hermify e pule o trabalho de rotação de logs e observabilidade por inteiro. Ou fique com os logs locais e use este guia da próxima vez que seu agente ficar mudo. Os dois caminhos valem, e o mesmo audit trail está disponível em ambos.

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