374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# 📖 Antigravity Brain - Documentação para Desenvolvedores
|
|
|
|
Guia completo para desenvolvedores e agentes de IA trabalhando neste projeto.
|
|
|
|
## 📑 Índice
|
|
|
|
1. [Visão Geral da Arquitetura](#visão-geral-da-arquitetura)
|
|
2. [Adicionando Novos Agentes](#adicionando-novos-agentes)
|
|
3. [Adicionando Novas Crews](#adicionando-novas-crews)
|
|
4. [Adicionando Novas Ferramentas](#adicionando-novas-ferramentas)
|
|
5. [Referência de Configuração](#referência-de-configuração)
|
|
6. [Sistema de Memória](#sistema-de-memória)
|
|
7. [Diretrizes para Agentes de IA](#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`:
|
|
|
|
```markdown
|
|
---
|
|
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`:
|
|
|
|
```python
|
|
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`:
|
|
|
|
```python
|
|
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`:
|
|
|
|
```python
|
|
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`:
|
|
|
|
```python
|
|
@staticmethod
|
|
def get_available_crews():
|
|
return [
|
|
...
|
|
"Sua Nova Crew",
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Adicionando Novas Ferramentas
|
|
|
|
### Passo 1: Criar Arquivo de Ferramenta
|
|
|
|
Crie `src/tools/suas_tools.py`:
|
|
|
|
```python
|
|
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
|
|
|
|
```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**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|