Knowledge Base

From the CLI

terminalCopy
npx zavudev agents knowledge-bases create --sender <senderId> --name "Product docs"
npx zavudev agents knowledge-bases documents add --sender <senderId> --kb <kbId> \
  --title "Pricing" --content-file ./pricing.md
npx zavudev agents knowledge-bases documents list --sender <senderId> --kb <kbId>

Processing takes a few seconds; isProcessed flips to true and chunkCount fills in. Verify retrieval actually fires with npx zavudev agents test — it reports how many chunks the answer used.

Knowledge Base

A Knowledge Base lets your AI agent answer questions using your own documents. Upload FAQs, product docs, policies, or any text content, and the agent will search for relevant information when responding to customers.

What is a Knowledge Base?

A Knowledge Base is a collection of documents that your agent can reference. When a customer asks a question, the agent:

1. Searches the knowledge base for relevant content
2. Retrieves the most relevant chunks
3. Includes that context in its prompt
4. Generates an informed response

This approach is called RAG (Retrieval Augmented Generation).

Use Cases

Via Dashboard

1. Navigate to Knowledge Bases

   Go to Senders > select your sender > Agent tab > Knowledge Bases section.

2. Create Knowledge Base

   Click Create Knowledge Base and enter:

   • Name: A descriptive name (e.g., "Product FAQs")
   • Description: What this knowledge base contains

3. Add Documents

   Click Add Document and choose how to add content:

   • Text: Paste text content directly
   • Markdown: Upload .md files
   • PDF: Upload PDF documents
   • URL: Import content from a webpage

4. Wait for Processing

   Documents are automatically chunked and embedded. This takes a few seconds for small documents, longer for large PDFs.

5. Verify

   Check the document list to see:

   • Chunk Count: Number of searchable chunks created
   • Processing Status: Whether the document is ready

Via API

Create Knowledge Base

TypeScriptcURLCopy
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const kb = await zavu.senders.agent.knowledgeBases.create("sender_abc123", {
  name: "Product FAQs",
  description: "Frequently asked questions about our products",
});

console.log("Knowledge Base created:", kb.id);

Add Document

TypeScriptcURLCopy
const document = await zavu.senders.agent.knowledgeBases.documents.create(
  "sender_abc123",
  "kb_xyz789",
  {
    title: "Return Policy",
    content: `# Return Policy

## 30-Day Returns
All products can be returned within 30 days of purchase for a full refund.

## Conditions
- Items must be unused and in original packaging
- Original receipt required
- Shipping costs are non-refundable

## How to Return
1. Contact support@example.com
2. Receive return shipping label
3. Ship item within 7 days
4. Refund processed within 5 business days

## Exceptions
- Final sale items cannot be returned
- Custom orders are non-refundable
`,
  }
);

console.log("Document added:", document.id);

List Knowledge Bases

TypeScriptcURLCopy
const kbs = await zavu.senders.agent.knowledgeBases.list("sender_abc123");

for (const kb of kbs.items) {
  console.log(`${kb.name}: ${kb.documentCount} documents, ${kb.totalChunks} chunks`);
}

List Documents

TypeScriptcURLCopy
const docs = await zavu.senders.agent.knowledgeBases.documents.list(
  "sender_abc123",
  "kb_xyz789"
);

for (const doc of docs.items) {
  console.log(`${doc.title}: ${doc.chunkCount} chunks`);
}

Delete Document

TypeScriptcURLCopy
await zavu.senders.agent.knowledgeBases.documents.delete(
  "sender_abc123",
  "kb_xyz789",
  "doc_abc123"
);

How RAG Works

