Integração com hosts ACP

O Hermes Agent pode rodar como servidor ACP, deixando hosts compatíveis com ACP conversarem com o Hermes por stdio. Os editores conseguem renderizar:

• mensagens de conversa
• atividade de ferramentas
• diffs de arquivo
• comandos de terminal
• pedidos de aprovação
• pedaços de raciocínio e de resposta em streaming

Outros hosts podem usar o mesmo protocolo para rotear eventos de colaboração para dentro do Hermes. O ACP cai bem quando você quer que o Hermes mantenha a identidade, a configuração de provedor, a memória, as skills e as ferramentas que já tem, enquanto outro aplicativo cuida do transporte da conversa.

O que o Hermes expõe no modo ACP

O Hermes roda com um conjunto de ferramentas curado, o hermes-acp, pensado para fluxos de editor. Ele inclui:

• ferramentas de arquivo: read_file, write_file, patch, search_files
• ferramentas de terminal: terminal, process
• ferramentas de web/navegador
• memória, lista de tarefas, busca em sessões
• skills
• execute_code e delegate_task
• visão

Ele deixa de fora, de propósito, o que não combina com a experiência típica de um editor, como a entrega de mensagens e o gerenciamento de tarefas de cron.

Instalação

Instale o Hermes normalmente e depois adicione o extra de ACP a partir do checkout de instalação:

cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'

Isso instala a dependência agent-client-protocol e habilita:

• hermes acp
• hermes-acp
• python -m acp_adapter

Subir o servidor ACP

Qualquer um destes comandos inicia o Hermes em modo ACP:

hermes acp

hermes-acp

python -m acp_adapter

O Hermes escreve os logs no stderr, para que o stdout fique reservado ao tráfego JSON-RPC do ACP.

Para verificações não interativas:

hermes acp --version
hermes acp --check

Ferramentas de navegador (opcional)

As ferramentas de navegador (browser_navigate, browser_click etc.) dependem do pacote npm agent-browser e do Chromium, que não fazem parte do wheel Python. Instale com:

hermes acp --setup-browser           # interativo (pergunta antes de baixar uns 400 MB)
hermes acp --setup-browser --yes     # aceita o download sem interação

Este é o comando avulso. O fluxo de autenticação por terminal (hermes acp --setup) também oferece a preparação do navegador como pergunta seguinte, depois da escolha do modelo, então a maioria das pessoas nunca precisa rodar --setup-browser direto.

O que ele faz:

• Instala o Node.js 26 em ~/.hermes/node/, se não houver
• Roda npm install -g agent-browser @askjo/camofox-browser nesse prefixo (sem precisar de sudo — o --prefix do npm aponta para o Node gerenciado pelo Hermes, com permissão de escrita do usuário)
• Instala o Chromium do Playwright, ou usa um Chrome/Chromium do sistema quando encontrar um

A preparação é idempotente — rodar de novo é rápido e pula o que já está feito.

Configuração do host

Canais do Buzz (ponte de relay)

O Buzz é uma plataforma de colaboração baseada em Nostr para pessoas e agentes. O harness buzz-acp dele conecta canais do Buzz a qualquer agente ACP por stdio:

Relay do Buzz <-- WebSocket --> buzz-acp <-- ACP por stdio --> Hermes Agent

Isto é uma integração de transporte, não uma segunda instalação do Hermes. O subprocesso lançado pelo buzz-acp usa a mesma configuração, credenciais, memória, skills e estado do Hermes que o hermes daquela máquina.

(Isso é diferente do runtime gerenciado do Buzz Desktop, que sobe o Hermes localmente como um harness predefinido. A ponte de relay serve para entrar em canais do Buzz como uma identidade de agente, tipicamente em um servidor.)

Pré-requisitos:

