A2A em Duas Máquinas: Fazendo o Hermes de Dois Computadores se Ajudarem

O Hermes em um computador não dá conta do recado e quer que o Hermes de outro computador dê uma força — é pra isso que serve o A2A. Mas quais são as pegadinhas na hora de implantar? Usuários reais já pisaram nessas minas pra você.

Quando Você Realmente Precisa de Duas Máquinas

Primeiro, pense bem numa pergunta: você precisa mesmo de dois computadores, ou só quer que dois agentes trabalhem juntos?

Se os dois agentes moram na mesma máquina, usar delegação ou um quadro de tarefas já resolve — é como no mesmo escritório, é só gritar pro colega da mesa ao lado, sem precisar ligar. O A2A é feito para “entre máquinas / entre processos / entre frameworks”: seu desktop e seu servidor rodam cada um um Hermes, com memórias, ferramentas e credenciais próprias. É aí que você precisa da ponte A2A.

Passos para Começar

Passo 1: Ative a plataforma A2A nas duas máquinas. Na instalação do Hermes, escolha A2A, ou edite o arquivo de configuração para definir gateway.platforms.a2a.enabled como true. A porta padrão é 9900. Esse passo é tipo instalar uma porta com catraca de acesso em cada computador.

Passo 2: Configure o token (a chave da catraca). No servidor, defina A2A_PEER_TOKENS ou A2A_BEARER_TOKEN. Se for só teste local, pode deixar sem token, mas a porta só abre para 127.0.0.1 — como se o crachá de acesso só fosse emitido para moradores do prédio.

Passo 3: Exponha o endereço. Para funcionar entre máquinas, é obrigatório definir A2A_HOST, por exemplo 0.0.0.0 ou o IP da rede local. Esse passo move a porta de “corredor interno” para “fachada na rua”, pra outra máquina conseguir te achar.

Passo 4: Faça o pareamento. No cliente, configure a2a_agents, ou use direto a2a_discover("http://endereço-do-servidor:9900") para ver o Agent Card do outro lado — é como entregar um cartão de visita primeiro, pra confirmar quem é o outro e quais habilidades ele tem.

Passo 5: Valide. Ative o conjunto de ferramentas a2a e use a2a_call para mandar uma tarefa simples de teste. Atenção ao timeout: o cliente usa 330 segundos por padrão, e a janela de resposta do servidor é de 300 segundos. Para tarefas longas, aumente esses valores, senão o serviço é interrompido no meio do caminho por estouro de tempo. Depois de concluir, dê uma olhada no log de auditoria em ~/.hermes/a2a_audit.jsonl.

Caso Real 1: Como é uma Implantação Bem-Sucedida

A documentação oficial descreve um cenário ideal: seu Hermes no desktop entrega uma tarefa para o Hermes no servidor — o servidor tem mais poder de processamento, rede mais estável e um banco de dados mais completo. Por outro lado, o Hermes do servidor também pode mandar tarefas como “consultar um arquivo local” para o desktop. Cada lado tem suas próprias memórias e ferramentas, cada um faz seu trabalho, se descobrem via Agent Card, e a conversa é controlada por contextId, com suporte a múltiplas rodadas.

É como dois departamentos de uma empresa: o de marketing (desktop) precisa de um relatório de análise de dados, manda um e-mail para o de dados (servidor), que faz e devolve. Cada um guarda seus próprios arquivos, sem interferência.

Caso Real 2: Uma Implantação que Falhou

Tem um caso real na comunidade (#82910): um usuário implantou dois nós em dois macOS — um gateway voltado ao usuário + um worker. Parece igual ao caso de sucesso acima, mas deu tudo errado, e no fim o time desativou a implantação.

O problema foi que os papéis de “coordenador” e “worker” não ficaram bem definidos. O agente pai (coordenador) acumulou coisas demais na própria sessão: cada passo do worker, cada resultado intermediário, cada processo de raciocínio voltava para a sessão pai, causando inchaço de contexto — o agente pai ficou afogado em informação e cada vez mais lento. A transcrição entre agentes arrastou a performance geral, e tarefas complexas ainda disparavam loops de recuperação, afundando cada vez mais.

A lição é clara: na colaboração A2A entre máquinas, primeiro desenhe bem a divisão de responsabilidades — quem coordena, quem executa, e a memória de cada um é de cada um. Não jogue tudo na sessão pai; o worker precisa do próprio “caderninho”.

Checklist para Evitar Problemas na Implantação

Colapso de identidade atrás de proxy reverso (#80534/#80779): Se você usa nginx, Ingress do K8s ou CDN como proxy reverso, todos os pares compartilham o mesmo bearer token, e a identidade de todos colapsa para o endereço do proxy. A solução é fazer o proxy repassar o X-Forwarded-For e derivar a identidade real a partir de um proxy confiável. É como a recepção do prédio recebendo encomendas: precisa escrever o destinatário real no pacote, senão tudo fica empilhado na portaria.

Rota rejeitada com múltiplos perfis de configuração (#80884/#80956): Se você usa multiplex_profiles para rodar várias configurações, mensagens A2A de entrada roteadas para um perfil secundário podem ser rejeitadas pela camada de autorização do gateway. A correção é capturar o contexto de segurança do adaptador imutável na inicialização, preservando as políticas de autenticação, confiança, binding e Agent Card de cada perfil. Cada porta precisa da sua própria regra de catraca, não pode compartilhar uma única.

Configuração de timeout: O padrão é 330 segundos no cliente contra 300 no servidor. Para tarefas longas, lembre de ajustar. Senão é como ligação interurbana: a ligação cai antes de você terminar de falar.

Modo worker com limite definido (#82503): Essa é a receita oficial para o inchaço de contexto. Rotas A2A servidas que não são root podem rodar subprocessos de configuração ou workers RPC versionados, com saída limitada, colheita da árvore de processos, cancelamento e terminação exatamente-uma-vez — o worker termina o serviço e encerra, sem despejar todo o processo na sessão pai.

O Que Isso Significa para o Usuário

Implantar A2A em duas máquinas não é só “ligar dois computadores”. É como abrir uma filial: vitrine (Agent Card), catraca (token), divisão de trabalho (quem coordena, quem executa) e depósito (memórias individuais) — tudo precisa estar bem pensado. Uma implantação bem-sucedida faz cada máquina brilhar no que faz de melhor; uma mal-sucedida afoga o coordenador em informação.

Lembre de três coisas: primeiro defina os limites de responsabilidade, depois pense nos detalhes técnicos; proxy reverso exige tratamento de identidade; tarefas longas pedem timeout maior, e tarefas complexas pedem worker com limite definido. Fazendo isso, os Hermes em dois computadores viram bons colegas de verdade, e não parceiros que só atrapalham um ao outro.