Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
AutoRagAgent
AutoRagAgent is an agent wrapper that automatically decides when to retrieve context from knowledge bases versus direct chat, based on query heuristics.
Overview
AutoRagAgent wraps an existing Agent and adds intelligent retrieval decision-making:
- auto policy: Decides based on query keywords, length, and question marks
- always policy: Always retrieves context before responding
- never policy: Never retrieves, direct chat only
When to Use
| Use Case | Recommended |
|---|
| Agent with knowledge that should auto-retrieve | ✅ AutoRagAgent |
| Simple chat without knowledge | ❌ Use Agent directly |
| Always need RAG context | ✅ AutoRagAgent with always policy |
| Fine-grained retrieval control | ❌ Use RAG.retrieve() + Agent.chat_with_context() |
Installation
pip install praisonaiagents
Quick Start
from praisonaiagents import Agent, AutoRagAgent
# Create agent with knowledge
agent = Agent(
name="Research Assistant",
instructions="You are a helpful research assistant.",
knowledge=["docs/manual.pdf", "data/faq.txt"],
memory={"user_id": "user123"} , # Required for RAG
)
# Wrap with AutoRagAgent
auto_rag = AutoRagAgent(
agent=agent,
retrieval_policy="auto", # auto, always, never
top_k=5,
hybrid=True,
rerank=True,
)
# Auto-decides: retrieves for questions, skips for greetings
result = auto_rag.chat("What are the key findings?") # Retrieves
result = auto_rag.chat("Hello!") # Skips retrieval
API Reference
AutoRagAgent
class AutoRagAgent:
def __init__(
self,
agent: Agent,
rag: Optional[RAG] = None,
config: Optional[AutoRagConfig] = None,
*,
retrieval_policy: Optional[str] = None, # "auto", "always", "never"
top_k: Optional[int] = None,
hybrid: Optional[bool] = None,
rerank: Optional[bool] = None,
citations: bool = True,
)
Parameters
| Parameter | Type | Default | Description |
|---|
agent | Agent | required | Agent instance with knowledge configured |
rag | RAG | None | Optional RAG instance (uses agent.rag if not provided) |
config | AutoRagConfig | None | Full configuration object |
retrieval_policy | str | "auto" | When to retrieve: auto, always, never |
top_k | int | 5 | Number of results to retrieve |
hybrid | bool | False | Enable hybrid retrieval (dense + BM25) |
rerank | bool | False | Enable reranking of results |
citations | bool | True | Include citations in response |
chat()
def chat(
self,
message: str,
*,
force_retrieval: bool = False,
skip_retrieval: bool = False,
top_k: Optional[int] = None,
hybrid: Optional[bool] = None,
rerank: Optional[bool] = None,
user_id: Optional[str] = None,
**kwargs,
) -> str
Parameters
| Parameter | Type | Default | Description |
|---|
message | str | required | User message/query |
force_retrieval | bool | False | Force retrieval regardless of policy |
skip_retrieval | bool | False | Skip retrieval regardless of policy |
top_k | int | None | Override top_k for this call |
hybrid | bool | None | Override hybrid setting for this call |
rerank | bool | None | Override rerank setting for this call |
user_id | str | None | User ID for RAG (uses agent.user_id if not provided) |
RetrievalPolicy
from praisonaiagents import RagRetrievalPolicy
class RetrievalPolicy(Enum):
AUTO = "auto" # Decide based on query heuristics
ALWAYS = "always" # Always retrieve
NEVER = "never" # Never retrieve
AutoRagConfig
from praisonaiagents import AutoRagConfig
config = AutoRagConfig(
retrieval_policy=RetrievalPolicy.AUTO,
top_k=5,
hybrid=False,
rerank=False,
include_citations=True,
citations_mode="append", # append, hidden, none
max_context_tokens=4000,
auto_keywords={"what", "how", "why", "explain", ...},
auto_min_length=10,
)
Examples
Basic Usage
from praisonaiagents import Agent, AutoRagAgent
agent = Agent(
name="DocBot",
knowledge=["./docs/"],
memory={"user_id": "user1"},
)
auto_rag = AutoRagAgent(agent=agent)
# Automatic decision
response = auto_rag.chat("What is the return policy?")
Force/Skip Retrieval
# Force retrieval even for short queries
response = auto_rag.chat("Hi", force_retrieval=True)
# Skip retrieval even for questions
response = auto_rag.chat("What is 2+2?", skip_retrieval=True)
Different Policies
# Always retrieve
always_rag = AutoRagAgent(agent=agent, retrieval_policy="always")
# Never retrieve (chat only)
never_rag = AutoRagAgent(agent=agent, retrieval_policy="never")
# Auto (default) - decides based on query
auto_rag = AutoRagAgent(agent=agent, retrieval_policy="auto")
With Hybrid Retrieval and Reranking
auto_rag = AutoRagAgent(
agent=agent,
hybrid=True, # Dense + BM25 keyword search
rerank=True, # Rerank results for better relevance
top_k=10, # Retrieve more, rerank to top 5
)
Async Usage
import asyncio
async def main():
response = await auto_rag.achat("What are the key findings?")
print(response)
asyncio.run(main())
CLI Usage
# Enable auto-rag with default policy (auto)
praisonai --auto-rag "What are the key findings?"
# Always retrieve
praisonai --auto-rag --rag-policy always "Tell me about X"
# With hybrid retrieval and reranking
praisonai --auto-rag --rag-hybrid --rag-rerank "Summarize the document"
# Custom top-k
praisonai --auto-rag --rag-top-k 10 "Find all references to Y"
Decision Heuristics
AutoRagAgent uses simple, local heuristics (no ML classifier) to decide when to retrieve:
- Minimum length: Queries shorter than 10 characters skip retrieval
- Keywords: Queries containing keywords like “what”, “how”, “why”, “explain”, “find”, “search” trigger retrieval
- Question marks: Queries ending with ”?” trigger retrieval
- Import overhead: ~1.6ms (lazy loaded)
- Decision overhead: less than 1ms (local heuristics only)
- No ML classifier: Zero additional dependencies
Comparison
| Feature | Agent | RAG | AutoRagAgent |
|---|
| Direct chat | ✅ | ❌ | ✅ |
| Knowledge retrieval | Manual | Always | Auto-decides |
| Citations | Manual | ✅ | ✅ |
| Hybrid retrieval | Manual | ✅ | ✅ |
| Reranking | Manual | ✅ | ✅ |
| Policy control | ❌ | ❌ | ✅ |
See Also
