Knowledge Base

A knowledge base (KnowledgeBase) is an agent’s external source of knowledge — a place to store static material such as product docs, FAQs, and articles. Attach it to an agent and VeADK automatically injects a retrieval tool, so the agent retrieves relevant snippets before answering and produces more accurate, better-grounded responses (RAG).

Unified entry point: `KnowledgeBase`

Regardless of the backend, everything goes through the unified veadk.knowledgebase.KnowledgeBase. It selects the storage backend through backend and exposes a consistent ingestion and retrieval interface. Ingestion supports three sources:

From files: kb.add_from_files([...]);
From a directory: kb.add_from_directory("./docs");
From text: kb.add_from_text([...]).

from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="local", index="company_faq")

kb.add_from_text(
    [
        "The standard annual leave is 15 days per year, available after one year of service.",
        "With manager approval, employees may work remotely up to 2 days per week.",
    ]
)

Common parameters

The fields of KnowledgeBase are common to all backends:

Parameter	Type	Default	Description
`backend`	`"local" \| "opensearch" \| "redis" \| "tos_vector" \| "viking" \| "context_search"`	`"local"`	Selects the backend.
`backend_config`	`dict`	`{}`	Backend-specific settings. When non-empty, the configuration must include `index`.
`top_k`	`int`	`10`	Number of most-similar snippets returned during retrieval. Can be overridden per call in `search`.
`app_name`	`str`	`""`	Application name. Used as the fallback for `index` when it is empty.
`index`	`str`	`""`	Knowledge base index/collection name. Falls back to `app_name` when empty; initialization fails if both are empty.
`name`	`str`	`user_knowledgebase`	Knowledge base name, used to describe it to the agent.
`description`	`str`	`This knowledgebase stores some user-related information.`	Knowledge base description, used to explain its purpose to the agent.
`enable_profile`	`bool`	`False`	Whether to enable knowledge base profiling.
`query_with_user_profile`	`bool`	`False`	Whether to incorporate the user profile during retrieval. This requires the Viking backend.

Vector backends (local, opensearch, redis, tos_vector) embed the knowledge text and require the extensions dependency pip install "veadk-python[extensions]" plus an embedding model configured (env prefix MODEL_EMBEDDING_, falling back to MODEL_AGENT_API_KEY). viking and context_search are managed services that embed on the server side, so no local embedding is needed.

Choosing a backend

Use local for debugging; for production prefer the managed viking or context_search. If you already run a vector store, choose opensearch, redis, or tos_vector.

Backend	Storage	Dependencies	Use case	Docs
`local`	In-memory vector index	`extensions` + embedding	Local debugging (data lost on exit)	Local
`opensearch`	OpenSearch vector store	OpenSearch + `extensions` + embedding	Self-hosted vector search	OpenSearch
`redis`	Redis vector store	Redis (RediSearch) + `extensions` + embedding	Low-latency self-hosted vector search	Redis
`tos_vector`	TOS vector bucket	Volcengine account + `extensions` + embedding	Volcengine object-storage vector store	TOS Vector
`viking`	VikingDB knowledge base (managed)	Volcengine account	Recommended for production	VikingDB
`context_search`	Context Search (managed)	Volcengine account	Recommended for production	Context Search

Binding to an agent

Pass knowledgebase to Agent and the agent automatically gains a load_knowledgebase tool, deciding on its own whether to search the knowledge base when answering.

import asyncio

from veadk import Agent, Runner
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="local", index="company_faq")
kb.add_from_text("The standard annual leave is 15 days per year, available after one year of service.")

agent = Agent(
    name="kb_agent",
    instruction="You are a knowledgeable assistant. Prefer the knowledge base when answering.",
    knowledgebase=kb,
)

runner = Runner(agent=agent, app_name="company_faq")
print(asyncio.run(runner.run(messages="How many days of annual leave do I get?")))

Direct retrieval

Besides automatic retrieval at agent runtime, you can call search directly for semantic search, useful for debugging or custom RAG. A top_k of 0 uses the value set at construction.

entries = kb.search(query="annual leave", top_k=3)
for entry in entries:
    print(entry.content)

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Unified entry point: `KnowledgeBase`

Common parameters

Choosing a backend

Binding to an agent

Direct retrieval

​Unified entry point: KnowledgeBase

​Common parameters

​Choosing a backend

​Binding to an agent

​Direct retrieval

Unified entry point: `KnowledgeBase`

Common parameters

Choosing a backend

Binding to an agent

Direct retrieval