From e511281f6419417ec2734733e1841fcce1b79ac4 Mon Sep 17 00:00:00 2001 From: Rui Date: Thu, 7 May 2026 23:32:23 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20adicionado=20protocolo=20de=20coordena?= =?UTF-8?q?=C3=A7=C3=A3o=20de=20multi-agentes=20PGS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- protocolo_agentes.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 protocolo_agentes.md diff --git a/protocolo_agentes.md b/protocolo_agentes.md new file mode 100644 index 0000000..8232da5 --- /dev/null +++ b/protocolo_agentes.md @@ -0,0 +1,72 @@ +# 🤖 Protocolo Gitea Swarm (PGS): Coordenação de Multi-Agentes em Ambiente Multi-VPS + +Este documento estabelece o protocolo de comunicação padrão, obrigatório e imutável para todos os Agentes de Inteligência Artificial (IAs) que atuarem no gerenciamento, desenvolvimento ou manutenção da infraestrutura do **Clube67** distribuída em múltiplos servidores. + +Como a arquitetura adota segurança **Zero-Trust de movimentação lateral** (impedindo que agentes em uma VPS acessem outras máquinas via SSH automático), o **Gitea** atua como o **Orquestrador de Estado Assíncrono** do enxame de agentes. + +--- + +## 📋 Regras de Engajamento para Agentes + +Sempre que um agente for invocado para resolver uma Issue ou realizar uma implementação, ele deve obrigatoriamente seguir os 4 passos de ciclo de vida abaixo: + +```mermaid +graph TD + A[1. Autocognição: Onde estou?] --> B[2. Leitura de Histórico na Issue] + B --> C[3. Execução Local na VPS Atual] + C --> D[4. Comentário de Hand-off e Status] +``` + +--- + +### 🔍 Passo 1: Autocognição (Em qual VPS estou?) +Toda IA, ao iniciar sua execução, deve identificar em qual máquina física ou container está rodando, executando comandos como `hostname` ou inspecionando o IP da VPN WireGuard local. +* *Exemplo:* "Identificado que estou rodando na **VPS 3 (Data Server - 10.99.0.3)**." + +### 📖 Passo 2: Leitura do Histórico da Issue +Antes de fazer qualquer alteração no código ou nos servidores, o agente deve ler a Issue no Gitea de baixo para cima, analisando o histórico de comentários de outros agentes para entender o que já foi feito e onde o processo parou. + +### 🛠️ Passo 3: Execução Local Estrita +O agente deve realizar apenas as alterações correspondentes à VPS onde ele está ativamente rodando. Ele **nunca** deve tentar forçar conexões ou invasões a outras VPSs que não estejam documentadas ou autorizadas. + +### 💬 Passo 4: Comentário de Hand-off (O Passe de Bastão) +Ao concluir sua tarefa local, o agente **não deve simplesmente fechar a tarefa**, caso ela dependa de ações em outros servidores. Ele deve postar um comentário estruturado seguindo o modelo abaixo: + +--- + +## 📝 Modelo Padrão de Comentário de Hand-off ( PGS ) + +O comentário de encerramento do agente na Issue deve conter obrigatoriamente os seguintes blocos: + +```markdown +### 🖥️ [VPS ATUAL]: [Nome da VPS, ex: VPS 3 (Data Appliance)] +* **O que foi realizado localmente:** [Lista clara de arquivos modificados, bancos criados ou serviços configurados]. +* **Impacto na Rede:** [Portas abertas na VPN, novas credenciais disponíveis, ex: 'Banco criado com a senha X']. + +### ⏭️ [AÇÃO REQUERIDA NA VPS DESTINO]: [Nome da VPS, ex: VPS 1 (App Server)] +* **Instruções passo a passo para o próximo agente:** [Instruções exatas do que deve ser feito na outra VPS, códigos YAML, bash ou edições de arquivo]. +* **Como se conectará à VPS atual:** [Mostrar a URL de conexão, ex: 'DATABASE_URL=postgresql://...']. + +### 🚦 [STATUS]: [Escolha uma das tags abaixo] +* `[Aguardando Agente na VPS X]` - Quando o trabalho local acabou e agora outro agente precisa agir na VPS X. +* `[Aguardando Homologação do Usuário]` - Quando todo o cluster foi configurado e o Humano precisa testar e aprovar. +``` + +--- + +## 🎯 Exemplo de Aplicação Real (Issue #2 - newwhats) + +1. **Agente A (na VPS 3 - Banco):** + * Cria o banco `newwhats` e configura DragonflyDB. + * Comenta na Issue: + > **[VPS 3 - Data Appliance]:** Banco `newwhats` restaurado com sucesso. + > **[REQUERIDO NA VPS 1]:** Próximo agente, edite o `docker-compose.yml` da aplicação apontando para `10.99.0.3` usando a senha `X`. Comente quando terminar. + > **[STATUS]:** `[Aguardando Agente na VPS 1]` +2. **Agente B (na VPS 1 - Frontend):** + * Inicia na VPS 1, lê o comentário acima, altera o `docker-compose.yml` local e sobe o container. + * Comenta na Issue: + > **[VPS 1 - App Server]:** docker-compose.yml atualizado e container reiniciado. Conexão com VPS 3 validada e healthy. + > **[STATUS]:** `[Aguardando Homologação do Usuário]` + +--- +*Este protocolo garante consistência, segurança máxima e clareza absoluta na comunicação humana e de inteligência artificial em nosso ecossistema.*