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

```python
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:
```python
return f"Erro: Arquivo '{path}' não encontrado"  # {path} interpretado como template
```

✅ CORRETO:
```python
return f"Erro: Arquivo 'PATH_VAR' não encontrado"  # Escapado
```

### 2. Rate Limiting Ausente

❌ ERRADO:
```python
while True:
    api.call()  # Queima cota instantaneamente
```

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

### 3. Configuração Hardcoded

❌ ERRADO:
```python
model = "gpt-4"
api_key = "sk-xxx"
```

✅ CORRETO:
```python
config = Config.get_llm_config(mode="smart")
```

---

## 🧪 Protocolo de Teste

1. **Teste local:**
   ```bash
   docker-compose restart app
   docker logs antigravity_brain --tail 50
   ```

2. **Verificar ausência de erros:**
   ```bash
   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:**
   ```bash
   git add .
   git commit -m "feat: Descrição"
   git push
   ```

2. **No servidor de produção:**
   ```bash
   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.