Knowledge Base not responding

When the agent does not use the Knowledge Base for responses, or answers outside the document scope, check the following.

Checks

1. The KB is assigned to the agent in the Knowledge tab.
2. The document was indexed successfully. Indexing errors appear in the source list.
3. The retrieval mode is correct: semantic, hybrid, or exact.
4. The user's question falls within the domain covered by the document.
5. The agent's system instruction explicitly asks it to use the KB.

Diagnostic tools

Use the Knowledge Runtime Diagnostics in the backoffice or the endpoint:

GET /api/v1/agents/{agent_id}/knowledge-runtime?query=...

Test retrieval with:

POST /api/v1/agents/{agent_id}/knowledge-retrieve
{
  "query": "..."
}

Common fixes

• Reindex the document after changes.
• Verify the PDF contains selectable text and is not just an image.
• Try a different retrieval mode.
• Increase the amount of relevant content in the document.
• Add an instruction to the agent: "Always respond based on the Knowledge Base when possible."