Knowledge & RAG Examples

Complete, runnable examples for building RAG systems with Agentium. Covers knowledge bases, vector stores, embeddings, hybrid search, and full agent-powered retrieval pipelines.

1. Basic KnowledgeBase

Create a knowledge base, add documents, and query by semantic similarity.

import {
  KnowledgeBase,
  InMemoryVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";

const embedder = new OpenAIEmbedding();
const vectorStore = new InMemoryVectorStore(embedder);

const kb = new KnowledgeBase({
  name: "Product Docs",
  vectorStore,
});

await kb.initialize();

await kb.addDocuments([
  {
    id: "pricing",
    content: "The Pro plan costs $49/month and includes unlimited agents, 100k API calls, and priority support.",
    metadata: { category: "pricing" },
  },
  {
    id: "features",
    content: "Agentium supports multi-agent teams, workflows, RAG, voice, and multi-modal inputs.",
    metadata: { category: "features" },
  },
  {
    id: "setup",
    content: "Install with npm install @agentium/core. Set OPENAI_API_KEY to get started.",
    metadata: { category: "getting-started" },
  },
]);

// Search by semantic similarity
const results = await kb.search("How much does it cost?", { topK: 3 });

for (const r of results) {
  console.log(`[${r.id}] (score: ${r.score.toFixed(3)}) ${r.content}`);
}

2. Knowledge as Tool

Turn a KnowledgeBase into a tool the agent calls automatically during runs.

import {
  Agent,
  openai,
  KnowledgeBase,
  InMemoryVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";

const embedder = new OpenAIEmbedding();
const vectorStore = new InMemoryVectorStore(embedder);

const kb = new KnowledgeBase({
  name: "Support KB",
  vectorStore,
});

await kb.initialize();

await kb.addDocuments([
  { id: "reset", content: "To reset your password, go to Settings > Security > Reset Password." },
  { id: "billing", content: "Invoices are generated on the 1st of each month and sent to the account email." },
  { id: "api-limits", content: "Free plan: 1,000 API calls/day. Pro plan: 100,000 API calls/day." },
]);

const agent = new Agent({
  name: "support-bot",
  model: openai("gpt-4o"),
  instructions: "Answer user questions using the knowledge base. Always cite the source document.",
  tools: [
    kb.asTool({
      toolName: "search_support",
      description: "Search the support knowledge base for answers",
      topK: 3,
      minScore: 0.5,
    }),
  ],
});

const result = await agent.run("How do I reset my password?");
console.log(result.text);

Custom result formatting

const tool = kb.asTool({
  toolName: "search_docs",
  topK: 5,
  formatResults: (results) =>
    results
      .map((r) => `[${r.id}] (relevance: ${(r.score * 100).toFixed(0)}%) ${r.content}`)
      .join("\n\n"),
});

3. OpenAI Embeddings

Use OpenAI’s embedding models to convert text into vectors.

import { OpenAIEmbedding } from "@agentium/core";

// Default model: text-embedding-3-small (1536 dimensions)
const embedder = new OpenAIEmbedding({
  apiKey: process.env.OPENAI_API_KEY,
  model: "text-embedding-3-small",
});

// Embed a single string
const vector = await embedder.embed("What is Agentium?");
console.log(`Dimensions: ${vector.length}`); // 1536

// Batch embed multiple strings
const vectors = await embedder.embedBatch([
  "Agentium is a TypeScript agent framework.",
  "It supports RAG, tools, and multi-agent teams.",
  "Install with npm install @agentium/core.",
]);
console.log(`Batch size: ${vectors.length}`); // 3

Higher accuracy model

const highAccuracy = new OpenAIEmbedding({
  model: "text-embedding-3-large", // 3072 dimensions
});

const vector = await highAccuracy.embed("Detailed technical analysis...");
console.log(`Dimensions: ${vector.length}`); // 3072

4. Google Embeddings

Use Google’s embedding models as an alternative to OpenAI.

import { GoogleEmbedding } from "@agentium/core";

const embedder = new GoogleEmbedding({
  apiKey: process.env.GOOGLE_API_KEY,
  model: "text-embedding-004", // 768 dimensions
});

const vector = await embedder.embed("What is Agentium?");
console.log(`Dimensions: ${vector.length}`); // 768

const vectors = await embedder.embedBatch([
  "First document.",
  "Second document.",
]);
console.log(`Batch size: ${vectors.length}`); // 2

Using Google embeddings with a knowledge base

import { KnowledgeBase, InMemoryVectorStore, GoogleEmbedding } from "@agentium/core";

const embedder = new GoogleEmbedding();
const vectorStore = new InMemoryVectorStore(embedder);

const kb = new KnowledgeBase({
  name: "docs",
  vectorStore,
});

await kb.initialize();
await kb.addDocuments([
  { id: "intro", content: "Agentium is a TypeScript agent framework." },
]);

const results = await kb.search("What is Agentium?");
console.log(results[0].content);

5. In-Memory Vector Store

Quickstart with in-memory vectors. No external dependencies — data is lost on restart.

import { InMemoryVectorStore, OpenAIEmbedding } from "@agentium/core";

const embedder = new OpenAIEmbedding();
const store = new InMemoryVectorStore(embedder);

await store.initialize();

// Upsert documents
await store.upsert("articles", {
  id: "article-1",
  content: "TypeScript 5.4 introduces the NoInfer utility type for better generic inference.",
  metadata: { author: "TS Team", year: 2024 },
});

await store.upsertBatch("articles", [
  { id: "article-2", content: "Bun 1.2 adds native S3 support and improved Node.js compatibility." },
  { id: "article-3", content: "Deno 2.0 focuses on Node.js compatibility and workspaces." },
]);

// Search by semantic similarity
const results = await store.search("articles", "TypeScript generics improvements", {
  topK: 2,
  minScore: 0.5,
});

for (const r of results) {
  console.log(`[${r.id}] score=${r.score.toFixed(3)}: ${r.content}`);
}

// Get a specific document
const doc = await store.get("articles", "article-1");
console.log(doc?.content);

// Delete a document
await store.delete("articles", "article-3");

6. PgVector Store

PostgreSQL-backed vector store using the pgvector extension. Persists across restarts.

npm install pg pgvector

import { PgVectorStore, OpenAIEmbedding } from "@agentium/core";

const embedder = new OpenAIEmbedding();

const store = new PgVectorStore(
  {
    connectionString: process.env.DATABASE_URL!,
    dimensions: 1536,
  },
  embedder
);

await store.initialize(); // Creates pgvector extension + tables

await store.upsertBatch("knowledge", [
  {
    id: "security-policy",
    content: "All employees must use 2FA and complete annual security training.",
    metadata: { department: "IT", updated: "2026-01-15" },
  },
  {
    id: "remote-work",
    content: "Remote work is allowed up to 3 days per week with manager approval.",
    metadata: { department: "HR", updated: "2025-11-01" },
  },
  {
    id: "expenses",
    content: "Travel expenses over $500 require VP approval before booking.",
    metadata: { department: "Finance", updated: "2026-02-10" },
  },
]);

const results = await store.search("knowledge", "work from home policy", {
  topK: 3,
});

for (const r of results) {
  console.log(`[${r.id}] ${r.score.toFixed(3)}: ${r.content}`);
}

await store.close();

7. MongoDB Vector Store

MongoDB Atlas-backed vector store. Requires an Atlas Search index for production.

npm install mongodb

import { MongoDBVectorStore, OpenAIEmbedding } from "@agentium/core";

const embedder = new OpenAIEmbedding();

const store = new MongoDBVectorStore(
  {
    uri: process.env.MONGO_URI!,
    dbName: "myapp",
    indexName: "vector_index",
    dimensions: 1536,
  },
  embedder
);

await store.initialize();

await store.upsertBatch("products", [
  {
    id: "laptop-1",
    content: "MacBook Pro 16-inch with M4 Max chip, 48GB RAM, 1TB SSD. $3,499.",
    metadata: { category: "electronics", price: 3499 },
  },
  {
    id: "laptop-2",
    content: "ThinkPad X1 Carbon Gen 12, Intel Ultra 7, 32GB RAM, 512GB SSD. $1,849.",
    metadata: { category: "electronics", price: 1849 },
  },
  {
    id: "desk-1",
    content: "Standing desk with programmable height presets, bamboo top, 60x30 inches. $599.",
    metadata: { category: "furniture", price: 599 },
  },
]);

const results = await store.search("products", "powerful laptop for development", {
  topK: 2,
});

for (const r of results) {
  console.log(`[${r.id}] ${r.score.toFixed(3)}: ${r.content}`);
}

await store.close();

8. Qdrant Vector Store

Qdrant cloud or self-hosted vector database. Ideal for dedicated vector search workloads.

npm install @qdrant/js-client-rest

import { QdrantVectorStore, OpenAIEmbedding } from "@agentium/core";

const embedder = new OpenAIEmbedding();

const store = new QdrantVectorStore(
  {
    url: process.env.QDRANT_URL ?? "http://localhost:6333",
    apiKey: process.env.QDRANT_API_KEY,
    dimensions: 1536,
  },
  embedder
);

await store.initialize();

await store.upsertBatch("support-tickets", [
  {
    id: "ticket-101",
    content: "Customer unable to log in after password reset. Error: invalid_grant.",
    metadata: { priority: "high", status: "open" },
  },
  {
    id: "ticket-102",
    content: "Billing page shows incorrect subscription tier after upgrade.",
    metadata: { priority: "medium", status: "open" },
  },
  {
    id: "ticket-103",
    content: "API rate limit exceeded during bulk import. Need temporary limit increase.",
    metadata: { priority: "low", status: "resolved" },
  },
]);

const results = await store.search("support-tickets", "login authentication issue", {
  topK: 2,
  minScore: 0.7,
});

for (const r of results) {
  console.log(`[${r.id}] ${r.score.toFixed(3)}: ${r.content}`);
}

9. Hybrid Search

Combine vector (semantic) and BM25 (keyword) search with Reciprocal Rank Fusion for the best retrieval accuracy.

import {
  Agent,
  openai,
  KnowledgeBase,
  InMemoryVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";

const kb = new KnowledgeBase({
  name: "Company Policies",
  vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()),
  searchMode: "hybrid",
  hybridConfig: {
    vectorWeight: 1.0,
    keywordWeight: 1.0,
    rrfK: 60,
  },
});

await kb.initialize();

await kb.addDocuments([
  { id: "pto", content: "Employees accrue 20 days of PTO per year. Unused PTO carries over up to 5 days." },
  { id: "401k", content: "The company matches 401(k) contributions up to 6% of base salary." },
  { id: "security", content: "All employees must complete SOC 2 compliance training annually. 2FA is mandatory." },
  { id: "remote", content: "Remote work is allowed up to 3 days per week with manager approval." },
]);

// Compare all three search modes
const vectorResults  = await kb.search("401k matching", { topK: 3, searchMode: "vector" });
const keywordResults = await kb.search("401k matching", { topK: 3, searchMode: "keyword" });
const hybridResults  = await kb.search("401k matching", { topK: 3, searchMode: "hybrid" });

console.log("Vector results:", vectorResults.map((r) => r.id));
console.log("Keyword results:", keywordResults.map((r) => r.id));
console.log("Hybrid results:", hybridResults.map((r) => r.id));

Hybrid search with an agent

const agent = new Agent({
  name: "policy-bot",
  model: openai("gpt-4o"),
  instructions: "Answer questions about company policies. Always search first.",
  tools: [
    kb.asTool({ topK: 3, searchMode: "hybrid" }),
  ],
});

const result = await agent.run("What's the 401k match and how many PTO days do we get?");
console.log(result.text);

Tuning for technical docs

const technicalKb = new KnowledgeBase({
  name: "API Reference",
  vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()),
  searchMode: "hybrid",
  hybridConfig: {
    vectorWeight: 1.0,
    keywordWeight: 2.0, // favor exact term matches for API names, error codes
    rrfK: 40,
  },
});

10. PageIndex Toolkit

Reasoning-based document retrieval without vectors. Best for complex, structured documents like financial reports and legal filings.

import { Agent, openai, PageIndexToolkit } from "@agentium/core";

const pageindex = new PageIndexToolkit({
  apiKey: process.env.PAGEINDEX_API_KEY!,
  timeout: 120_000,
});

const agent = new Agent({
  name: "document-analyst",
  model: openai("gpt-4o"),
  instructions: "Analyze uploaded documents. Answer questions with page citations.",
  tools: [...pageindex.getTools()],
});

// Submit and analyze a document
const result = await agent.run(
  "Submit https://example.com/annual-report-2025.pdf and summarize the revenue breakdown by business segment."
);
console.log(result.text);

// Multi-document comparison
const comparison = await agent.run(
  "Compare the risk factors section between the 2024 and 2025 annual reports."
);
console.log(comparison.text);

11. RAG Agent

A full agent with a knowledge base for answering questions grounded in your documents.

import {
  Agent,
  openai,
  KnowledgeBase,
  InMemoryVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";

const embedder = new OpenAIEmbedding();
const vectorStore = new InMemoryVectorStore(embedder);

const kb = new KnowledgeBase({
  name: "company-docs",
  vectorStore,
  searchMode: "hybrid",
});

await kb.initialize();

await kb.addDocuments([
  {
    id: "pricing-pro",
    content: "The Pro plan costs $49/month. Includes unlimited agents, 100k API calls/day, and priority support.",
    metadata: { category: "pricing" },
  },
  {
    id: "pricing-enterprise",
    content: "Enterprise plan is custom-priced. Includes SSO, SLA, dedicated support, and on-premise deployment.",
    metadata: { category: "pricing" },
  },
  {
    id: "api-auth",
    content: "API authentication uses Bearer tokens. Generate keys at Settings > API Keys. Keys can be scoped to specific agents.",
    metadata: { category: "api" },
  },
  {
    id: "webhooks",
    content: "Webhooks notify your server of agent events. Configure at Settings > Webhooks. Supports run.completed, tool.called, and error events.",
    metadata: { category: "api" },
  },
  {
    id: "teams",
    content: "Multi-agent teams support four patterns: coordinate, broadcast, route, and collaborate. Use Teams for complex multi-step workflows.",
    metadata: { category: "features" },
  },
]);

const agent = new Agent({
  name: "docs-assistant",
  model: openai("gpt-4o"),
  instructions: `You are a helpful assistant for Agentium documentation.
- Always search the knowledge base before answering.
- Cite the source document ID in your response.
- If the knowledge base doesn't have the answer, say so clearly.`,
  tools: [
    kb.asTool({
      toolName: "search_docs",
      description: "Search Agentium documentation",
      topK: 3,
      searchMode: "hybrid",
    }),
  ],
});

const result = await agent.run("How do I set up API authentication and webhooks?");
console.log(result.text);

12. Multi-Source RAG

An agent with multiple knowledge bases, each specialized for different document types.

import {
  Agent,
  openai,
  KnowledgeBase,
  InMemoryVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";

const embedder = new OpenAIEmbedding();

// Knowledge base for product documentation
const productKb = new KnowledgeBase({
  name: "Product Docs",
  vectorStore: new InMemoryVectorStore(embedder),
  searchMode: "hybrid",
});
await productKb.initialize();
await productKb.addDocuments([
  { id: "install", content: "Install Agentium: npm install @agentium/core. Requires Node.js 20+." },
  { id: "agents", content: "Create agents with new Agent({ name, model, tools, instructions })." },
  { id: "tools", content: "Define custom tools with defineTool({ name, description, parameters, execute })." },
]);

// Knowledge base for support tickets
const supportKb = new KnowledgeBase({
  name: "Support Tickets",
  vectorStore: new InMemoryVectorStore(embedder),
  searchMode: "hybrid",
});
await supportKb.initialize();
await supportKb.addDocuments([
  { id: "ticket-201", content: "Issue: Agent times out on large contexts. Fix: Enable context compaction." },
  { id: "ticket-202", content: "Issue: MCP tools not discovered. Fix: Check MCP server is running and accessible." },
  { id: "ticket-203", content: "Issue: High token costs. Fix: Use toolRouter and toolResultLimit to reduce prompt tokens." },
]);

// Knowledge base for internal processes
const processKb = new KnowledgeBase({
  name: "Internal Processes",
  vectorStore: new InMemoryVectorStore(embedder),
  searchMode: "hybrid",
});
await processKb.initialize();
await processKb.addDocuments([
  { id: "deploy", content: "Deployments happen every Tuesday. Hotfixes can be deployed anytime with VP approval." },
  { id: "oncall", content: "On-call rotation is weekly. Primary gets paged first, secondary after 15 min." },
]);

const agent = new Agent({
  name: "unified-assistant",
  model: openai("gpt-4o"),
  instructions: `You have access to three knowledge bases:
- Product Docs: how to use Agentium
- Support Tickets: known issues and fixes
- Internal Processes: company procedures

Search the most relevant knowledge base for each question. You can search multiple if needed.`,
  tools: [
    productKb.asTool({
      toolName: "search_product_docs",
      description: "Search Agentium product documentation",
      topK: 3,
    }),
    supportKb.asTool({
      toolName: "search_support_tickets",
      description: "Search past support tickets for known issues and fixes",
      topK: 3,
    }),
    processKb.asTool({
      toolName: "search_processes",
      description: "Search internal company processes and procedures",
      topK: 3,
    }),
  ],
});

const result = await agent.run(
  "My agent is timing out and I also need to know when the next deployment window is."
);
console.log(result.text);

13. Document Ingestion Pipeline

A workflow to ingest documents from multiple sources, chunk them, and embed into a vector store.

import {
  KnowledgeBase,
  PgVectorStore,
  OpenAIEmbedding,
} from "@agentium/core";
import { readFile, readdir } from "node:fs/promises";
import { join, extname } from "node:path";

const embedder = new OpenAIEmbedding();

const store = new PgVectorStore(
  { connectionString: process.env.DATABASE_URL!, dimensions: 1536 },
  embedder
);

const kb = new KnowledgeBase({
  name: "ingested-docs",
  vectorStore: store,
  searchMode: "hybrid",
});

await kb.initialize();

// --- Chunking utility ---
function chunkText(text: string, maxChars = 1000, overlap = 200): string[] {
  const chunks: string[] = [];
  let start = 0;
  while (start < text.length) {
    const end = Math.min(start + maxChars, text.length);
    chunks.push(text.slice(start, end));
    start += maxChars - overlap;
  }
  return chunks;
}

// --- Ingest a directory of text/markdown files ---
async function ingestDirectory(dirPath: string) {
  const files = await readdir(dirPath);
  const textFiles = files.filter((f) =>
    [".txt", ".md", ".mdx"].includes(extname(f))
  );

  let totalChunks = 0;

  for (const file of textFiles) {
    const content = await readFile(join(dirPath, file), "utf-8");
    const chunks = chunkText(content, 1000, 200);

    const docs = chunks.map((chunk, i) => ({
      id: `${file}-chunk-${i}`,
      content: chunk,
      metadata: {
        source: file,
        chunkIndex: i,
        totalChunks: chunks.length,
      },
    }));

    await kb.addDocuments(docs);
    totalChunks += docs.length;
    console.log(`Ingested ${file}: ${chunks.length} chunks`);
  }

  console.log(`Total: ${totalChunks} chunks from ${textFiles.length} files`);
}

// --- Ingest from a URL ---
async function ingestUrl(url: string, docId: string) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status}`);
  const text = await res.text();

  const chunks = chunkText(text, 1000, 200);
  const docs = chunks.map((chunk, i) => ({
    id: `${docId}-chunk-${i}`,
    content: chunk,
    metadata: { source: url, chunkIndex: i },
  }));

  await kb.addDocuments(docs);
  console.log(`Ingested ${url}: ${chunks.length} chunks`);
}

// --- Run the pipeline ---
await ingestDirectory("./docs/content");
await ingestUrl("https://example.com/faq.txt", "faq");

// Verify
const results = await kb.search("How do I get started?", { topK: 3 });
for (const r of results) {
  console.log(`[${r.id}] (${r.score.toFixed(3)}) ${r.content.slice(0, 100)}...`);
}

await store.close();

Using the ingested KB with an agent

import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "ingested-docs-agent",
  model: openai("gpt-4o"),
  instructions: "Answer questions using the ingested document collection. Cite sources.",
  tools: [
    kb.asTool({
      topK: 5,
      searchMode: "hybrid",
      formatResults: (results) =>
        results
          .map((r) => `[${r.metadata?.source ?? r.id}] ${r.content}`)
          .join("\n---\n"),
    }),
  ],
});

const result = await agent.run("Summarize the key topics covered in our documentation.");
console.log(result.text);

Core Examples

Multi-Agent & Orchestration

Knowledge & RAG

Deployment & Transport

Monitoring & Cost

Advanced & Integrations

End-to-End Applications

Knowledge & RAG Examples

1. Basic KnowledgeBase

2. Knowledge as Tool

Custom result formatting

3. OpenAI Embeddings

Higher accuracy model

4. Google Embeddings

Using Google embeddings with a knowledge base

5. In-Memory Vector Store

6. PgVector Store

7. MongoDB Vector Store

8. Qdrant Vector Store

9. Hybrid Search

Hybrid search with an agent

Tuning for technical docs

10. PageIndex Toolkit

11. RAG Agent

12. Multi-Source RAG

13. Document Ingestion Pipeline

Using the ingested KB with an agent

​1. Basic KnowledgeBase

​2. Knowledge as Tool

​Custom result formatting

​3. OpenAI Embeddings

​Higher accuracy model

​4. Google Embeddings

​Using Google embeddings with a knowledge base

​5. In-Memory Vector Store

​6. PgVector Store

​7. MongoDB Vector Store

​8. Qdrant Vector Store

​9. Hybrid Search

​Hybrid search with an agent

​Tuning for technical docs

​10. PageIndex Toolkit

​11. RAG Agent

​12. Multi-Source RAG

​13. Document Ingestion Pipeline

​Using the ingested KB with an agent

1. Basic KnowledgeBase

2. Knowledge as Tool

Custom result formatting

3. OpenAI Embeddings

Higher accuracy model

4. Google Embeddings

Using Google embeddings with a knowledge base

5. In-Memory Vector Store

6. PgVector Store

7. MongoDB Vector Store

8. Qdrant Vector Store

9. Hybrid Search

Hybrid search with an agent

Tuning for technical docs

10. PageIndex Toolkit

11. RAG Agent

12. Multi-Source RAG

13. Document Ingestion Pipeline

Using the ingested KB with an agent