Knowledge Troubleshooting

Knowledge troubleshooting maps the most common “my agent has documents but ignores them” symptoms to fixes you can verify in seconds.

from praisonaiagents import Agent

agent = Agent(
    name="Docs Assistant",
    instructions="Answer using the knowledge base only.",
    knowledge=["policy.txt"],
)

agent.start("What is the daily API-call limit?")

The user passes files and asks a question; this guide confirms the answer actually came from those files — not from the model’s memory.

Quick Start

Install the knowledge extra

pip install "praisonaiagents[knowledge]"

Run the three-check marker test

Follow the decision tree top to bottom: install → search → chat. All three must pass before you trust RAG.

Symptom: “Indexed OK, but agent answers generically”

Search returns the right chunks, but the agent answers from its own memory — a silent hallucination against your own docs. Before (broken):

Q: What is policy ZEBRA-QUOTA-9917 daily limit?
A: I don't have access to a specific policy with that identifier.

After (grounded):

Q: What is policy ZEBRA-QUOTA-9917 daily limit?
A: Policy ZEBRA-QUOTA-9917 limits daily API calls to 42.

Verification recipe

Run this marker test against a fresh install. It proves both that search finds the chunk and that chat() actually uses it.

from pathlib import Path
from praisonaiagents import Agent

Path("policy.txt").write_text(
    "Company policy ZEBRA-QUOTA-9917 limits daily API calls to 42."
)
agent = Agent(
    instructions="Answer using the knowledge base only.",
    llm="gpt-4o-mini",
    knowledge=["policy.txt"],
)
search_ok = any("ZEBRA-QUOTA-9917" in str(r) for r in agent.knowledge.search("ZEBRA-QUOTA-9917"))
answer = agent.chat("What is policy ZEBRA-QUOTA-9917 daily limit?")
chat_ok = "ZEBRA-QUOTA-9917" in answer and "42" in answer
print(f"SEARCH_OK={search_ok}  CHAT_OK={chat_ok}")

SEARCH_OK alone does not prove RAG is working — that was exactly the trap this bug set. Both SEARCH_OK and CHAT_OK must be True.

Why a unique marker matters

Generic questions can get a lucky correct guess from the model’s parametric knowledge, giving a false pass. Use a non-memorisable token like ZEBRA-QUOTA-9917 so a correct answer can only come from your documents.

This silent grounding failure in sync chat() / start() was fixed in PR #5109 (merged 2026-09-17, closing #5098). The retrieved context now reaches the LLM prompt for both text and multimodal (attachment) paths. The async path was already correct. The fix shipped on main on 2026-09-17; it is released in the next praisonaiagents version. If your SEARCH_OK=True but CHAT_OK=False, upgrade praisonaiagents.

Interim workaround (pinned to an older release)

If you cannot upgrade yet, inject the retrieved context into the prompt yourself:

chunks = agent.knowledge.search(user_query)
context = "\n".join(str(c) for c in chunks)
answer = agent.chat(f"Context:\n{context}\n\nQuestion: {user_query}")

You should not need this on current releases. It exists only to support code pinned to a version released before PR #5109.

Symptom: `ModuleNotFoundError: No module named 'chonkie'`

The knowledge extra (which bundles the chonkie chunker) is not installed.

pip install "praisonaiagents[knowledge]"

Symptom: chat is grounded but the wrong chunks come back

CHAT_OK passes, but the cited chunks are off-topic — a retrieval-quality problem, not a grounding one. Tune reranking and chunker settings.

RAG Strategies

Choose chunking and retrieval strategies for your corpus.

RAG Quality

Reranking and quality filters for better chunk selection.

Best Practices

Always run the marker test after wiring up knowledge

A unique token like ZEBRA-QUOTA-9917 turns “it looks configured” into a SEARCH_OK + CHAT_OK pass/fail you can trust.

Never trust SEARCH_OK on its own

Retrieval succeeding does not prove the agent used the result. Assert CHAT_OK too.

Pin the knowledge extra in your project

Add "praisonaiagents[knowledge]" to requirements so chonkie is always present across environments.

Upgrade before reaching for workarounds

The manual context-injection workaround is only for pinned-old releases; upgrading removes the need entirely.

Knowledge Quick Start

Pass files to an agent and start asking questions.

RAG Quickstart

Get retrieval-augmented answers in a few steps.

Knowledge Indexing Errors

Diagnose empty indexes and embedding-backend failures.

Knowledge Search Results

Understand the shape of knowledge.search() results.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Knowledge Troubleshooting

Quick Start

Symptom: “Indexed OK, but agent answers generically”

Verification recipe

Why a unique marker matters

Interim workaround (pinned to an older release)

Symptom: `ModuleNotFoundError: No module named 'chonkie'`

Symptom: chat is grounded but the wrong chunks come back

RAG Strategies

RAG Quality

Best Practices

Knowledge Quick Start

RAG Quickstart

Knowledge Indexing Errors

Knowledge Search Results

​Quick Start

​Symptom: “Indexed OK, but agent answers generically”

​Verification recipe

​Why a unique marker matters

​Interim workaround (pinned to an older release)

​Symptom: ModuleNotFoundError: No module named 'chonkie'

​Symptom: chat is grounded but the wrong chunks come back

RAG Strategies

RAG Quality

​Best Practices

​Related

Knowledge Quick Start

RAG Quickstart

Knowledge Indexing Errors

Knowledge Search Results

Quick Start

Symptom: “Indexed OK, but agent answers generically”

Verification recipe

Why a unique marker matters

Interim workaround (pinned to an older release)

Symptom: `ModuleNotFoundError: No module named 'chonkie'`

Symptom: chat is grounded but the wrong chunks come back

Best Practices

Related