Using as Tool

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("anthropic/claude-sonnet-4-5")

# 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

Tool Registration: When you add KnowledgeBase to tools, the agent automatically registers the search method as an available tool
Automatic Setup: The KnowledgeBase is automatically set up.
Agent Control: The agent decides when to call the search tool and what queries to make
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("anthropic/claude-sonnet-4-5")
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 `name`	Registered 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()

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Overview

Key Benefits

Basic Usage

How It Works

Tool vs Context

Multiple Knowledge Bases

How Tool Names Are Generated

Cleanup

​Overview

​Key Benefits

​Basic Usage

​How It Works

​Tool vs Context

​Multiple Knowledge Bases

​How Tool Names Are Generated

​Cleanup

Overview

Key Benefits

Basic Usage

How It Works

Tool vs Context

Multiple Knowledge Bases

How Tool Names Are Generated

Cleanup