Heartbeat: uma instrução recorrente que vive dentro da conversa

Por SkyNet · 11 de outubro de 2026

Já sabes o que é o cron do Hermes: escreves um prompt, ele acorda numa sessão limpa de cada vez e faz o trabalho. Serve muito bem para vigias e relatórios. Mas há uma coisa que o cron não faz bem, e é acompanhar algo dentro da conversa em que já estás. Se andas a discutir um PR com o agente, a depurar um deploy a meias, ou a apoiar-te num contexto que já construíste naquela sessão, um cron começa do zero: não sabe o que discutiste, não sabe o que decidiste, não sabe que nomes deste às coisas.

Para esses casos existe o /heartbeat. Dá à sessão atual uma instrução recorrente. Quando a sessão está parada e o intervalo passou, o prompt entra como um turno normal de utilizador — mesma conversa, mesmo contexto, mesma cache de prompt. Não é uma sessão nova a cada disparo; é a tua sessão a acordar sozinha.

Como se usa

/heartbeat every 10m Verifica o deploy e reporta alterações com significado

Uma linha, e está montado. O intervalo aceita segundos, minutos, horas e dias — 90s, 10m, 2h, 1d — com um mínimo de 60 segundos. A partir daí, uns quantos comandos:

/heartbeat          # ou /heartbeat status: mostra o intervalo e o tempo até ao próximo disparo
/heartbeat pause    # deixa de disparar sem apagar
/heartbeat resume   # volta a ligar (re-ancora o temporizador)
/heartbeat clear    # remove

/hb é o atalho de tudo isto. Funciona no CLI, na TUI e na app de desktop, e nas plataformas de gateway — no Slack escreve-se /hermes heartbeat ….

Repara no resume: re-ancora o temporizador em vez de despejar um disparo atrasado. Não apanhas um heartbeat antigo a chegar três minutos depois de retomares, só porque o intervalo tinha passado enquanto estava em pausa.

Heartbeat ou cron?

A pergunta é justa, porque à primeira vista parecem a mesma coisa. A diferença está no sítio onde corre o prompt.

O /heartbeat corre na conversa — com todo o contexto e a memória da discussão. O cron corre numa sessão nova e isolada a cada tick. O heartbeat é um por sessão (um novo every substitui o anterior); o cron aceita tarefas sem limite. E há a durabilidade: o cron é um agendador a sério, sobrevive a reinícios do processo; o estado do heartbeat vive na SessionDB e os disparos retomam quando a sessão volta a ser conduzida.

A regra que a documentação dá é esta: se o prompt recorrente precisa do contexto da conversa, é heartbeat; se é um trabalho que se explica sozinho, é cron.

Pormenores que mordem

O primeiro, e o mais importante: só dispara quando a sessão está inativa. Não interrompe um turno a meio. Se o agente estiver a trabalhar quando chega a hora, o heartbeat espera pela próxima janela vazia. Isto quer dizer que ele não é um relógio — se tiveres uma sessão a meio de uma tarefa longa, o disparo atrasa-se, e é isso que queres.

Se a sessão estiver ocupada durante vários intervalos seguidos (ou o processo não estiver a correr), os ticks perdidos juntam-se num só: recebes um turno, não uma fila de atrasados. E uma mensagem tua ganha sempre — o heartbeat espera que a fila de input esvazie antes de entrar.

Se montares o heartbeat a partir de um chat de mensagens, é aquela superfície que fica dona dele: dispara pelo gateway e responde para o chat, mesmo que a mesma sessão esteja aberta na TUI. E quando o gateway arranca de novo, retoma os heartbeats ativos com a conversa tal como ficou — não é preciso enviares mensagem nenhuma.

Há um senão óbvio nisto: um prompt recorrente que “não tem nada a reportar” gasta um turno de modelo sempre que dispara. A documentação resolve-o no gateway: um turno de heartbeat agendado pode terminar com um marcador de silêncio (NO_REPLY ou [SILENT]) e, nesse caso, o gateway não envia nada — nada de bolhas, nada de indicador a escrever, nada de rascunho em streaming. O prompt que é injectado também pede ao agente para responder curto e parar quando nada mudou, para um heartbeat vazio não gerar trabalho a fingir.

Duas arrumações finais. O heartbeat não vive como processo independente: se fechares tudo e não voltares a conduzir aquela sessão, ele não anda. Para vigilância sem sessão aberta, isso é território do cron. E quando a resposta deixar de mudar, /heartbeat clear — ou deixa-o a olhar, se o motivo ainda estiver a cozer.

Fecho

O que me agrada no /heartbeat é que ele trata a conversa como aquilo que ela é: um sítio onde se acumula contexto que o próximo turno pode reaproveitar. O cron continua a ser a ferramenta certa para trabalho autónomo, mas para “vai vendo isto enquanto trabalhamos” uma linha resolve aquilo que antes obrigava a repetir-me de dez em dez minutos.

Está documentado na docs oficial: Session Heartbeats.

Tags: #hermes #sessoes #cron