O gateway que leva o agente às conversas

O caminho de uma mensagem

Quando você escreve para o bot no Telegram, a mensagem não vai direto para o modelo. Ela chega ao gateway, que confere o remetente, encontra a conversa certa e só então chama o agente. A resposta faz o caminho de volta pelo mesmo processo.

1. A plataforma

   O bot do Telegram ou do Discord recebe a mensagem, e o gateway, conectado à plataforma, a lê.

2. O acesso

   TELEGRAM_ALLOWED_USERS

   Um usuário fora da lista e sem pareamento é recusado ali mesmo.

3. A sessão

   state.db

   O gateway abre ou retoma a sessão daquele chat, com o histórico dela.

4. O agente

   config.yaml

   O agente responde com o modelo e as ferramentas do profile, e a resposta volta à conversa.

O mesmo processo cuida de mais coisas além das mensagens. Ele executa as tarefas agendadas do cron do Hermes, criadas pelo agente quando você solicita um lembrete ou um relatório diário. O resultado chega no canal escolhido. Também transcreve mensagens de voz e responde em áudio nas plataformas que aceitam voz.

O gateway atende mais de vinte plataformas, entre elas Telegram, Discord, Slack, WhatsApp, Signal, e-mail, Matrix e Microsoft Teams. Este portal cobre Telegram e Discord, os dois canais da trilha.

Um processo para a máquina inteira

Desde a v0.22.0, o gateway é o centro do Hermes. A CLI clássica, a TUI, o Hermes Desktop, os bots e o cron se conectam ao gateway do profile em vez de rodar cada um o próprio agente. Uma conversa é uma fila só, com um único processo gravando nela. Por isso uma sessão começada no Telegram aparece no dashboard. Fechar o terminal no meio de uma tarefa também não a cancela: a tarefa continua no gateway.

Na VPS, um único gateway atende todos os profiles da máquina. Ele roda como o serviço hermes-gateway do systemd do usuário hermes. O linger, ativado na instalação, mantém o serviço ligado sem uma sessão SSH aberta. Com mais de um profile, você não instala um gateway por profile: o gateway do profile padrão serve os outros. Cada profile controla só os próprios bots.

Os registros ficam no journal do systemd. O comando journalctl --user -u hermes-gateway -f acompanha o serviço em tempo real. O arquivo ~/.hermes/logs/gateway.log também registra o gateway.

Os usuários liberados para falar com o agente

O bot de um canal tem acesso ao terminal da VPS, porque executa as ferramentas do agente. Por isso o gateway recusa, por padrão, todo usuário fora da lista de acesso e sem pareamento. Há duas formas de liberar um usuário:

A variável GATEWAY_ALLOW_ALL_USERS=true libera qualquer pessoa da plataforma. A documentação desaconselha essa opção num bot com acesso ao terminal, porque qualquer usuário do Telegram passaria a executar comandos no seu servidor.

Dentro da lista, o gateway ainda separa administradores de usuários comuns. Sem configuração, todo usuário liberado tem acesso completo. Com a lista de administradores definida no config.yaml, os usuários comuns conversam com o agente normalmente, mas só executam os comandos de barra que você liberar. O comando /whoami mostra a cada pessoa o próprio nível de acesso.

O que o gateway guarda de cada conversa

Cada chat tem a própria sessão. Ela não reinicia sozinha por inatividade nem na virada do dia. A conversa continua até você mandar /new. Quando a sessão cresce, o histórico é comprimido automaticamente. O /sessions lista as sessões daquele chat e retoma uma delas pelo nome.

A troca de modelo com /model vale para a sessão e sobrevive ao reinício do gateway. O /model reset volta ao modelo do profile sem apagar a conversa.

A resposta final passa por um registro de entrega no state.db. Se o gateway cair entre gerar a resposta e a plataforma confirmar o recebimento, o próximo início reenvia a resposta guardada, sem rodar a tarefa de novo. Quando não dá para saber se a primeira tentativa chegou, a resposta reenviada vem marcada como possível duplicata.

Comandos dentro da conversa

No Telegram e no Discord, a própria conversa aceita comandos que o gateway trata antes do modelo:

• /newabre uma conversa nova, e o agente relê a memória atualizada
• /modelmostra ou troca o modelo da sessão
• /statusmostra o modelo e o resumo da sessão
• /stoppara o agente em execução e o trabalho em primeiro plano
• /approve e /denyrespondem a um comando perigoso que espera a sua aprovação
• /sessionslista as sessões do chat e retoma uma pelo nome
• /whoamimostra o seu nível de acesso e os comandos que você pode usar
• /helplista os comandos disponíveis para você

Antes de executar um comando, o Hermes compara a linha com uma lista de padrões perigosos, como rm -r, chmod 777, DROP TABLE e systemctl stop. No modo padrão, smart, um modelo auxiliar aprova sozinho o que é inofensivo, recusa o que é claramente destrutivo e pergunta nos casos duvidosos. A pergunta chega na própria conversa. Você responde com /approve ou /deny em até cinco minutos. O modo manual pergunta em todos os comandos da lista.