89b471831d
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>
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pkill -f "hermes.*gateway" && sleep 2
|
|
nohup hermes gateway run --replace > /var/log/hermes-gateway.log 2>&1 &
|
|
```
|
|
|
|
Verifique:
|
|
|
|
```bash
|
|
hermes plugins list | grep http_callback
|
|
```
|
|
|
|
## Uso
|
|
|
|
Cria webhook subscription apontando para este deliver type:
|
|
|
|
```bash
|
|
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
|
|
|
|
```http
|
|
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)
|
|
|
|
```
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
# 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.
|