RAG (Retrieval Augmented Generation)

Complete guide to RAG - how agents retrieve and use knowledge to generate accurate, grounded responses

RAG enables agents to retrieve relevant information from documents before generating responses, producing accurate, grounded answers with citations.

Quick Start

1. Install

   pip install "praisonaiagents[knowledge]"
   export OPENAI_API_KEY=your_key
   
2. Create Agent with Knowledge

   from praisonaiagents import Agent
   
   agent = Agent(
       name="RAG Agent",
       instructions="Answer questions using the knowledge base",
       knowledge=["docs/manual.pdf"]  # Your documents
   )
   
   agent.start("What are the key features?")
   
3. Get Answer with Citations

   # Use query() for structured results with citations
   result = agent.query("What are the main findings?")
   
   print(result.answer)
   for citation in result.citations:
       print(f"  [{citation.id}] {citation.source}")
   

---

How RAG Works

The RAG Process

Phase	What Happens	When
Indexing	Documents → Chunks → Embeddings → Vector DB	Once per document
Retrieval	Query → Embedding → Similarity Search → Top-K chunks	Every query
Generation	Query + Context → LLM → Answer + Citations	Every query

---

Agent Methods for RAG

Method	Returns	Use Case
agent.start(prompt)	String	Interactive terminal with RAG
agent.chat(prompt)	String	Programmatic RAG
agent.query(prompt)	RAGResult	Structured answer + citations
agent.retrieve(prompt)	ContextPack	Context only, no LLM generation

Example: All Methods

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Answer using the knowledge base",
    knowledge=["research_paper.pdf"]
)

# Method 1: Interactive (verbose output)
agent.start("Summarize the findings")

# Method 2: Programmatic (silent)
answer = agent.chat("What methodology was used?")

# Method 3: Structured with citations
result = agent.query("What are the conclusions?")
print(result.answer)
print(result.citations)

# Method 4: Retrieval only (no LLM)
context = agent.retrieve("key findings")
print(f"Found {len(context.citations)} sources")
print(context.context)  # Raw retrieved text

---

Knowledge Configuration

Basic: File List

agent = Agent(
    name="Agent",
    knowledge=["doc1.pdf", "doc2.txt", "folder/"]
)

Advanced: Full Configuration

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Advanced RAG Agent",
    instructions="Answer with high precision",
    knowledge=KnowledgeConfig(
        sources=["docs/"],
        
        # Retrieval settings
        retrieval_k=5,              # Number of chunks to retrieve
        rerank=True,                # Rerank for better relevance
        
        # Chunking settings
        chunking_strategy="semantic",  # semantic, fixed, sentence
        chunk_size=1000,
        chunk_overlap=200,
        
        # Vector store
        vector_store={
            "provider": "chroma",
            "config": {
                "collection_name": "my_docs",
                "path": ".praison"
            }
        }
    )
)

Configuration Options

Option	Type	Default	Description
sources	list	[]	Files, folders, or URLs
retrieval_k	int	5	Number of chunks to retrieve
rerank	bool	False	Enable reranking
chunking_strategy	str	"semantic"	How to split documents
chunk_size	int	1000	Max tokens per chunk
chunk_overlap	int	200	Overlap between chunks
auto_retrieve	bool	True	Auto-inject context

---

Retrieval Strategies

PraisonAI automatically selects the optimal strategy based on corpus size:

Strategy	Files	Technique
DIRECT	< 10	Load all content into context
BASIC	< 100	Embedding-based semantic search
HYBRID	< 1000	Keyword + semantic search
RERANKED	< 10000	Hybrid + cross-encoder reranking
COMPRESSED	< 100000	Reranked + contextual compression
HIERARCHICAL	≥ 100000	Summaries + top-down routing

Force a Strategy

agent = Agent(
    knowledge={
        "sources": ["large_corpus/"],
        "strategy": "reranked"  # Force reranking
    }
)

---

RAG vs Knowledge vs Memory vs Context

Comparison Table

