> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# RAG Quick Start
> Build retrieval-augmented agents that answer from your documents and knowledge bases
RAG agents retrieve relevant chunks from your documents before answering, grounding responses in your own knowledge.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
D[Documents] --> V[(Vector DB)]
Q[Question] --> A[RAG Agent]
V --> A
A --> O[Grounded answer]
classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class D,Q input
class V store
class A process
class O output
```
Every stage below is now configurable from `KnowledgeConfig` after the fields were wired up.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Chunk[Chunk
chunking_strategy] --> Store[Store
vector_store]
Store --> Retrieve[Retrieve
retrieval_k]
Retrieve --> Rerank[Rerank
rerank_model]
Rerank --> Generate[Generate
auto_retrieve]
classDef cfg fill:#6366F1,stroke:#7C90A0,color:#fff
classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
classDef out fill:#10B981,stroke:#7C90A0,color:#fff
class Chunk,Retrieve cfg
class Store,Rerank store
class Generate out
```
## Quick Start
Pass file paths or directories — the agent indexes on first run, then retrieves on each query:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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?")
```
Use `KnowledgeConfig` for vector store, chunking, and reranking:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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"},
},
),
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, KnowledgeConfig
agent = Agent(
instructions="Answer from the knowledge base.",
knowledge=KnowledgeConfig(
sources=["small.pdf"],
embedder="cohere",
),
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/features/knowledge#use-a-non-openai-embedder) for the full guide.
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant KnowledgeStore
participant LLM
User->>Agent: Question
Agent->>KnowledgeStore: Embed query + search
KnowledgeStore-->>Agent: Relevant chunks (top-k)
Agent->>LLM: Prompt + retrieved context
LLM-->>Agent: Grounded answer
Agent-->>User: Response
```
| 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](/docs/features/knowledge#use-a-non-openai-embedder). |
| `embedder_config` | `dict` | `None` | Full embedder dict `{"provider": ..., "config": {...}}` |
| `chunking_strategy` | `str` \| `ChunkingStrategy` | `"recursive"` | Chunking method — see [Chunking Strategies](/docs/guides/rag/chunking) |
| `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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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}
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[KnowledgeConfig fields] --> Merged[Resolved dict]
B["config={...}"] --> Merged
Merged --> Retrieval[Retrieval]
classDef in fill:#6366F1,stroke:#7C90A0,color:#fff
classDef out fill:#10B981,stroke:#7C90A0,color:#fff
class A,B in
class Merged,Retrieval out
```
***
## Every knob wired up
Chunking, vector store, retrieval, and reranking are all set from one `KnowledgeConfig`.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
Pass sources via `knowledge=["file.pdf"]` at agent creation — first run indexes, later runs retrieve without re-indexing.
Narrow questions retrieve better chunks than broad prompts like "tell me everything".
Set `vector_store` with Chroma path, Qdrant, or Pinecone — avoid in-memory stores for production.
Pair `knowledge=` with web tools when you need both static documents and real-time data.
***
## Related
Pluggable embedding storage
Sources and retrieval strategies