> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} pip install praisonaiagents ``` ## Quick Start ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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() ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import RagRetrievalPolicy class RetrievalPolicy(Enum): AUTO = "auto" # Decide based on query heuristics ALWAYS = "always" # Always retrieve NEVER = "never" # Never retrieve ``` ### AutoRagConfig ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import asyncio async def main(): response = await auto_rag.achat("What are the key findings?") print(response) asyncio.run(main()) ``` ## CLI Usage ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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](/docs/sdk/praisonaiagents/agent/agent) - Base agent class * [RAG](/docs/features/rag) - RAG pipeline * [Knowledge](/docs/sdk/praisonaiagents/knowledge/knowledge) - Knowledge base management