Knowledge Base: ground your agent in your content

Knowledge base (KB) is what turns a voice agent from "polite hallucinator" into "specific, accurate answerer." This page covers the full setup.

What it does

You upload documents. We chunk them, embed them, and store the embeddings in pgvector. At call time, when the caller asks a question, the retriever finds the most relevant chunks and the LLM generates an answer grounded in those chunks.

End to end, in well under 500ms.

Supported source types

• PDF — menus, FAQ documents, manuals, brochures.
• DOCX — Word documents.
• TXT — plain text.
• Markdown — .md files.
• URL crawl — paste a public URL, the crawler indexes that page.

Adding a source

Agents page → AgentDetail → Knowledge Base section → Add source.

Pick the source type, upload (or paste URL), wait ~30 seconds. The chunk count appears next to the source — that's how many embedded passages the retriever has to search.

If chunk count is 0 or much less than expected:

• Scanned PDF without text layer — OCR it first, then re-upload.
• PDF with weird encoding — save as TXT and upload that.
• URL behind auth — use a publicly accessible URL.

Best practices

The KB structure that works:

• One source-of-truth document per topic — menu, hours, FAQ, policies.
• Q&A format for FAQs — embeddings match Q&A entries far better than prose.
• Chunks under 300 words for fact-heavy content (prices, addresses).
• Chunks ~500 words for narrative content (history, brand voice).
• No duplicates — every fact in exactly one place.

What NOT to put in the KB

• Frequently-changing data (stock, prices, today's specials) → use a webhook or function call instead.
• Customer-specific data (orders, balances) → never index personal data; use function calls scoped to the caller.
• Patient/medical records → never. Use function calls with patient phone-number lookup.

Sample sizes from real deployments

When the agent gives wrong answers

Walkthrough of the most common cause and fix:

1. Caller asks about something not in the KB. The retriever returns the closest 3 chunks anyway. The LLM answers based on those, possibly making up details.
   • Fix: in the system prompt add "Use ONLY the retrieved passages. If they don't contain the answer, say 'I'll check.'"
2. Retriever picks the wrong chunks. Question and chunk share keywords but mean different things.
   • Fix: smaller chunks, Q&A format, more chunks retrieved (top-5 instead of top-3).
3. Stale data. You re-uploaded the document but the old version is still indexed.
   • Fix: delete the old source before adding the new one.

Sample test pass

Before going live, do this 10-minute test:

1. List 20 questions you expect callers to ask most often.
2. Call the agent. Ask each one.
3. Count: correct + specific, vague "I'll check", or plain wrong.

"Wrong" should be 0. "Vague" should be under 20%. If not, your KB has gaps to fill.

Per-agent vs shared KB

You can attach the same KB to multiple agents (shared) or have each agent own its own (per-agent). Trade-offs:

• Shared — single source of truth, update once, all agents see new content.
• Per-agent — different agents can have different scopes (sales agent doesn't need the support FAQ).

For most businesses, shared is the right default.