CodeCopy
Customer: "What's your return policy?"
                    |
                    v
            +------------------+
            | Embed Question   |
            | Create vector    |
            +------------------+
                    |
                    v
            +------------------+
            | Vector Search    |
            | Find similar     |
            | chunks           |
            +------------------+
                    |
                    v
            +------------------+
            | Retrieve Top     |
            | Chunks (e.g., 3) |
            +------------------+
                    |
                    v
            +------------------+
            | Inject Context   |
            | into LLM Prompt  |
            +------------------+
                    |
                    v
            +------------------+
            | Generate Answer  |
            | with Context     |
            +------------------+
                    |
                    v
Customer: "You can return any item within
           30 days for a full refund. Items
           must be unused and in original
           packaging. Contact support@..."

Processing Steps

1. Chunking: Documents are split into smaller pieces (~500-1000 tokens each)
2. Embedding: Each chunk is converted to a vector using an embedding model
3. Indexing: Vectors are stored for fast similarity search
4. Retrieval: When a question arrives, we find the most similar chunks
5. Generation: Retrieved chunks are included in the LLM prompt as context

What you can put in, and where

Which formats are accepted depends on the surface, and the API is the narrowest of the three. It takes text and nothing else.

The API's POST /v1/senders/{senderId}/agent/knowledge-bases/{kbId}/documents takes title and content, both strings. There is no upload endpoint for knowledge-base files and no URL parameter: to load a PDF or a page from your own code, extract the text yourself and send it as content.

A document knows where it came from — sourceType and sourceUrl are stored and returned, so one imported from the web can be told apart from one that was pasted. They are not yet declared in the OpenAPI schema, so a generated SDK will not type them; read them from the raw response until it is.

Importing a web page

In the dashboard, open the agent, go to Knowledge, choose a knowledge base, then Add document → URL. It reads that one page — not the site — and files it under a knowledge base named after the host, so several pages of the same site group together. Add the pages that answer questions one at a time: shipping, returns, pricing.

The onboarding assistant can do the same thing if you paste a link into the chat.

This adds to what the agent knows. It does not change the agent's prompt, its model or its channels.

Document Limits

The last three are the website importer's caps. Documents you create through the API or the dashboard are bounded by content length, and by nothing else today: there is no enforced ceiling on documents per knowledge base or on knowledge bases per agent, so plan capacity from content size rather than from a document count.

Best Practices

Content Writing Tips

Good document structure:

MARKDOWNCopy
# Product Returns

## How long do I have to return an item?
You have 30 days from the delivery date to return any item for a full refund.

## What condition must items be in?
Items must be unused, unworn, and in original packaging with all tags attached.

## How do I start a return?
1. Email support@example.com with your order number
2. We'll send a prepaid return label within 24 hours
3. Ship the item within 7 days
4. Refund processes within 5 business days of receipt

Poor document structure:

CodeCopy
Returns are processed within the timeframe specified in our terms. Contact support for assistance with any issues you may have regarding your order.

Example Documents

FAQ Document

MARKDOWNCopy
# Shipping FAQs

## How long does shipping take?
- Standard shipping: 5-7 business days
- Express shipping: 2-3 business days
- Same-day delivery: Available in select cities

## How much does shipping cost?
- Free shipping on orders over $50
- Standard shipping: $5.99
- Express shipping: $12.99

## Do you ship internationally?
Yes! We ship to over 50 countries. International shipping takes 7-14 business days.

## Can I track my order?
Yes, you'll receive a tracking number via email once your order ships.

Product Document

MARKDOWNCopy
# Pro Widget X100

## Overview
The Pro Widget X100 is our flagship widget designed for professional use.

## Specifications
- Weight: 2.5 lbs
- Dimensions: 10" x 6" x 4"
- Battery life: 12 hours
- Warranty: 2 years

## Features
- Wireless connectivity (Bluetooth 5.0 and WiFi)
- Water-resistant (IP67 rating)
- Voice control compatible

## Price
- Standard edition: $299
- Pro edition: $449 (includes accessories)

## Common Questions

### Is it compatible with Mac?
Yes, works with macOS 10.15 and later.

### Can I use it outdoors?
Yes, the IP67 rating means it's water and dust resistant.

Next Steps