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:

   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:

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:

   docker ps | findstr qdrant
   

2. Verificar configuração de host:

   QDRANT_HOST=qdrant  # Nome do serviço Docker, NÃO localhost
   

3. Reiniciar Qdrant:

   docker-compose restart qdrant
   

---

Alterações não refletidas

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

Solução:

docker-compose restart app

Ou para rebuild completo:

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:

   # 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:

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

---

Agente usando modelo errado

Verificar: Certifique-se que model_tier está configurado corretamente:

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:

netstat -an | findstr 8000

Verificar container:

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

# 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