RAG Quick Start

RAG agents retrieve relevant chunks from your documents before answering, grounding responses in your own knowledge.

from praisonaiagents import Agent

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the provided knowledge only.",
    knowledge=["small.pdf"],
)

agent.start("What is KAG in one line?")

The user asks from their documents; the agent retrieves relevant chunks and grounds the reply.

Indexing works but the agent won’t cite your docs? See Knowledge Troubleshooting.

Every stage below is now configurable from KnowledgeConfig after the fields were wired up.

Quick Start

Simple Usage

Pass file paths or directories — the agent indexes on first run, then retrieves on each query:

from praisonaiagents import Agent

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the knowledge base.",
    knowledge=["small.pdf"],
)

agent.start("What is KAG in one line?")

With Configuration

Use KnowledgeConfig for vector store, chunking, and reranking:

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the provided knowledge.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        vector_store={
            "provider": "chroma",
            "config": {"collection_name": "praison", "path": ".praison"},
        },
        retrieval_k=5,
        rerank=True,
    ),
)

agent.start("What is KAG in one line?")

With a different embedder provider

Set embedder_config to embed with Gemini, Cohere, or a local Ollama model instead of OpenAI.

Gemini
Cohere
Ollama

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder_config={
            "provider": "gemini",
            "config": {"model": "models/text-embedding-004"},
        },
    ),
)

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder="cohere",
    ),
)

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder_config={
            "provider": "ollama",
            "config": {"model": "nomic-embed-text"},
        },
    ),
)

embedder="openai" is the default and means “no override”. See Knowledge → Use a non-OpenAI embedder for the full guide.

How It Works

Phase	What happens
1. Index	Documents are chunked and embedded into the vector store on first access
2. Retrieve	User query is embedded; top-k similar chunks are returned
3. Generate	Retrieved context is injected before the LLM prompt; LLM answers from your data

For pre-indexed stores, pass vector config via task context or call agent.retrieve("query") directly.

Configuration Options

Option	Type	Default	Description
`sources`	`List[str]`	`[]`	Files, directories, or URLs to index
`embedder`	`str`	`"openai"`	Provider shorthand; `"openai"` means “no override”. See Use a non-OpenAI embedder.
`embedder_config`	`dict`	`None`	Full embedder dict `{"provider": ..., "config": {...}}`
`chunking_strategy`	`str` \| `ChunkingStrategy`	`"recursive"`	Chunking method — see Chunking Strategies
`chunk_size`	`int`	`512`	Target chunk size in tokens
`chunk_overlap`	`int`	`50`	Overlap between adjacent chunks
`chunker`	`dict`	`None`	Full chunker dict — alternative to the three fields above: `{"type": "token", "chunk_size": 512, "chunk_overlap": 50}`
`vector_store`	`dict`	`None`	Backend provider config `{"provider": "chroma", "config": {"collection_name": "...", "path": "..."}}`
`retrieval_k`	`int`	`5`	Chunks retrieved per query
`retrieval_threshold`	`float`	`0.0`	Minimum similarity score
`rerank`	`bool`	`False`	Rerank retrieved chunks after search
`rerank_model`	`str`	`None`	Reranker model — use `"provider/model"` format (e.g. `"cohere/rerank-v3"`); provider is required for the reranker to load
`auto_retrieve`	`bool`	`True`	Automatically inject retrieved context into the prompt
`config`	`dict`	`None`	Advanced override — merged on top of the resolved config (does not replace it)

config={...} now updates the resolved retrieval config instead of replacing it — setting retrieval_k=20, config={"note":"mine"} keeps retrieval_k=20 (previously it silently reset to 5).

If you previously set chunk_size / chunking_strategy / vector_store and relied on the app running, those settings are now active and may require re-indexing to match new chunk boundaries or a different vector store.

Install knowledge extras: pip install "praisonaiagents[knowledge]"

How `config=` overrides work

config={...} merges on top of the values resolved from KnowledgeConfig fields — it patches individual keys instead of replacing the whole config.

# Resolved by KnowledgeConfig fields:  {retrieval_k: 20, min_score: 0.4, rerank: True}
# config={"top_k": 3}                  overrides just top_k
# Final:                               {retrieval_k: 3,  min_score: 0.4, rerank: True}

Every knob wired up

Chunking, vector store, retrieval, and reranking are all set from one KnowledgeConfig.

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Research Agent",
    instructions="Answer only from the provided knowledge.",
    knowledge=KnowledgeConfig(
        sources=["research_paper.pdf"],

        # Chunking (three fields, or use chunker={...} for the same thing)
        chunking_strategy="recursive",
        chunk_size=512,
        chunk_overlap=50,

        # Vector store
        vector_store={
            "provider": "chroma",
            "config": {"collection_name": "research", "path": ".praison"},
        },

        # Retrieval
        retrieval_k=5,
        retrieval_threshold=0.35,
        auto_retrieve=True,

        # Reranking — model must be "provider/model" for the reranker to load
        rerank=True,
        rerank_model="cohere/rerank-v3",
    ),
)

agent.start("What are the main findings?")

rerank_model must include a provider prefix (e.g. "cohere/rerank-v3"). A bare model name like "rerank-v3" is used as its own provider — set it deliberately or it will not load.

Opting out of automatic context injection

Set auto_retrieve=False to retrieve manually instead of injecting context on every prompt.

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Retrieve on your own; do not auto-inject.",
    knowledge=KnowledgeConfig(sources=["docs/"], auto_retrieve=False),
)

# Do it manually when you need it:
context = agent.retrieve("What are the deployment steps?")
answer = agent.chat_with_context("Summarise", context)

Best Practices

Index documents before querying

Pass sources via knowledge=["file.pdf"] at agent creation — first run indexes, later runs retrieve without re-indexing.

Use specific questions

Narrow questions retrieve better chunks than broad prompts like “tell me everything”.

Use persistent vector stores in production

Set vector_store with Chroma path, Qdrant, or Pinecone — avoid in-memory stores for production.

Combine RAG with tools for live data

Pair knowledge= with web tools when you need both static documents and real-time data.

Vector Store

Pluggable embedding storage

Knowledge

Sources and retrieval strategies

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)

Quick Start

With a different embedder provider

How It Works

Configuration Options

How `config=` overrides work

Every knob wired up

Opting out of automatic context injection

Best Practices

Vector Store

Knowledge

​Quick Start

​With a different embedder provider

​How It Works

​Configuration Options

​How config= overrides work

​Every knob wired up

​Opting out of automatic context injection

​Best Practices

​Related

Vector Store

Knowledge

Quick Start

With a different embedder provider

How It Works

Configuration Options

How `config=` overrides work

Every knob wired up

Opting out of automatic context injection

Best Practices

Related