Skip to main content

​
Overview

KnowledgeBase can be used as a tool, allowing the agent to actively search and retrieve information from your knowledge base during task execution. When added as a tool, the agent gains access to a search method that it can call to query the knowledge base.

​
Key Benefits

  • Active Retrieval: Agent decides when and how to search the knowledge base
  • Dynamic Queries: Agent can formulate multiple queries based on context
  • Tool Integration: Works seamlessly with other tools in the agent’s toolkit
  • Automatic Setup: KnowledgeBase is automatically set up when first used

​
Basic Usage

Add KnowledgeBase to the tools parameter of a Task or Agent: 
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode
from upsonic.loaders.pdf import PdfLoader
from upsonic.loaders.config import PdfLoaderConfig

# Step 1: Setup embedding provider
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig(
    model_name="text-embedding-3-small"
))

# Step 2: Setup vector database
vectordb = ChromaProvider(ChromaConfig(
    collection_name="my_rag_kb",
    vector_size=1536,
    connection=ConnectionConfig(
        mode=Mode.EMBEDDED,
        db_path="./rag_database"
    )
))

# Step 3: Setup PDF loader
loader = PdfLoader(PdfLoaderConfig())

# Step 4: Create knowledge base with documents
kb = KnowledgeBase(
    sources=["document.pdf"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader]
)

# Step 5: Create agent
agent = Agent("openai/gpt-4o")

# Step 6: Create task with knowledge base as a tool
task = Task(
    description="What are the main topics discussed in the document?",
    tools=[kb]
)

# Step 7: Execute and get results
result = agent.do(task)
print(result)

​
How It Works

  1. Tool Registration: When you add KnowledgeBase to tools, the agent automatically registers the search method as an available tool
  2. Automatic Setup: The KnowledgeBase is automatically set up.
  3. Agent Control: The agent decides when to call the search tool and what queries to make
  4. Results Integration: Search results are returned to the agent, which uses them to answer your questions

​
Tool vs Context

Using as Tool (this feature):
  • Agent actively searches when needed
  • Agent can make multiple queries
  • Agent controls the search strategy
  • Best for: Complex tasks requiring multiple searches
Using as Context (traditional RAG):
  • Knowledge base is queried once before task execution
  • Results are added to the context automatically
  • Simpler, but less flexible
  • Best for: Simple Q&A tasks

​
Multiple Knowledge Bases

You can add multiple KnowledgeBase instances as tools. When using multiple knowledge bases, provide unique name and description attributes so the agent can distinguish between them: 
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode
from upsonic.loaders.pdf import PdfLoader
from upsonic.loaders.config import PdfLoaderConfig

# Setup dependencies
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())
vectordb = ChromaProvider(ChromaConfig(
    collection_name="my_kb",
    vector_size=1536,
    connection=ConnectionConfig(mode=Mode.EMBEDDED, db_path="./chroma_db")
))

loader = PdfLoader(PdfLoaderConfig())

# Each KnowledgeBase MUST have a unique name for multi-KB usage
kb1 = KnowledgeBase(
    sources=["technical_docs/"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader],
    name="technical_docs",  # IMPORTANT: Unique name for this KB
    description="Technical API documentation including rate limits, authentication, and endpoints"
)

kb2 = KnowledgeBase(
    sources=["user_guides/"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader],
    name="user_guides",  # IMPORTANT: Different unique name
    description="User guides and tutorials for end users including usage limits and best practices"
)

# Use with Agent
agent = Agent("openai/gpt-4o")
task = Task(
    description="Compare the API rate limits defined in the technical documentation with the usage limits described in the user guide",
    tools=[kb1, kb2]
)

result = agent.do(task)
print(result)

​
How Tool Names Are Generated

When you register multiple KnowledgeBase instances as tools, each one gets a unique tool name based on its name attribute:
KnowledgeBase nameRegistered Tool Name
"technical_docs"search_technical_docs
"user_guides"search_user_guides
(no name provided)search_{auto_generated_id} (e.g., search_7c6432f612bb422a)
This allows the agent to call the appropriate knowledge base search tool:
  • Call search_technical_docs(query="API rate limits") to search the technical documentation
  • Call search_user_guides(query="usage limits") to search the user guides
If you don’t provide unique name attributes, tool names may collide and only one knowledge base will be accessible.

​
Cleanup

Always close the KnowledgeBase when done to free resources: 
await kb.close()