Skip to main content
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

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

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

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

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

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

​
RAG vs Knowledge vs Memory vs Context

​
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

​
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, PraisonAIAgents

# 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"
)

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

agents.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
    )
)
ModeDescription
APPENDAdd sources at end of response
INLINEInsert citation markers in text
HIDDENInclude 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

  • Check if documents were indexed: knowledge.stats()
  • Lower the similarity threshold
  • Try different chunking strategy
  • Reduce retrieval_k
  • Disable reranking for faster results
  • Use persistent vector store
  • Increase chunk overlap
  • Use semantic chunking
  • Increase retrieval_k

Knowledge

Document loading and indexing

Memory

Persistent agent memory

Context

Runtime data flow

Quality RAG

Advanced quality patterns