Skip to main content

​
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 CaseRecommended
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"],
    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

ParameterTypeDefaultDescription
agentAgentrequiredAgent instance with knowledge configured
ragRAGNoneOptional RAG instance (uses agent.rag if not provided)
configAutoRagConfigNoneFull configuration object
retrieval_policystr"auto"When to retrieve: auto, always, never
top_kint5Number of results to retrieve
hybridboolFalseEnable hybrid retrieval (dense + BM25)
rerankboolFalseEnable reranking of results
citationsboolTrueInclude 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

ParameterTypeDefaultDescription
messagestrrequiredUser message/query
force_retrievalboolFalseForce retrieval regardless of policy
skip_retrievalboolFalseSkip retrieval regardless of policy
top_kintNoneOverride top_k for this call
hybridboolNoneOverride hybrid setting for this call
rerankboolNoneOverride rerank setting for this call
user_idstrNoneUser 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/"],
    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

FeatureAgentRAGAutoRagAgent
Direct chat✅❌✅
Knowledge retrievalManualAlwaysAuto-decides
CitationsManual✅✅
Hybrid retrievalManual✅✅
RerankingManual✅✅
Policy control❌❌✅

​
See Also