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.

Diagram

RAG Pipeline

1. Embed

2. Search

3. Retrieve

4. Augment

5. Generate

❓ Query

Query Vector

Vector DB

📄 Relevant Chunks

🧠 LLM

✅ Answer + Citations

Quick Start

  1. Install
    bash
    pip install "praisonaiagents[knowledge]"
    export OPENAI_API_KEY=your_key
  2. Create Agent with Knowledge
    python
    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
    python
    # 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

Diagram
LLMVectorDBEmbedderAgentUserLLMVectorDBEmbedderAgentUser1. INDEXING (one-time)2. RETRIEVAL (per query)3. GENERATIONChunk documentsStore embeddings“What is X?”Embed querySimilarity searchTop-K chunksQuery + Retrieved contextAnswer with citationsGrounded response

The RAG Process

PhaseWhat HappensWhen
IndexingDocuments → Chunks → Embeddings → Vector DBOnce per document
RetrievalQuery → Embedding → Similarity Search → Top-K chunksEvery query
GenerationQuery + Context → LLM → Answer + CitationsEvery query

Agent Methods for RAG

Diagram

Agent RAG Methods

Interactive

Programmatic

Structured

Context Only

agent.start()

Full RAG + Display

agent.chat()

agent.query()

Answer + Citations

agent.retrieve()

ContextPack

MethodReturnsUse Case
agent.start(prompt)StringInteractive terminal with RAG
agent.chat(prompt)StringProgrammatic RAG
agent.query(prompt)RAGResultStructured answer + citations
agent.retrieve(prompt)ContextPackContext only, no LLM generation

Example: All Methods

python
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

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

Advanced: Full Configuration

python
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

OptionTypeDefaultDescription
sourceslist[]Files, folders, or URLs
retrieval_kint5Number of chunks to retrieve
rerankboolFalseEnable reranking
chunking_strategystr"semantic"How to split documents
chunk_sizeint1000Max tokens per chunk
chunk_overlapint200Overlap between chunks
auto_retrieveboolTrueAuto-inject context

Retrieval Strategies

PraisonAI automatically selects the optimal strategy based on corpus size:

Diagram

Yes

No

Yes

No

Yes

No

Yes

No

📊 Corpus Size

< 10 files?

🎯 DIRECT
Load all content

< 100 files?

🔍 BASIC
Semantic search

< 1000 files?

⚡ HYBRID
Keyword + Semantic

< 10000 files?

🏆 RERANKED
Hybrid + Reranking

📦 COMPRESSED
+ Compression

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

Force a Strategy

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

RAG vs Knowledge vs Memory vs Context

Diagram

Information Systems

powers

read-only

read/write

ephemeral

🔍 RAG
Retrieval technique

📚 Knowledge
Pre-loaded docs

🧠 Memory
Persistent learning

📋 Context
Runtime data flow

🤖 Agent

Comparison Table

AspectRAGKnowledgeMemoryContext
WhatSearch techniquePre-loaded docsPersistent storageRuntime data
WhenQuery timeBefore executionAcross sessionsDuring execution
LifetimeN/APermanentPermanentSession only
DirectionRead-onlyRead-onlyRead + WriteRead-only
Agent ParamPart of knowledge=knowledge=memory=context=

When to Use What

Diagram

Yes

Yes

No

No

Yes

No

🤔 What do I need?

External documents?

Need semantic search?

✅ Knowledge + RAG

✅ Knowledge alone

Persist across sessions?

✅ Memory

✅ Context


Agent with Knowledge (Simple)

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

python
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:

python
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:

python
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")
Diagram

Agents

Shared Knowledge

search

context

📚 Documents

Vector DB

🔍 Researcher

✍️ Writer

📄 Report


Supported File Types


Vector Store Backends

python
# 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:

python
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

python
from praisonaiagents import Agent, RetrievalConfig, CitationsMode

agent = Agent(
    knowledge=RetrievalConfig(
        sources=["docs/"],
        citations=True,
        citations_mode=CitationsMode.APPEND  # or INLINE, HIDDEN
    )
)
ModeDescription
APPENDAdd sources at end of response
INLINEInsert citation markers in text
HIDDENInclude in metadata only

Best Practices


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