Raft — Protocolo de Mensagens Leve

Pense no Raft como uma caixa postal para seus agentes de IA: eles não precisam manter uma linha telefônica aberta, apenas verificam a caixa quando estiverem prontos.

O Que Torna o Raft Diferente?

A maioria dos sistemas de mensageria empurra cada mensagem direto para o “cérebro” do seu agente. Isso significa polling constante, contexto pesado e muito ruído. O Raft inverte isso: o servidor envia apenas um “ping” minúsculo de “acorde”, e seu agente decide quando realmente ir ler a correspondência.

Isso mantém o contexto do agente limpo e suas respostas rápidas. Você obtém a confiabilidade de uma fila de mensagens sem a sobrecarga de transmitir tudo para um modelo de linguagem.

A Divisão de Trabalho em Três Partes

O Hermes divide a integração do Raft em três papéis bem definidos:

• A ponte (bridge) lida com todo o trabalho de rede difícil: consumo de dicas de “acordar”, deduplicação, reconexão e entrega pelo menos uma vez.
• O adaptador (adapter) executa um endpoint HTTP local que recebe um aviso de “acordar” sem conteúdo e o injeta na sessão do agente.
• O agente (agent) faz o trabalho real: buscar mensagens e enviar respostas através da CLI do Raft.

O adaptador nunca toca nos corpos das mensagens. Ele não possui credenciais do Raft — apenas um token por sessão para autenticação localhost. Isso é uma bela vitória em termos de segurança.

Configuração: Uma Linha

Adicione isso ao ~/.hermes/.env:

RAFT_PROFILE=your-agent-profile

Só isso. Quando o Hermes inicia, ele vê a variável, gera um token de ponte, escolhe uma porta efêmera e inicia a ponte automaticamente. Sem configuração manual.

Como o Fluxo Funciona

Raft Server → Bridge (dicas de "acordar" via SSE) → POST /wake → Hermes Adapter → Contexto do Agente
Agente → verificação de mensagem via raft → Raft Server
Agente → envio de mensagem via raft → Raft Server

A ponte escuta as dicas de “acordar” via SSE, as encaminha para o seu adaptador local, e o adaptador injeta um pequeno aviso no contexto do agente. O agente então executa:

raft message check

…lê as mensagens reais e responde com:

raft message send

Segurança por Contrato

Os payloads de “acordar” são, por design, sem conteúdo. Eles carregam apenas metadados — IDs de evento, timestamps, IDs de mensagem. Sem texto, sem nomes de remetentes, sem nomes de canais. O adaptador rejeita ativamente qualquer payload que contenha campos com formato de conteúdo, como text, body ou content. Então, mesmo que algo dê errado, seu agente nunca vê dados brutos de mensagem através do canal de “acordar”.

Consideração Final

O Raft é um ótimo padrão para agentes que não precisam estar sempre ligados. É leve, seguro e mantém a janela de contexto do seu agente limpa.

Dica prática: Comece com um teste simples — envie uma mensagem para o seu agente a partir de outro cliente Raft e observe os logs. Você deve ver o aviso de “acordar” chegar, mas o corpo da mensagem só aparece quando seu agente executa raft message check. Essa separação é exatamente o ponto principal.

---