minions-ai-agents/docs/DEVELOPER_GUIDE.md

📖 Antigravity Brain - Documentação para Desenvolvedores

Guia completo para desenvolvedores e agentes de IA trabalhando neste projeto.

📑 Índice

1. Visão Geral da Arquitetura
2. Adicionando Novos Agentes
3. Adicionando Novas Crews
4. Adicionando Novas Ferramentas
5. Referência de Configuração
6. Sistema de Memória
7. Diretrizes para Agentes de IA

---

🏗️ Visão Geral da Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                        Interface Web Chainlit                    │
│                      (src/app.py:8000)                          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Roteador Inteligente                        │
│                    (src/router.py)                               │
│         Classifica intenção do usuário → Roteia para Crew        │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ Crew Infra  │   │ Crew        │   │ Crew RH/    │
│             │   │ Segurança   │   │ Evolução    │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Fábrica de Agentes                          │
│                  (src/agents/factory.py)                         │
│      Carrega Persona → Injeta Conhecimento → Cria Agente         │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Persona   │   │ Conhecimento│   │ Ferramentas │
│    (.md)    │   │   Padrões   │   │  (Python)   │
└─────────────┘   └─────────────┘   └─────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Memória Compartilhada (Mem0)                     │
│                   (src/memory/wrapper.py)                        │
│              Qdrant Vector DB + HuggingFace Embeddings           │
└─────────────────────────────────────────────────────────────────┘

Arquivos Principais

Arquivo	Propósito
src/app.py	Ponto de entrada Chainlit, gerencia chat
src/router.py	Roteia requisições para crew apropriada
src/config.py	Configuração LLM & Memória
src/agents/factory.py	Cria agentes a partir de arquivos de persona
src/crews/definitions.py	Define composições de crews
src/memory/wrapper.py	Integração Mem0 com rate limiting

---

🤖 Adicionando Novos Agentes

Passo 1: Criar Arquivo de Persona

Crie src/agents/personas/persona-<nome>.md:

---
description: Descrição curta do agente
llm_config:
  provider: default  # ou: openai, gemini, ollama
---

# 👤 Persona: Nome do Agente

**Papel:** O cargo do agente
**Objetivo:** O que o agente busca alcançar

## 🧠 História

Personalidade e histórico detalhados. Isto se torna o
prompt de sistema do agente. Escreva na voz do personagem.

## 📋 Protocolo

1. Primeiro passo de como este agente trabalha
2. Segundo passo...

Passo 2: Registrar na Fábrica (Opcional)

Se o agente precisa de ferramentas especiais, atualize src/crews/definitions.py:

from src.agents.factory import AgentFactory
from src.tools.sua_tool import SuaTool

agent = AgentFactory.create_agent(
    "seu-agente-nome",  # corresponde ao nome do arquivo
    specific_tools=[SuaTool()],
    model_tier="smart"  # ou "fast"
)

Convenção de Nomenclatura

• Nome do arquivo: persona-<minusculo-hifenizado>.md
• Exemplo: persona-bob-builder.md

---

👥 Adicionando Novas Crews

Passo 1: Definir Crew em definitions.py

Edite src/crews/definitions.py:

elif crew_name == "Sua Nova Crew":
    # Criar agentes
    agent1 = AgentFactory.create_agent("agente-um", model_tier="smart")
    agent2 = AgentFactory.create_agent("agente-dois", model_tier="fast")
    
    # Definir tarefas
    task1 = Task(
        description=f"Fazer algo com: '{inputs.get('topic')}'",
        expected_output="Descrição do resultado esperado",
        agent=agent1
    )
    
    task2 = Task(
        description="Revisar o trabalho anterior",
        expected_output="Aprovação ou feedback",
        agent=agent2
    )
    
    # Retornar crew
    return Crew(
        agents=[agent1, agent2],
        tasks=[task1, task2],
        process=Process.sequential,
        verbose=True
    )

Passo 2: Registrar no Roteador

Edite o prompt em src/router.py:

prompt = f"""
CREWS DISPONÍVEIS:
...
6. 'Sua Nova Crew': Descrição de quando usar esta crew.
"""

Passo 3: Adicionar à Lista de Crews

Em src/crews/definitions.py:

@staticmethod
def get_available_crews():
    return [
        ...
        "Sua Nova Crew",
    ]

---

🔧 Adicionando Novas Ferramentas

Passo 1: Criar Arquivo de Ferramenta

Crie src/tools/suas_tools.py:

from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class SuaToolInput(BaseModel):
    """Schema de entrada - DEVE ter docstring e descrições Field."""
    param1: str = Field(..., description="Para que serve este parâmetro")
    param2: int = Field(default=10, description="Opcional com valor padrão")

