History

Rodribm10 89b471831d feat(hermes): plugin captain-http-callback (HTTP delivery adapter) Adiciona plugin externo pro Hermes Agent que entrega a resposta do agente como POST HTTP a uma URL configurável — em vez de empurrar pra plataforma de mensageria (Telegram, Slack, etc) como o Hermes faz por default. Por quê: O Hermes nativamente entrega respostas em plataformas conhecidas. Quando integramos o Hermes como cérebro de outro backend (Captain / Chatwoot), precisamos da resposta de volta via HTTP pro backend continuar o fluxo (mandar pro cliente WhatsApp, atualizar conversa, etc). O Hermes não tem deliver type "http_callback" built-in, então criamos via API de plugin oficial deles (kind: platform). Arquivos: - plugin.yaml — manifest (kind=platform) - __init__.py — entrypoint (re-exporta register) - adapter.py — HttpCallbackAdapter implementando BasePlatformAdapter - README.md — uso, formato do POST, signing HMAC opcional Como funciona: 1. Backend (Captain) → POST /webhooks/<rota> no Hermes (entrada) 2. Hermes processa via Codex/Anthropic/Gemini conforme config dele 3. Hermes invoca este plugin (deliver=http_callback) 4. Plugin POSTa resposta na URL configurada via --deliver-chat-id 5. Backend recebe e roteia pro destinatário real Validado end-to-end no Hermes da VPS com: - Subscription criada via `hermes webhook subscribe ... --deliver http_callback` - POST simulando msg do cliente → resposta chegou no servidor de teste em ~11s (tempo de processamento via subscription Codex) - Plugin enabled e descoberto via `hermes plugins list` Próximo passo (separado, em outro PR): cliente Captain (outgoing + incoming endpoint) que conecta o Captain ao Hermes via este plugin. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>		2026-05-01 13:13:15 -03:00
..
__init__.py	feat(hermes): plugin captain-http-callback (HTTP delivery adapter)	2026-05-01 13:13:15 -03:00
adapter.py	feat(hermes): plugin captain-http-callback (HTTP delivery adapter)	2026-05-01 13:13:15 -03:00
plugin.yaml	feat(hermes): plugin captain-http-callback (HTTP delivery adapter)	2026-05-01 13:13:15 -03:00
README.md	feat(hermes): plugin captain-http-callback (HTTP delivery adapter)	2026-05-01 13:13:15 -03:00

README.md

captain-http-callback

Hermes Agent platform plugin que entrega a resposta do agente como POST HTTP a uma URL configurável.

Por que existe

O Hermes nativamente entrega respostas em plataformas conhecidas (Telegram, Slack, Discord, WhatsApp, etc). Quando integramos o Hermes como cérebro de outro backend (no nosso caso o Captain / Chatwoot), precisamos da resposta de volta via HTTP para o backend continuar o fluxo (mandar pro cliente WhatsApp, atualizar conversa, etc) — esse plugin fornece essa ponte.

Fluxo

1. Captain → POST /webhooks/<rota> no Hermes (entrada da mensagem do cliente)
2. Hermes processa via LLM (Codex/Anthropic/Gemini conforme config dele)
3. Hermes invoca este plugin com a resposta gerada
4. Plugin → POST <url-configurada> com a resposta
5. Captain recebe, identifica conversa, manda pro WhatsApp

Instalação

Plugin é discovered automaticamente quando colocado em ~/.hermes/plugins/captain-http-callback/. Após copiar os arquivos, reinicie o gateway:

pkill -f "hermes.*gateway" && sleep 2
nohup hermes gateway run --replace > /var/log/hermes-gateway.log 2>&1 &

Verifique:

hermes plugins list | grep http_callback

Uso

Cria webhook subscription apontando para este deliver type:

hermes webhook subscribe minha-rota \
    --prompt "Cliente disse: {message}. Responda como ..." \
    --deliver http_callback \
    --deliver-chat-id "https://seu-backend.example/api/hermes_callback"

--deliver-chat-id é interpretado como a URL de callback. Quando o agente terminar de processar, este plugin POSTa nessa URL.

Formato do POST de callback

POST <url-configurada> HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Hermes-Callback-Signature: sha256=<hex-hmac>     (opcional, se signing_secret configurado)

{
  "content": "<resposta gerada pelo agente>",
  "reply_to": "<id da mensagem original ou null>",
  "metadata": { ... },
  "timestamp": <unix epoch>
}

Assinatura HMAC opcional

Define a env var CAPTAIN_HTTP_CALLBACK_SECRET em ~/.hermes/.env (ou no shell do Hermes). Quando set, o plugin assina cada POST com HMAC-SHA256(secret, body) no header X-Hermes-Callback-Signature. O backend valida a assinatura antes de processar.

# em ~/.hermes/.env
CAPTAIN_HTTP_CALLBACK_SECRET=<gere com: openssl rand -hex 32>

Limitações

Send-only. Não recebe mensagens. A entrada da conversa precisa vir via outro adapter (geralmente o webhook adapter built-in).
Resposta esperada: o backend precisa aceitar POST JSON e responder 2xx. Plugin loga warning em qualquer status >= 300 e retorna falha pro Hermes.
Timeout default: 15s. Configurável via extra.timeout_seconds no config.yaml.
Sem retry built-in. Se o backend retornar erro, é falha — o Hermes pode escolher logar e seguir. Adicione retry no backend caller se precisar.