Por que meu agente não está usando a base de conhecimento que anexei?

Quatro causas comuns, em ordem:

1. Arquivo ainda não foi processado
Verifique se aparece o ícone verde de 'pronto' em Workspace → Conhecimento. PDFs grandes demoram alguns minutos. Se ficou em vermelho, veja o motivo (senha, formato não-suportado, OCR falhou).

2. Usuário não tem acesso à coleção
Anexar a coleção ao agente não bypassa controle de acesso. O usuário precisa ter read access à coleção também (via grant direto, grupo ou coleção pública). Sem isso, a busca volta vazia silenciosamente.

3. Function calling 'native' ativo + prompt sem instrução
Se o agente usa function_calling: native (modo agentic), o RAG não é injetado automaticamente. O modelo precisa decidir chamar query_knowledge_files. Solução: no prompt do sistema adicione "Sempre consulte a base de conhecimento usando query_knowledge_files antes de responder dúvidas sobre políticas da empresa."

4. Modo 'Contexto completo' em documento grande
Documento inteiro sendo injetado consome toda a janela. Troque para 'Busca focada' (RAG) clicando no item anexado.

Debugging rápido: peça ao agente "Liste os documentos que você consegue acessar e cite 2 trechos aleatórios". Se ele não listar nada, o problema é de acesso ou ferramentas.

📖 Documentação completa na Wiki:

• Troubleshooting de RAG