RAG Quick Start

Build retrieval-augmented agents that answer from your documents and knowledge bases

RAG agents retrieve relevant chunks from your documents before answering, grounding responses in your own knowledge.

from praisonaiagents import Agent

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the provided knowledge only.",
    knowledge=["small.pdf"],
)

agent.start("What is KAG in one line?")

The user asks from their documents; the agent retrieves relevant chunks and grounds the reply.

Every stage below is now configurable from KnowledgeConfig after the fields were wired up.

Quick Start

1. Simple Usage

   Pass file paths or directories — the agent indexes on first run, then retrieves on each query:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Knowledge Agent",
       instructions="Answer from the knowledge base.",
       knowledge=["small.pdf"],
   )
   
   agent.start("What is KAG in one line?")

2. With Configuration

   Use KnowledgeConfig for vector store, chunking, and reranking:

   from praisonaiagents import Agent, KnowledgeConfig
   
   agent = Agent(
       name="Knowledge Agent",
       instructions="Answer from the provided knowledge.",
       knowledge=KnowledgeConfig(
           sources=["small.pdf"],
           vector_store={
               "provider": "chroma",
               "config": {"collection_name": "praison", "path": ".praison"},
           },
           retrieval_k=5,
           rerank=True,
       ),
   )
   
   agent.start("What is KAG in one line?")

With a different embedder provider

Set embedder_config to embed with Gemini, Cohere, or a local Ollama model instead of OpenAI.

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder_config={
            "provider": "gemini",
            "config": {"model": "models/text-embedding-004"},
        },
    ),
)

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder="cohere",
    ),
)

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(
        sources=["small.pdf"],
        embedder_config={
            "provider": "ollama",
            "config": {"model": "nomic-embed-text"},
        },
    ),
)

Pass retrieval tuning directly to Agent

retrieval_config= tunes retrieval without wrapping sources in KnowledgeConfig. A dict merges on top of what knowledge= already derived; a RetrievalConfig instance replaces it wholesale.

A dict is the quickest form — tune a few keys and keep everything knowledge= already set:

from praisonaiagents import Agent

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the knowledge base.",
    knowledge=["small.pdf"],
    retrieval_config={"citations": True, "top_k": 5},
)

agent.start("What is KAG in one line?")

For the fully-typed form, pass a RetrievalConfig instance:

from praisonaiagents import Agent, RetrievalConfig

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from the knowledge base.",
    knowledge=["small.pdf"],
    retrieval_config=RetrievalConfig(top_k=5, citations=True, rerank=True),
)

agent.start("What is KAG in one line?")

Without knowledge= at all, the dict is used as-is and resolved to a RetrievalConfig:

from praisonaiagents import Agent

agent = Agent(
    name="Knowledge Agent",
    instructions="Answer from indexed knowledge.",
    retrieval_config={"top_k": 3},
)

agent.start("What is KAG in one line?")

How dict merge works

A dict patches individual keys on top of the config derived from knowledge=; a RetrievalConfig instance skips the merge and replaces it entirely.

Every RetrievalConfig field

How It Works

For pre-indexed stores, pass vector config via task context or call agent.retrieve("query") directly.

Configuration Options

Install knowledge extras: pip install "praisonaiagents[knowledge]"

How config= overrides work

config={...} merges on top of the values resolved from KnowledgeConfig fields — it patches individual keys instead of replacing the whole config.

# Resolved by KnowledgeConfig fields:  {retrieval_k: 20, min_score: 0.4, rerank: True}
# config={"top_k": 3}                  overrides just top_k
# Final:                               {retrieval_k: 3,  min_score: 0.4, rerank: True}

Every knob wired up

Chunking, vector store, retrieval, and reranking are all set from one KnowledgeConfig.

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Research Agent",
    instructions="Answer only from the provided knowledge.",
    knowledge=KnowledgeConfig(
        sources=["research_paper.pdf"],

        # Chunking (three fields, or use chunker={...} for the same thing)
        chunking_strategy="recursive",
        chunk_size=512,
        chunk_overlap=50,

        # Vector store
        vector_store={
            "provider": "chroma",
            "config": {"collection_name": "research", "path": ".praison"},
        },

        # Retrieval
        retrieval_k=5,
        retrieval_threshold=0.35,
        auto_retrieve=True,

        # Reranking — model must be "provider/model" for the reranker to load
        rerank=True,
        rerank_model="cohere/rerank-v3",
    ),
)

agent.start("What are the main findings?")

Opting out of automatic context injection

Set auto_retrieve=False to retrieve manually instead of injecting context on every prompt.

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    instructions="Retrieve on your own; do not auto-inject.",
    knowledge=KnowledgeConfig(sources=["docs/"], auto_retrieve=False),
)

# Do it manually when you need it:
context = agent.retrieve("What are the deployment steps?")
answer = agent.chat_with_context("Summarise", context)

Best Practices

Related