Build your first RAG system with KnowledgeBase in 5 minutes
Overview
This guide walks you through building a complete Retrieval-Augmented Generation (RAG) system step by step. By the end, your agent will answer questions using your own documents.
from upsonic import Agent, Task, KnowledgeBasefrom upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfigfrom upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Modefrom upsonic.loaders.pdf import PdfLoaderfrom upsonic.loaders.config import PdfLoaderConfig# Step 1: Setup embedding providerembedding = OpenAIEmbedding(OpenAIEmbeddingConfig( model_name="text-embedding-3-small"))# Step 2: Setup vector databasevectordb = ChromaProvider(ChromaConfig( collection_name="my_rag_kb", vector_size=1536, connection=ConnectionConfig( mode=Mode.EMBEDDED, db_path="./rag_database" )))# Step 3: Setup PDF loaderloader = PdfLoader(PdfLoaderConfig())# Step 4: Create knowledge base with documentskb = KnowledgeBase( sources=["document.pdf"], embedding_provider=embedding, vectordb=vectordb, loaders=[loader])# Step 5: Create agent and taskagent = Agent("anthropic/claude-sonnet-4-5")task = Task( description="What is the daily working hours policy described in the text?", context=[kb])# Step 6: Execute and get resultsresult = agent.do(task)print(result)
Step-by-Step Breakdown
1. Embedding Provider
The embedding provider converts text into vector representations for semantic search. The vector_size in your vector database config must match the embedding model’s output dimension (1536 for text-embedding-3-small).
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfigembedding = OpenAIEmbedding(OpenAIEmbeddingConfig( model_name="text-embedding-3-small"))
2. Vector Database
The vector database stores embedded document chunks for fast similarity search. Choose any supported provider — this example uses Chroma in embedded mode.
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Modevectordb = ChromaProvider(ChromaConfig( collection_name="my_rag_kb", vector_size=1536, # Must match embedding model dimension connection=ConnectionConfig( mode=Mode.EMBEDDED, db_path="./rag_database" )))
3. Knowledge Base
KnowledgeBase orchestrates the entire pipeline: it loads documents, chunks text, generates embeddings, and stores them.
If you don’t specify loaders, KnowledgeBase auto-detects the appropriate loader based on file extension. Explicit loaders give you more control over parsing behavior.
4. Agent + Task
Pass the knowledge base as context to the Task. The agent automatically queries it for relevant chunks before generating a response.
from upsonic import Agent, Taskagent = Agent("anthropic/claude-sonnet-4-5")task = Task( description="What is the main topic?", context=[kb])result = agent.do(task)
What Happens Behind the Scenes
Document Loading — KnowledgeBase detects the file type and loads the document
Text Chunking — The document is split into smaller chunks optimized for retrieval
Embedding Generation — Each chunk is converted to a vector embedding
Vector Storage — Embeddings are stored in the vector database
Query Processing — When the task runs, the description is embedded and matched against stored chunks
Context Injection — The most relevant chunks are injected into the agent’s context
Response Generation — The agent uses the retrieved context to generate an answer
Next Steps
Examples — More patterns: async, streaming, multiple KBs, custom splitters
Using as Tool — Let agents actively search the KB (instead of auto-injection)
Vector Stores — Compare and choose the right vector database
Query Control — Fine-tune when RAG context is injected