AutoRagAgent

Agent wrapper with automatic RAG retrieval decision

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:

1. Minimum length: Queries shorter than 10 characters skip retrieval
2. Keywords: Queries containing keywords like “what”, “how”, “why”, “explain”, “find”, “search” trigger retrieval
3. Question marks: Queries ending with ”?” trigger retrieval

Performance

• 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

• Agent - Base agent class
• RAG - RAG pipeline
• Knowledge - Knowledge base management