• Conclua a instalação do ACP e o hermes acp --check descritos acima.
• Compile o buzz-acp e a CLI buzz a partir do repositório do Buzz (cargo build --release -p buzz-acp).
• Gere um par de chaves Nostr dedicado ao Hermes (buzz-admin generate-key) e registre-o como membro do relay (buzz-admin add-member). Cada agente precisa da própria identidade — não reaproveite o par de chaves de uma pessoa.
• Adicione essa identidade aos canais do Buzz pretendidos.

Suba uma ponte com:

export BUZZ_RELAY_URL="wss://community.example.com"
export BUZZ_PRIVATE_KEY="..."
export BUZZ_API_TOKEN="..."
export BUZZ_ACP_AGENT_COMMAND="hermes"
export BUZZ_ACP_AGENT_ARGS="acp"

buzz-acp

A BUZZ_API_TOKEN só é necessária quando o relay exige autenticação por token. Não versione nem cole a chave privada ou o token de API.

Para uma implantação persistente em servidor, rode o buzz-acp sob um gerenciador de serviços, com o mesmo usuário de sistema operacional dono do diretório home pretendido do Hermes. Configuração, geração de chave, descoberta de canais e opções por agente estão documentadas no README do buzz-acp.

A ponte descobre todo canal do Buzz em que a identidade do Hermes é membro e se inscreve automaticamente quando é adicionada a outro canal. A associação aos canais do Buzz continua sendo, portanto, a fronteira de acesso; o Hermes não precisa de uma lista separada de canais na própria configuração.

Para expor a atividade do Hermes por ACP no Buzz Desktop do dono, adicione:

export BUZZ_ACP_RELAY_OBSERVER="true"

Isso publica quadros de observador criptografados do tipo 24200, endereçados ao dono do agente (o NIP-AO do Buzz). O Desktop renderiza o fluxo ao vivo de ciclo de vida, ferramentas, respostas e uso no Activity log do agente. O relay trata esses quadros como efêmeros, então o Desktop precisa estar on-line antes de o turno começar; o arquivo local de observador dele é o histórico durável do lado do dono.

As pontes headless respondem sozinhas aos pedidos de permissão do ACP, porque não há editor presente para mostrar as caixas de aprovação — veja Deixe os agentes do Buzz só para o dono. Trate a ponte como automação privilegiada: use uma conta de sistema operacional dedicada, restrinja quais usuários do Buzz podem falar com o agente (o buzz-acp tem um controle de resposta só para o dono, via BUZZ_ACP_AGENT_OWNER) e conceda associação apenas nos canais em que se espera que o Hermes trabalhe.

VS Code

Instale a extensão ACP Client.

Para conectar:

1. Abra o painel do ACP Client pela Activity Bar.
2. Escolha Hermes Agent na lista de agentes embutidos.
3. Conecte e comece a conversar.

Se você quiser definir o Hermes na mão, adicione-o pelas configurações do VS Code em acp.agents:

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Configure o Hermes como servidor de agente personalizado nas configurações do Zed:

1. Abra o Agent Panel.
2. Adicione um servidor de agente personalizado com a configuração a seguir:

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

3. Comece uma thread nova de agente externo do Hermes.

Pré-requisitos:

• Configure antes as credenciais de provedor do Hermes com hermes model, ou defina-as em ~/.hermes/.env / ~/.hermes/config.yaml.

JetBrains

Use um plugin compatível com ACP e aponte-o para hermes acp ou hermes-acp.

Buzz Desktop

O Buzz traz o Hermes Agent como runtime predefinido. Com o Hermes instalado do jeito normal, o Buzz o descobre sozinho — abra Settings → Runtimes e o Hermes aparece entre os seus runtimes.

Se a descoberta falhar (instalações mais antigas), garanta que o lançador de ACP seja resolvido no PATH de um shell de login:

command -v hermes-acp || command -v hermes

As instalações recentes escrevem tanto o lançador hermes quanto o hermes-acp em ~/.local/bin; rodar hermes update adiciona o lançador hermes-acp às instalações antigas. Como alternativa manual, configure o comando de agente do Buzz como hermes com os args ["acp"].