class SuaTool(BaseTool):
    name: str = "Nome da Sua Ferramenta"
    description: str = (
        "Descrição detalhada do que esta ferramenta faz. "
        "O agente lê isto para decidir quando usar."
    )
    args_schema: type = SuaToolInput

    def _run(self, param1: str, param2: int = 10) -> str:
        try:
            # Sua lógica aqui
            result = fazer_algo(param1, param2)
            return f"Sucesso: {result}"
        except Exception as e:
            # NUNCA lance exceção, sempre retorne string de erro
            return f"Erro: {str(e)}"

Diretrizes de Ferramentas

1. Sempre capture exceções - Retorne strings de erro, nunca lance
2. Docstrings descritivas - Agentes usam estas para entender o uso
3. Type hints obrigatórios - Todos os parâmetros precisam de tipos
4. Retorne strings - Resultados narrativos, não JSON bruto

---

⚙️ Referência de Configuração

Variáveis .env

# Provedor LLM: gemini, openai, anthropic, ollama
LLM_PROVIDER=gemini

# Nomes de modelos (usados para agentes e memória)
LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17
LLM_MODEL_SMART=gemini-2.5-flash-lite-preview-06-17

# Chaves de API (apenas a que corresponde ao seu provedor)
GEMINI_API_KEY=sua-chave
OPENAI_API_KEY=sua-chave
ANTHROPIC_API_KEY=sua-chave

# Configuração de Memória
MEMORY_PROVIDER=qdrant          # qdrant (local) ou mem0 (nuvem)
MEMORY_EMBEDDING_PROVIDER=local # local, openai, ou gemini
QDRANT_HOST=qdrant              # Nome do serviço Docker
QDRANT_PORT=6333
MEMORY_PROJECT_ID=seu_projeto   # Namespace para memórias

Níveis de Modelo

• smart: Usado para raciocínio complexo (estratégia, arquitetura)
• fast: Usado para tarefas rápidas (classificação, respostas simples)

---

🧠 Sistema de Memória

Como Funciona

1. Todos os agentes têm acesso a SearchMemoryTool e SaveMemoryTool
2. Memórias são armazenadas no banco de dados vetorial Qdrant
3. Mem0 usa LLM para extrair fatos e embeddings para busca

Rate Limiting

O sistema de memória tem proteção integrada:

• Máximo 50 chamadas/minuto
• 3 tentativas com backoff exponencial
• Degradação graciosa (continua sem memória se indisponível)

Escopo de Memória

Todas as memórias são escopadas para MEMORY_PROJECT_ID. Altere isto para isolar diferentes projetos.

---

🤖 Diretrizes para Agentes de IA

Para Agentes de IA Trabalhando Neste Código

LEIA ANTES DE FAZER ALTERAÇÕES

1. Carregue Conhecimento Primeiro

   • Leia src/knowledge/standards/*.md antes de escrever código
   • Estes são A LEI para estilo de código e padrões

2. Nunca Hardcode

   • Use Config.get_llm_config() para configurações LLM
   • Use Config.get_mem0_config() para configurações de memória
   • Use variáveis de ambiente para segredos

3. Tratamento de Erros

   • Ferramentas NUNCA devem lançar exceções
   • Sempre retorne strings de erro descritivas
   • Use rate limiting para APIs externas

4. Adicionando Agentes

   • Crie arquivo de persona primeiro
   • Teste se o agente carrega: AgentFactory.create_agent("nome")
   • Adicione à crew apenas depois que a persona funcionar

5. Testando Alterações

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

6. Convenção de Commit

   feat: Adicionar nova funcionalidade
   fix: Correção de bug
   docs: Documentação
   refactor: Limpeza de código
   

---

📁 Referência de Diretórios

src/
├── agents/
│   ├── factory.py          # Lógica de criação de agentes
│   └── personas/           # Arquivos de personalidade de agentes
│       ├── persona-arthur-mendes.md
│       ├── persona-gus-fring.md
│       └── ... (26 agentes)
├── crews/
│   └── definitions.py      # Composições de crews
├── knowledge/
│   └── standards/          # Base de conhecimento corporativo
│       ├── docker_standards.md
│       ├── python_tool_standards.md
│       └── ... (16 padrões)
├── memory/
│   └── wrapper.py          # Mem0 + rate limiting
├── tools/
│   ├── base.py             # Ferramentas de sistema de arquivos
│   ├── evolution.py        # SpawnAgent, LearnPolicy
│   └── zabbix.py           # Ferramentas de validação Zabbix
├── app.py                  # Entrada Chainlit
├── config.py               # Hub de configuração
└── router.py               # Roteamento inteligente

---

🚀 Comandos Rápidos

# Iniciar aplicação
docker-compose up -d

# Ver logs
docker logs antigravity_brain -f

# Reiniciar após alterações
docker-compose restart app

# Reconstruir container
docker-compose build --no-cache app

# Acessar dashboard Qdrant
open http://localhost:6333/dashboard

---

Feito com ❤️ pela ITGuys | Última Atualização: 2026-01-07