minions-ai-agents/docs/TROUBLESHOOTING.md

# 🔥 Guia de Solução de Problemas

Problemas comuns e soluções para o sistema Antigravity Brain.

---

## 🚨 Erros de API

### Erro: 429 RESOURCE_EXHAUSTED (Cota Excedida)

**Sintomas:**
- Agentes presos em loop de retry
- "You exceeded your current quota" nos logs

**Causas:**
- Limite de taxa da API atingido (especialmente com Gemini 2.0-flash-exp: apenas 10 RPM!)
- Ferramentas de memória chamando API muito rapidamente

**Soluções:**

1. **Mudar para modelo com cota maior:**
   ```env
   LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17  # 4000 RPM
   ```

2. **Aguardar reset de cota** (tipicamente 1 minuto)

3. **Verificar cota atual:**
   - Gemini: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
   - OpenAI: https://platform.openai.com/usage

---

### Erro: OPENAI_API_KEY must be set

**Sintomas:**
- Ferramentas de memória falham com "api_key client option must be set"

**Causa:**
- Configuração LLM do Mem0 ausente

**Solução:**
- Certifique-se que `src/config.py` tem configuração LLM em `get_mem0_config()`
- Verifique se `LLM_PROVIDER` no `.env` corresponde a um provedor suportado

---

### Erro: Template variable 'X' not found

**Sintomas:**
- Agente crasha ao carregar conhecimento

**Causa:**
- Sintaxe `{variável}` em arquivos markdown interpretada como template CrewAI

**Solução:**
- Escape chaves em exemplos de código: use `PATH_VAR` em vez de `{path}`
- Verifique `src/knowledge/standards/*.md` por `{}` não escapados

---

## 🐳 Problemas com Docker

### Container continua reiniciando

**Verificar logs:**
```bash
docker logs antigravity_brain --tail 100
```

**Causas comuns:**
- Arquivo `.env` ausente
- Chave de API inválida
- Erros de import Python

---

### Conexão recusada ao Qdrant

**Sintomas:**
- "Connection refused" na porta 6333

**Soluções:**

1. **Verificar se Qdrant está rodando:**
   ```bash
   docker ps | findstr qdrant
   ```

2. **Verificar configuração de host:**
   ```env
   QDRANT_HOST=qdrant  # Nome do serviço Docker, NÃO localhost
   ```

3. **Reiniciar Qdrant:**
   ```bash
   docker-compose restart qdrant
   ```

---

### Alterações não refletidas

**Problema:** Alterações de código não aparecem após salvar

**Solução:**
```bash
docker-compose restart app
```

Ou para rebuild completo:
```bash
docker-compose build --no-cache app
docker-compose up -d
```

---

## 🤖 Problemas com Agentes

### Agente não encontrado

**Erro:** `No persona found matching 'nome-agente'`

**Soluções:**

1. **Verificar se nome do arquivo corresponde:**
   ```
   src/agents/personas/persona-<nome-exato>.md
   ```

2. **Usar padrão de busca correto:**
   ```python
   # Isto busca por *nome-agente* no nome do arquivo
   AgentFactory.create_agent("nome-agente")
   ```

---

### Agente carrega mas não responde

**Possíveis causas:**

1. **Erro de API LLM** - Verifique logs por 429/401
2. **Backstory vazio** - Certifique-se que persona tem conteúdo
3. **Erros de ferramenta** - Verifique se ferramentas estão lançando exceções

**Depurar:**
```bash
docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
```

---

### Agente usando modelo errado

**Verificar:** Certifique-se que `model_tier` está configurado corretamente:
```python
agent = AgentFactory.create_agent("nome", model_tier="smart")  # Usa LLM_MODEL_SMART
agent = AgentFactory.create_agent("nome", model_tier="fast")   # Usa LLM_MODEL_FAST
```

---

## 🧠 Problemas com Memória

### Memória não salva

**Verificar dashboard Qdrant:**
```
http://localhost:6333/dashboard
```

**Verificar se collection existe:** Deve ver `itguys_antigravity_v1` (ou seu `MEMORY_PROJECT_ID`)

---

### Busca de memória não retorna nada

**Possíveis causas:**

1. **Mismatch de embedding** - Não altere `MEMORY_EMBEDDING_PROVIDER` após existirem dados
2. **ID de projeto errado** - Verifique se `MEMORY_PROJECT_ID` corresponde
3. **Qdrant vazio** - Nenhuma memória salva ainda

---

## 🌐 Problemas com Interface Web

### Chainlit não carrega

**Verificar porta:**
```bash
netstat -an | findstr 8000
```

**Verificar container:**
```bash
docker logs antigravity_brain | findstr -i "error"
```

---

### Toast "Could not reach server"

**Causa:** Geralmente timeout ou erro de API LLM

**Solução:** Verifique chave de API e cota

---

## 📋 Comandos de Diagnóstico Rápido

```bash
# Verificar todos os containers
docker ps

# Ver logs em tempo real
docker logs antigravity_brain -f

# Verificar apenas erros
docker logs antigravity_brain 2>&1 | findstr "ERROR Error error Exception"

# Reiniciar tudo
docker-compose down && docker-compose up -d

# Rebuild completo
docker-compose build --no-cache && docker-compose up -d

# Verificar saúde do Qdrant
curl http://localhost:6333/health

# Testar API Gemini
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite-preview-06-17:generateContent?key=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Olá"}]}]}'
```

---

## 🆘 Obtendo Ajuda

1. **Verifique os logs primeiro** - 90% dos problemas estão nos logs do Docker
2. **Verifique o .env** - A maioria dos problemas de configuração são variáveis de ambiente
3. **Teste a API separadamente** - Certifique-se que sua chave de API funciona fora da aplicação
4. **Verifique cotas** - Rate limits são a causa #1 de falhas