Retrieval Configuration

Control how agents retrieve and inject knowledge through the knowledge parameter — one surface for sources, chunking, reranking, and retrieval policy.

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.

Quick Start

Simple Usage

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?")

With Configuration

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.

How It Works

The user asks a question; the agent embeds the query, retrieves the top-k chunks, then generates an answer with 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.
`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

For the retrieval-time tuning surface (top_k, rerank, citations, strategy, …), see the full RetrievalConfig field reference on the RAG page.

Pass tuning without wrapping in `KnowledgeConfig`

retrieval_config= is a shortcut for retrieval-time tuning on Agent(...) directly. A dict merges on top of what knowledge= derived; a RetrievalConfig instance replaces it wholesale.

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Answer questions based on the provided documents.",
    knowledge={"sources": ["docs/"]},
    retrieval_config={"top_k": 5, "citations": True},
)
response = agent.start("What are the key findings?")

See RAG → Pass retrieval tuning directly to Agent for the merge-vs-replace rules and the full field table.

Agent Methods

`agent.start()` / `agent.chat()`

Conversation with automatic retrieval when auto_retrieve=True:

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:

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:

context_pack = agent.retrieve("What are the key points?")
print(f"Found {len(context_pack.citations)} sources")

Multi-Agent Shared Knowledge

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

Set retrieval_threshold for noisy corpora

Use retrieval_threshold=0.3 or higher when low-scoring chunks pollute answers.

Retrieve more, rerank down

For large bases, set retrieval_k=20 with rerank=True — cast a wide net, then keep the best chunks.

Use skip_retrieval for non-RAG prompts

Arithmetic, greetings, and meta questions do not need retrieval — pass skip_retrieval=True.

Retrieval Strategies

Auto-select strategy by corpus size

CLI Retrieval

Run retrieval from the command line

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)

Retrieval Configuration

Quick Start

How It Works

Configuration Options

Pass tuning without wrapping in `KnowledgeConfig`

Agent Methods

`agent.start()` / `agent.chat()`

`agent.query()`

`agent.retrieve()`

Multi-Agent Shared Knowledge

Best Practices

Retrieval Strategies

CLI Retrieval

​Quick Start

​How It Works

​Configuration Options

​Pass tuning without wrapping in KnowledgeConfig

​Agent Methods

​agent.start() / agent.chat()

​agent.query()

​agent.retrieve()

​Multi-Agent Shared Knowledge

​Best Practices

​Related

Retrieval Strategies

CLI Retrieval

Quick Start

How It Works

Configuration Options

Pass tuning without wrapping in `KnowledgeConfig`

Agent Methods

`agent.start()` / `agent.chat()`

`agent.query()`

`agent.retrieve()`

Multi-Agent Shared Knowledge

Best Practices

Related