Aspect	RAG	Knowledge	Memory	Context
What	Search technique	Pre-loaded docs	Persistent storage	Runtime data
When	Query time	Before execution	Across sessions	During execution
Lifetime	N/A	Permanent	Permanent	Session only
Direction	Read-only	Read-only	Read + Write	Read-only
Agent Param	Part of knowledge=	knowledge=	memory=	context=

When to Use What

---

Agent with Knowledge (Simple)

For small document sets where you don’t need advanced retrieval:

from praisonaiagents import Agent

# Simple knowledge - loads documents, enables basic search
agent = Agent(
    name="FAQ Agent",
    instructions="Answer questions from the FAQ",
    knowledge=["faq.txt"]  # Small file, basic search
)

agent.start("What is the return policy?")

Agent with RAG (Advanced)

For large document sets requiring sophisticated retrieval:

from praisonaiagents import Agent, KnowledgeConfig

# Advanced RAG - full retrieval pipeline
agent = Agent(
    name="Research Agent",
    instructions="Answer with citations from research papers",
    knowledge=KnowledgeConfig(
        sources=["papers/"],
        retrieval_k=10,
        rerank=True,
        chunking_strategy="semantic"
    )
)

# Get structured result with citations
result = agent.query("What are the latest findings on X?")

---

Multi-Agent RAG

Share knowledge across multiple agents:

from praisonaiagents import Agent, Knowledge, AgentTeam

# Create shared knowledge base
knowledge = Knowledge(config={
    "vector_store": {
        "provider": "chroma",
        "config": {"collection_name": "shared_docs"}
    }
})
knowledge.add("company_docs/")

# Multiple agents share the same knowledge
researcher = Agent(
    name="Researcher",
    instructions="Find relevant information",
    knowledge=knowledge
)

writer = Agent(
    name="Writer",
    instructions="Write based on research findings"
)

team = AgentTeam(
    agents=[researcher, writer],
    process="sequential"
)

team.start("Write a report on Q4 performance")

---

Supported File Types

Documents

PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX

Text

TXT, CSV, JSON, XML, MD, HTML

Media

Images (with OCR), Audio (with transcription)

---

Vector Store Backends

# ChromaDB (default)
knowledge={"sources": ["docs/"], "vector_store": {"provider": "chroma"}}

# MongoDB Atlas
knowledge={"sources": ["docs/"], "vector_store": {"provider": "mongodb"}}

# Qdrant
knowledge={"sources": ["docs/"], "vector_store": {"provider": "qdrant"}}

# Pinecone
knowledge={"sources": ["docs/"], "vector_store": {"provider": "pinecone"}}

---

Citations

RAG automatically provides source citations:

result = agent.query("What is the main conclusion?")

# Access citations
for citation in result.citations:
    print(f"[{citation.id}] {citation.source}")
    print(f"  Score: {citation.score:.2f}")
    print(f"  Text: {citation.text[:100]}...")

Citation Modes

from praisonaiagents import Agent, RetrievalConfig, CitationsMode

agent = Agent(
    knowledge=RetrievalConfig(
        sources=["docs/"],
        citations=True,
        citations_mode=CitationsMode.APPEND  # or INLINE, HIDDEN
    )
)

Mode	Description
APPEND	Add sources at end of response
INLINE	Insert citation markers in text
HIDDEN	Include in metadata only

---

Best Practices

Chunk Size

Use 500-1000 tokens per chunk. Too small = lost context. Too large = noise.

Overlap

Use 10-20% overlap to preserve context across chunk boundaries.

Reranking

Enable reranking for large corpora to improve relevance.

Top-K

Start with k=5, increase if answers lack detail.

---

Troubleshooting

No relevant results

• Check if documents were indexed: knowledge.stats()
• Lower the similarity threshold
• Try different chunking strategy

Slow retrieval

• Reduce retrieval_k
• Disable reranking for faster results
• Use persistent vector store

Missing context

• Increase chunk overlap
• Use semantic chunking
• Increase retrieval_k

---

Related Documentation

Knowledge

Document loading and indexing

Memory

Persistent agent memory

Context

Runtime data flow

Quality RAG

Advanced quality patterns