minions-ai-agents/docs/AI_AGENT_PROTOCOL.md

🤖 Protocolo para Agentes de IA

LEIA ISTO ANTES DE TRABALHAR NO CÓDIGO

Este documento define os protocolos obrigatórios para agentes de IA trabalhando no projeto Antigravity Brain.

---

🎯 Diretivas Primárias

1. LEIA O CONHECIMENTO PRIMEIRO - Antes de escrever QUALQUER código, leia os src/knowledge/standards/*.md relevantes
2. NUNCA HARDCODE SEGREDOS - Use a classe Config e variáveis de ambiente
3. FERRAMENTAS NÃO DEVEM LANÇAR EXCEÇÕES - Sempre retorne strings de erro, nunca raise exceptions
4. TESTE ANTES DE COMMITAR - Verifique alterações com docker-compose restart app

---

📖 Leitura Obrigatória por Tipo de Tarefa

Tarefa	Deve Ler Primeiro
Ferramentas Python	python_tool_standards.md
Alterações Docker	docker_standards.md
Novos agentes	DEVELOPER_GUIDE.md#adicionando-novos-agentes
Banco de dados	database_standards.md
Segurança	security_standards.md
Operações Git	git_standards.md
Alterações de UI	ui_ux_standards.md

---

✅ Checklist de Alteração de Código

Antes de fazer qualquer alteração:

• Ler arquivo de padrões relevante
• Verificar se o padrão já existe no código
• Planejar alteração com impacto mínimo
• Adicionar tratamento de erros
• Testar localmente

Após fazer a alteração:

• Reiniciar container: docker-compose restart app
• Verificar logs por erros: docker logs antigravity_brain --tail 50
• Verificar se a funcionalidade funciona
• Commitar com formato de mensagem adequado

---

📝 Formato de Mensagem de Commit

<tipo>: <descrição curta>

<corpo opcional>

Tipos:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Documentação
• refactor: Limpeza de código
• test: Testes
• chore: Manutenção

Exemplo:

feat: Adicionar nova persona de agente DevOps

- Criado persona-devops-dan.md
- Adicionado à crew de Infraestrutura
- Atribuídas ferramentas Docker

---

🔧 Protocolo de Desenvolvimento de Ferramentas

class MinhaTool(BaseTool):
    name: str = "Nome Descritivo"  # Agente lê isto
    description: str = (
        "Descrição DETALHADA de quando usar esta ferramenta. "
        "Inclua exemplos de entrada e saídas esperadas."
    )
    args_schema: type = MinhaToolInput  # Modelo Pydantic com descrições Field

    def _run(self, **kwargs) -> str:
        try:
            # Sua lógica
            return "Sucesso: ..."
        except ErroEspecifico as e:
            return f"Erro: Tratamento específico para {e}"
        except Exception as e:
            return f"Erro: Inesperado - {str(e)[:100]}"

NUNCA:

• Use input() para interação com usuário
• Lance exceções
• Retorne JSON bruto (use texto narrativo)
• Use type hints Any

---

🤖 Protocolo de Desenvolvimento de Agentes

Arquivos de Persona

1. Use frontmatter YAML para metadados
2. Inclua campos **Papel:** e **Objetivo:**
3. Escreva backstory na voz do personagem
4. Defina protocolos/procedimentos claros

Atribuição de Ferramentas

• Atribua apenas ferramentas que o agente realmente precisa
• Considere model_tier: ferramentas que requerem raciocínio → smart
• Ferramentas de memória são auto-atribuídas a todos os agentes

---

📁 Regras de Localização de Arquivos

Tipo de Conteúdo	Localização
Personas de agentes	src/agents/personas/persona-*.md
Ferramentas	src/tools/*.py
Padrões de conhecimento	src/knowledge/standards/*.md
Conhecimento dinâmico	src/knowledge/dynamic/*/*.md
Definições de crew	src/crews/definitions.py
Configuração	src/config.py

---

⚠️ Erros Comuns a Evitar

1. Nomes de Variáveis em Padrões

❌ ERRADO:

return f"Erro: Arquivo '{path}' não encontrado"  # {path} interpretado como template

✅ CORRETO:

return f"Erro: Arquivo 'PATH_VAR' não encontrado"  # Escapado

2. Rate Limiting Ausente

❌ ERRADO:

while True:
    api.call()  # Queima cota instantaneamente

✅ CORRETO:

for attempt in range(MAX_RETRIES):
    result = api.call()
    if success: break
    time.sleep(DELAY * (2 ** attempt))

3. Configuração Hardcoded

❌ ERRADO:

model = "gpt-4"
api_key = "sk-xxx"

✅ CORRETO:

config = Config.get_llm_config(mode="smart")

---

🧪 Protocolo de Teste

1. Teste local:

   docker-compose restart app
   docker logs antigravity_brain --tail 50
   

2. Verificar ausência de erros:

   docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
   

3. Teste interativo:

   • Abra http://localhost:8000
   • Envie mensagem de teste
   • Verifique roteamento correto de crew
   • Confira resposta do agente

---

🚀 Protocolo de Deploy

1. Commitar alterações:

   git add .
   git commit -m "feat: Descrição"
   git push
   

2. No servidor de produção:

   git pull
   docker-compose build --no-cache app
   docker-compose up -d
   

---

Lembre-se: Qualidade acima de velocidade. Leia os padrões. Teste suas alterações.