Tutorial 26: Processamento em Lote | Easy Understand Hermes Agent

Esta é parte da série oficial de tutoriais do Hermes Agent. Ver todos os tutoriais

Pense nisto como uma lista de verificação matinal que você executa antes de começar o trabalho — você não quer lembrar de cada tarefa sozinho, então as escreve uma vez, e seu assistente as marca automaticamente todos os dias. É exatamente isso que o Hermes permite fazer com gateway hooks e um arquivo simples chamado BOOT.md.

Neste tutorial, você aprenderá como fazer o Hermes executar um “lote” personalizado de tarefas toda vez que seu gateway iniciar — como verificar logs, postar lembretes ou até mesmo executar um mini-agente que pensa e reporta.

Passo 1: Crie seu diretório de hooks

Primeiro, crie uma pasta dentro do seu diretório de hooks. Cada hook vive em sua própria subpasta com dois arquivos: HOOK.yaml (a configuração) e handler.py (a lógica).

mkdir -p ~/.hermes/hooks/boot-md
cd ~/.hermes/hooks/boot-md

Agora crie o HOOK.yaml:

name: "boot-md"
event: "gateway_startup"

Só isso — o evento informa ao Hermes para disparar este hook quando o gateway iniciar.

Passo 2: Escreva o handler

Agora crie o handler.py. É aqui que a mágica acontece. O handler lê um arquivo chamado BOOT.md do seu diretório pessoal e, em seguida, inicia uma thread em segundo plano que executa um agente com essas instruções.

Aqui está a ideia central (simplificada):

import os, threading
from pathlib import Path
from hermes.agent import AIAgent

def run_boot_md():
    content = Path.home().joinpath(".hermes", "BOOT.md").read_text()
    print(f"Running BOOT.md ({len(content)} chars)")

    agent = AIAgent(
        instructions=content,
        model=_resolve_gateway_model(),          # usa o modelo do seu gateway
        **_resolve_runtime_agent_kwargs()       # usa suas credenciais de provedor
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

def handler(event):
    thread = threading.Thread(target=run_boot_md, daemon=True)
    thread.start()

As duas linhas-chave:

_resolve_gateway_model() lê o modelo atualmente configurado no gateway.
_resolve_runtime_agent_kwargs() resolve as credenciais do provedor da mesma forma que uma interação normal do gateway faz — incluindo chaves de API, URLs base, tokens OAuth e pools de credenciais.

Sem elas, um AIAgent() puro recorre aos padrões embutidos e retornará 401 contra qualquer endpoint não padrão.

Passo 3: Teste

Reinicie o gateway:

hermes gateway restart

Acompanhe os logs:

hermes logs --follow --level INFO | grep boot-md

Você deve ver Running BOOT.md (N chars) seguido de boot-md completed: ... (resumo do que o agente fez) ou boot-md completed (nothing to report) quando o agente responder com um token de silêncio exato, como [SILENT].

Exclua ~/.hermes/BOOT.md para desativar a lista de verificação — o hook permanece carregado, mas é silenciosamente ignorado quando o arquivo não existe.

Expandindo o padrão

Listas de verificação com consciência de agenda: use datetime.now().weekday() dentro das instruções do BOOT.md (“se for segunda-feira, verifique também o log de deploy semanal”). As instruções são texto livre, então qualquer coisa que o agente possa raciocinar é válida.
Múltiplas listas de verificação: aponte o hook para um arquivo diferente (STARTUP.md, MORNING.md, etc.) e registre diretórios de hook separados para cada um.
Variante sem agente: se você não precisar de um loop completo de agente, pule o AIAgent completamente e faça o handler postar uma notificação fixa diretamente via httpx. Mais barato, mais rápido e sem dependência de provedor.

Por que isso não é um recurso embutido

Uma versão anterior do Hermes trazia isso como um hook embutido e silenciosamente iniciava um agente com padrões básicos em toda inicialização do gateway. Isso surpreendia usuários com endpoints personalizados e tornava o recurso invisível para quem não sabia que ele estava rodando. Mantê-lo como um padrão documentado — construído por você, no seu diretório de hooks — significa que você vê exatamente o que ele faz e opta por usá-lo ao escrever os arquivos.

Como Funciona

Na inicialização do gateway, HookRegistry.discover_and_load() escaneia ~/.hermes/hooks/
Cada subdiretório com HOOK.yaml + handler.py é carregado dinamicamente
Os handlers são registrados para seus eventos declarados
Em cada ponto do ciclo de vida, hooks.emit() dispara todos os handlers correspondentes
Erros em qualquer handler são capturados e registrados — um hook quebrado nunca derruba o agente

:::info Os gateway hooks só disparam no gateway (Telegram, Discord, Slack, WhatsApp, Teams). O CLI não carrega gateway hooks. Para hooks que funcionam em qualquer lugar, use plugin hooks. :::

Resumo

Agora você sabe como transformar um arquivo de texto simples em uma poderosa lista de verificação de inicialização que roda automaticamente. Seja um loop completo de agente ou uma chamada HTTP rápida, o padrão é o mesmo: escreva um hook, aponte-o para um arquivo e deixe o Hermes cuidar do resto.

A seguir: Tutorial 27 — Modo de Voz: falando com o Hermes sem usar as mãos.