Seletor de modelo

O Buzz Desktop (v0.5.1+) renderiza o menu completo de modelos do Hermes nas configurações de runtime do agente. A lista vem do próprio Hermes, por ACP: ela mostra todo modelo dos provedores em que você se autenticou no Hermes (o mesmo inventário por trás do hermes model e do comando /model), então um modelo que falta no menu significa que o provedor dele não tem credencial configurada do lado do Hermes.

Os IDs de entrada têm o formato provider:model (por exemplo, openrouter:z-ai/glm-5.1), ou custom:<nome>:<modelo> para endpoints personalizados compatíveis com a OpenAI definidos no config.yaml. Escolher um modelo vale para a sessão daquele agente; não muda o seu padrão global do Hermes — para isso, use o hermes model.

Deixe os agentes do Buzz só para o dono

O Buzz cria todo agente com Who can talk to this agent definido como Owner only. Deixe assim quando o runtime for o Hermes.

Dois comportamentos se somam nesse caminho. O conjunto de ferramentas hermes-acp inclui terminal e execute_code, e a ponte ACP do Buzz responde sozinha aos pedidos de permissão do Hermes com allow_once, em vez de mostrá-los. Um agente Hermes no Buzz, portanto, roda comandos de shell na máquina sem perguntar. Pedi para um deles rodar rm -rf em um diretório descartável e ele apagou, sem pedir nada a ninguém.

Escolher Anyone entrega esse mesmo acesso de shell a todo autor que alcance o canal. O Buzz não avisa quando você escolhe isso.

Nenhuma das duas mitigações óbvias funciona hoje:

• approvals.mode: manual até faz o Hermes levantar o pedido de permissão, mas o Buzz aprova sozinho e o comando roda mesmo assim.
• platform_toolsets.acp não reduz o conjunto de ferramentas do ACP, então não dá para usá-lo para tirar o terminal.

O !shutdown vindo do dono para o agente em qualquer modo, e o Buzz ignora esse comando quando vem de qualquer outra pessoa.

Configuração e credenciais

O modo ACP usa a mesma configuração do Hermes que a CLI:

• ~/.hermes/.env
• ~/.hermes/config.yaml
• ~/.hermes/skills/
• ~/.hermes/state.db

A resolução de provedor usa o resolvedor de runtime normal do Hermes, então o ACP herda o provedor e as credenciais configuradas no momento. O Hermes também anuncia um método de autenticação por terminal (--setup) para clientes ACP em primeira execução; isso abre a configuração interativa de modelo/provedor do Hermes.

Integração com o host

Estas variáveis são definidas por um processo host de ACP (um editor ou outro harness de agente) no subprocesso do Hermes que ele sobe. Não são configuração de usuário — não as defina na mão no .env nem no config.yaml.

Variável	Valor	Efeito
HERMES_ACP_SKIP_CONFIGURED_MCP	1	Não sobe os servidores MCP configurados globalmente no config.yaml antes de o laço JSON-RPC do ACP começar.

Normalmente o Hermes sobe todo servidor MCP configurado no config.yaml antes de entrar no laço JSON-RPC do ACP. Um host que cuida do MCP por conta própria — passando os servidores da sessão explicitamente pelo session/new — não precisa dessa subida global, e um servidor MCP lento ou interativo sem relação nenhuma atrasaria o initialize. Definir o marcador como exatamente 1 deixa esse host pular a etapa.

Só a descoberta global do config.yaml é pulada. Os servidores MCP fornecidos pela sessão ACP através do session/new continuam sendo registrados, então o host não perde nenhuma capacidade que tenha pedido. Qualquer outro valor (não definido, vazio, 0, false) mantém o comportamento padrão, para que uma string qualquer de aparência verdadeira não desabilite o MCP em silêncio.

Comportamento da sessão

