> ## 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.
# Retrieval Configuration
> Configure retrieval behaviour for AI agents with knowledge bases
Control how agents retrieve and inject knowledge through the `knowledge` parameter — one surface for sources, chunking, reranking, and retrieval policy.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Research Agent",
instructions="Answer questions based on the provided documents.",
knowledge={
"sources": ["docs/", "papers.pdf"],
"retrieval_k": 5,
"rerank": True,
},
)
response = agent.start("What are the key findings?")
```
The user asks a question; the agent retrieves relevant chunks from configured knowledge sources before answering.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Retrieval"
Query[📋 User Query] --> Agent[🤖 Agent]
Agent --> Retrieve[🔍 Retrieve Context]
Retrieve --> Response[✅ Answer + Citations]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Query input
class Agent agent
class Retrieve tool
class Response output
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Research Agent",
instructions="Answer questions based on the provided documents.",
knowledge={
"sources": ["docs/"],
"retrieval_k": 5,
"rerank": True,
},
)
response = agent.start("What are the key findings?")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, KnowledgeConfig
agent = Agent(
name="Agent",
instructions="You are a helpful assistant.",
knowledge=KnowledgeConfig(
sources=["documents/"],
embedder="openai",
chunking_strategy="semantic",
chunk_size=1000,
chunk_overlap=200,
retrieval_k=5,
retrieval_threshold=0.3,
rerank=True,
auto_retrieve=True,
vector_store={"provider": "chroma", "collection_name": "default"},
),
)
```
`embedder="openai"` is the default and means "no override". For Gemini, Cohere, or local Ollama embeddings, see [Knowledge → Use a non-OpenAI embedder](/docs/features/knowledge#use-a-non-openai-embedder).
***
## How It Works
The user asks a question; the agent embeds the query, retrieves the top-k chunks, then generates an answer with citations.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Knowledge
User->>Agent: start("What are the findings?")
Agent->>Knowledge: Retrieve top-k chunks
Knowledge-->>Agent: Relevant context + scores
Agent->>Agent: Generate answer with context
Agent-->>User: Response + citations
```
***
## 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[str, Any]` | `None` | Full embedder dict `{"provider": ..., "config": {...}}` |
| `chunking_strategy` | `str` | `"semantic"` | Chunking method |
| `chunk_size` | `int` | `1000` | Target chunk size in tokens |
| `chunk_overlap` | `int` | `200` | Overlap between chunks |
| `retrieval_k` | `int` | `5` | Number of chunks to retrieve |
| `retrieval_threshold` | `float` | `0.0` | Minimum relevance score (0.0–1.0) |
| `rerank` | `bool` | `False` | Enable reranking |
| `rerank_model` | `str` | `None` | Custom rerank model |
| `auto_retrieve` | `bool` | `True` | Inject context automatically |
| `vector_store` | `dict` | `None` | Vector store provider config |
***
## Agent Methods
### `agent.start()` / `agent.chat()`
Conversation with automatic retrieval when `auto_retrieve=True`:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
response = agent.start("What is the main topic?")
response = agent.start("Hello", force_retrieval=True)
response = agent.start("What is 2+2?", skip_retrieval=True)
```
### `agent.query()`
Structured answer with citations:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = agent.query("What are the main findings?")
print(result.answer)
for citation in result.citations:
print(f"[{citation.id}] {citation.source} (score: {citation.score:.2f})")
```
### `agent.retrieve()`
Retrieval only — no LLM generation:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
context_pack = agent.retrieve("What are the key points?")
print(f"Found {len(context_pack.citations)} sources")
```
***
## Multi-Agent Shared Knowledge
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Knowledge
shared = Knowledge(config={"vector_store": {"provider": "chroma", "config": {"collection_name": "shared_docs"}}})
shared.add("company_docs/")
analyst = Agent(
name="Analyst",
instructions="Analyse data from documents.",
knowledge={"sources": shared, "retrieval_k": 10},
)
summariser = Agent(
name="Summariser",
instructions="Summarise key points.",
knowledge={"sources": shared, "retrieval_k": 5},
)
```
***
## Best Practices
Use `retrieval_threshold=0.3` or higher when low-scoring chunks pollute answers.
For large bases, set `retrieval_k=20` with `rerank=True` — cast a wide net, then keep the best chunks.
Arithmetic, greetings, and meta questions do not need retrieval — pass `skip_retrieval=True`.
Create one `Knowledge` instance and pass it as `sources` to multiple agents to avoid re-indexing.
***
## Related
Auto-select strategy by corpus size
Run retrieval from the command line