Retrievers & Rerankers in YAML
Pick a retrieval strategy and reranker from your agents.yaml — no Python setup
Declare a retriever and reranker by name in your agent YAML and PraisonAI wires them into the knowledge base for you.
Quick Start
- Declare the retriever and reranker
yaml # agents.yaml framework: praisonai process: sequential topic: "Answer questions from the docs" agents: researcher: role: "Research assistant" goal: "Answer questions with the highest-quality retrieved passages" instructions: "Expert at finding the exact snippet a user needs." knowledge: sources: ["./docs/"] retriever: fusion # basic | fusion | recursive | auto_merge | hybrid reranker: llm # llm | cross_encoder | cohere retrieval_k: 20 - Run it
bash praisonai agents.yamlNo Python setup. All four launch surfaces —
praisonai <agents.yaml>,praisonai serve,praisonai eval, and Python (praisonai.run/praisonai.arun) — wire the built-in retrievers, readers and rerankers before the agent starts, soretriever: fusion(or any built-in name) resolves identically on every surface (PR #5322).
How it wires up
The registration is single-sourced in AgentsGenerator.__init__, so every launch path fires it once before the agent starts — not just the Python entry point.
The call is idempotent and thread-safe — it runs once per process even under startup races. It is also register-only-if-absent: a custom adapter you already registered under a built-in name (e.g. a multi-tenant host’s own fusion) is preserved, never overwritten.
Retriever choices
| Name | When to use | Extra install |
|---|---|---|
basic | Default — simple vector similarity | None |
fusion | Multiple query variations, then RRF merge — better recall on ambiguous questions | None |
recursive | Depth-limited chunk expansion — better for hierarchical content | None |
auto_merge | Merges adjacent chunks from the same document — better for long passages | None |
hybrid | Vector + keyword combined | None |
Reranker choices
| Name | When to use | Extra install |
|---|---|---|
llm | Highest quality — an LLM scores each candidate | OPENAI_API_KEY |
cross_encoder | Local neural reranker — no API cost | pip install sentence-transformers |
cohere | Cohere’s hosted rerank API | COHERE_API_KEY |
Choosing a retriever
Choosing a reranker
From the CLI
Same names, one-off from the praisonai knowledge query sub-command:
praisonai knowledge query "How do I authenticate?" \
--retrieval fusion \
--reranker llmSee Knowledge CLI for the full flag reference.
Best Practices
Start with basic, upgrade when recall is low
Use basic first — it needs no LLM calls or extra installs. Move to fusion only when ambiguous or paraphrased questions miss the right passage.
Retrieve wide, rerank narrow
Set retrieval_k higher than the number of passages you actually want, then let the reranker trim to the best few. A common pairing is retrieval_k: 20 with an llm reranker returning the top 5.
Match the reranker to your cost budget
cross_encoder runs locally with no API cost; llm is highest quality but bills per candidate; cohere is a hosted API. Pick based on whether cost, quality, or zero-dependency matters most.
No Python setup needed from YAML
The generator auto-wires the built-in adapters from AgentsGenerator.__init__, so a name like retriever: fusion resolves without any register_default_adapters() call — on every launch surface (praisonai <file.yaml>, praisonai serve, praisonai eval, and Python run/arun), not just the Python entry point (PR #5322). You only call it yourself when using retriever/reranker classes directly from your own Python code.
Safe in multi-agent setups
The retriever and reranker registries are thread-safe. If you’re running many agents in parallel (native threads, asyncio, or a worker pool), they all share the same registry safely — no external locks needed, and no duplicate singletons on startup races. Since PraisonAI #5197.