As sessões de ACP são acompanhadas pelo gerenciador de sessões em memória do adaptador de ACP enquanto o servidor está rodando.

Cada sessão guarda:

• ID da sessão
• diretório de trabalho
• modelo escolhido
• histórico atual da conversa
• evento de cancelamento

O AIAgent por baixo continua usando os caminhos normais de persistência e log do Hermes, mas o list/load/resume/fork do ACP tem escopo limitado ao processo do servidor ACP em execução.

Comportamento do diretório de trabalho

As sessões de ACP amarram o cwd do editor ao ID de tarefa do Hermes, para que as ferramentas de arquivo e de terminal rodem em relação ao espaço de trabalho do editor, e não ao cwd do processo do servidor.

Aprovações

Comandos perigosos de terminal podem ser devolvidos ao editor como pedidos de aprovação. As opções de aprovação do ACP são mais simples que o fluxo da CLI:

• permitir uma vez
• permitir sempre
• negar

Se você vai mesmo ver um pedido depende do host. O host pode responder ao pedido programaticamente em vez de mostrá-lo a você, e nesse caso essas opções existem no protocolo mas nunca chegam a uma pessoa. O Buzz Desktop faz isso, então trate esse caminho como execução sem supervisão, independentemente da sua configuração de approvals.

Em caso de tempo esgotado ou erro, a ponte de aprovação nega o pedido.

Aprovação automática de edições no escopo da sessão

O ACP expõe um terceiro nível entre permitir uma vez e permitir sempre: Allow for session. Escolher essa opção no pedido de permissão do editor registra a aprovação só dentro da sessão ACP atual — todo comando correspondente dali em diante passa sem perguntar naquela sessão, mas uma sessão ACP nova (ou reiniciar o editor) zera tudo e volta a perguntar na primeira vez.

Opção	Rótulo no editor	Escopo	Sobrevive a reinícios
allow_once	Allow once	Só esta chamada de ferramenta	Não
allow_session	Allow for session	Todas as chamadas correspondentes nesta sessão ACP	Não — some quando a sessão termina
allow_always	Allow always	Todas as sessões futuras	Sim (é escrito na lista permanente de permissões do Hermes)
deny	Deny	Só esta chamada de ferramenta	Não

O allow_session é o padrão certo para um fluxo de editor em que você confia no agente pela duração de uma tarefa mas não quer conceder uma entrada duradoura na lista de permissões. O compromisso de segurança é direto: quanto mais amplo o escopo, menos o editor interrompe você, e mais estrago um agente que se comporta mal (ou uma injeção de prompt) consegue fazer antes de você perceber. Comece com allow_once em comandos desconhecidos; promova para allow_session depois de ver o agente rodar o mesmo padrão corretamente algumas vezes; reserve o allow_always para comandos de fato idempotentes em que você confia para sempre (por exemplo, git status).

A ponte ACP mapeia essas opções na semântica interna de aprovação do Hermes — o allow_always escreve uma entrada permanente na lista de permissões do mesmo jeito que a CLI, enquanto o allow_session só afeta o cache de aprovação em memória da sessão ACP atual.

Resolução de problemas

O agente ACP não aparece no editor

Confira:

• Em desenvolvimento manual/local, verifique se o comando do host aponta para hermes acp.
• O Hermes está instalado e no seu PATH.
• O extra de ACP está instalado (cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]').

O ACP inicia mas dá erro na hora

Tente estas verificações:

hermes acp --version
hermes acp --check
hermes doctor
hermes status

Faltam credenciais

O modo ACP usa a configuração de provedor que o Hermes já tem. Configure as credenciais com:

hermes model

ou editando o ~/.hermes/.env. O fluxo de autenticação por terminal (hermes acp --setup) também consegue disparar a configuração interativa de provedor/modelo.

Veja também

• Harness ACP do Buzz
• ACP por dentro
• Resolução de runtime de provedores
• Runtime de ferramentas

---