Knowledge Base for an AI Agent: Designing Sources So It Answers Correctly

An AI support agent is only as good as the knowledge base behind it. You can pick the smartest model, write a tight system prompt, and wire up every tool — and the agent will still confidently tell a customer the wrong return window if the only place that window is written down is a three-year-old PDF that contradicts your live help center. The model isn't the bottleneck. The knowledge base is.

This is the part most teams under-invest in. They connect a help center, upload a folder of documents, and assume retrieval will sort it out. It won't, not on its own. The AI agents that answer correctly are backed by a knowledge base that was designed — scoped deliberately, deduplicated, kept current, and shaped so the retrieval layer can find the one right answer instead of three competing ones.

This post is the practical playbook for that work, grounded in how knowledge sources actually behave inside Macha — the AI agent layer that sits on top of your existing Zendesk, Freshdesk, Gorgias, or Front helpdesk. Macha builds agents that resolve and triage tickets using your knowledge plus live tools; the knowledge half is what we're focused on here. Everything below applies whether you run Macha or build your own retrieval stack — but the screenshots show you exactly where these decisions live.

What a "knowledge source" actually is

In Macha, a knowledge source is any body of content your agents can search to answer a question: uploaded documents, a crawled website, a single indexed webpage, or a live connector feed from Google Workspace, Notion, Confluence, or a connected Zendesk Help Center. You manage them all from one Sources page.

There are two fundamentally different kinds of source, and the difference matters for how you design:

• Indexed snapshots — uploaded files, crawled sites, and single webpages. Macha ingests the content once. Small files get injected directly into the agent's prompt; larger files are chunked, embedded, and searched on demand. The agent reads the version that existed at ingestion time until you re-index.
• Live connector sources — Google Docs and Sheets, Notion pages, Confluence spaces, and your help center. These read the latest content in real time. Edit the underlying doc and the agent sees the change with no re-upload.

That single distinction drives a lot of design decisions. Anything that changes often — pricing, SLAs, seasonal policies — belongs in a live source so it can never go stale. Anything stable and authoritative — a finalized returns policy, a runbook — is fine as an indexed upload. Get this wrong and your agent will cite a number that was correct last quarter.

Two kinds of knowledge: declarative vs procedural

Before you organize anything, it helps to separate the two kinds of content a knowledge base for an AI agent actually holds, because they want to be written differently:

• Declarative knowledge — facts and policies. "Returns are accepted within 30 days." "The Pro plan includes priority support." This is reference material the agent quotes. It should be short, unambiguous, and stated once, in one place.
• Procedural knowledge — steps and decisions. "How to process a warranty replacement," "when to escalate a billing dispute." This is workflow the agent follows. It should be written as explicit, ordered steps with the branch conditions made obvious, not buried in narrative prose.

The common failure is writing procedural knowledge as if it were declarative — a wall of paragraphs describing a process the agent then has to reverse-engineer into steps. Write the steps as steps. A retrieval-augmented agent reproduces structure it can see; it rarely invents structure that isn't there.

Chunking and metadata, briefly

You don't tune the embedding pipeline in Macha, but understanding how it splits content tells you how to write for it. Documents are broken into chunks — passages of a few hundred words — that get embedded and retrieved individually. The agent usually sees the matching chunk, not the whole file. Two practical consequences:

• Keep one idea per chunk. A clear heading every few hundred words gives the splitter a natural boundary and keeps a single retrieved passage self-contained. A rule split across two chunks ("EU customers…" in one, "…get 30 days" in the next) retrieves badly.
• Front-load the answer. Lead each section with the fact or the first step, then add context. Retrieval rewards passages where the answer is near the top.

Metadata is the other half. Descriptive filenames and headings are signal the retrieval layer uses — "SLA Guidelines & Response Times" out-retrieves "Support Doc v4 FINAL." Naming sources for the topic they own, and scoping them to the right agent (more on that below), is the lightweight tagging that keeps the right chunk surfacing for the right question.

The principle that beats everything else: one source of truth per fact

The single biggest predictor of whether an agent answers correctly isn't volume — it's consistency. Independent RAG research makes this blunt: a well-organized knowledge base of roughly 200 clear, accurate documents outperforms a chaotic pile of 2,000, and clean, single-source-of-truth content is what pushes retrieval-augmented agents into the 85–95% factual-accuracy range. The reason is simple and a little humbling: when two chunks disagree, the model can't reason its way to which one is right. It just picks one. Often the wrong one.

So the first design pass on any knowledge library is a deduplication and reconciliation pass, not an addition pass:

1. Find the duplicates. Search your sources for the same topic — "refund," "shipping time," "cancellation" — and you'll usually find it described in three places with three slightly different answers.
2. Pick the canonical home. One source owns each fact. The returns policy lives in one document. Everything else either links to it or is deleted.
3. Collapse contradictions into a decision tree. When edge cases genuinely differ ("EU customers get 30 days, US gets 14"), don't leave that as two vague paragraphs in two files. Write it as one explicit, conditional chunk so the agent retrieves the whole rule at once.

You are not building a comprehensive archive. You are building the smallest set of documents that unambiguously answers your real questions. Less, but correct, beats more-but-conflicting every time.

Match the ingestion method to the content

Macha gives you three ways to add non-connector knowledge, and each suits a different kind of content. Choosing the right one is half the battle.

Upload documents for stable, authoritative policy

Uploads accept PDF, DOCX, TXT, CSV, and XLSX — up to 20MB each, 10 files at a time. This is the right home for the canonical artifacts: your returns policy, escalation matrix, SLA guidelines, support team playbook.

A few design notes that pay off:

• One topic per file, named for the topic. "SLA Guidelines & Response Times" retrieves better than "Support Doc v4 FINAL." Filenames and headings are signal the retrieval layer uses.
• Strip the noise. A 40-page onboarding deck with two pages of actual policy is worse than a two-page policy doc. Extra prose dilutes retrieval and burns context.
• Prefer text-native files. A clean DOCX or TXT chunks far more reliably than a scanned-image PDF.

Crawl a website for breadth you don't want to hand-curate

The Add Website path crawls and indexes a site. You set a Crawl Depth — how many link-hops deep to follow — which defaults to 10 and goes up to 50, with a system limit of 200 pages per source.

Crawling is powerful and easy to misuse. The trap is pointing it at your whole marketing site and indexing careers pages, blog archives, and legal boilerplate that have nothing to do with support — all of which become retrieval noise. Design it instead:

• Crawl a sub-path, not the root. Point it at docs.yoursite.com or /help, not the homepage.
• Keep depth shallow on purpose. Depth 2–3 from a documentation index usually captures the real content; depth 50 mostly captures the long tail you didn't want.
• Mind the 200-page ceiling. If a site is bigger than that, split it into focused sources by section rather than letting the crawler choose 200 pages at random.

(One field note: Macha raised the crawler's per-page size limit from 512KB to 2MB in April 2026 specifically because content-heavy pages — large e-commerce and docs pages — were silently failing to ingest. If you crawled a big site before then and it looked thin, it's worth re-running.)

Index a single webpage for one canonical URL

The Add Webpage path indexes exactly one URL. Use it when a single page is the authority — a status page, one pricing page, a specific policy article — and you don't want a crawler wandering off it.

Connect live sources so knowledge can never go stale

The most underused accuracy lever is the live connector source. Connect Google Workspace, Notion, or Confluence and Macha automatically creates a data source that reads the current content every time — no re-upload, no re-index. (Connecting Confluence auto-creates a source the same way Google and Notion do; for Google, a native file picker lets you select specific Docs and Sheets instead of pasting document IDs.)

The design move here is to put your volatile knowledge where your team already edits it. If your support leads keep the escalation runbook in Notion and update it weekly, connect Notion rather than exporting a PDF every Friday that's wrong by Monday. The agent then answers from the same living document your humans trust. This is the cleanest way to keep "one source of truth" and "always current" at the same time — they're usually in tension, and a live connector resolves it.

Your helpdesk's own knowledge base counts too. A connected Zendesk Help Center appears as a source — in the library above it shows 28 published articles, indexed and Ready — so the public articles your team already maintains become agent knowledge for free. For the deeper Zendesk-specific setup, see how Macha works on top of Zendesk.

Scope what each agent reads — don't feed everything to everyone

Connecting a source to your workspace is not the same as giving it to an agent. On each agent's configuration page, the Data Sources card controls which sources that specific agent can search — and a per-source scope toggle lets you choose All documents or hand-pick Selected ones.

This is where teams quietly fix a lot of wrong answers. A billing agent that can also see your shipping FAQ will sometimes retrieve a shipping chunk for a payment question and confidently answer off-topic. Narrow knowledge improves precision. Give the refund agent the refund policy and the order data — not the entire library.

Sub-agents take this further: in Macha, an agent can delegate to specialist sub-agents (up to three levels deep), and each sub-agent carries its own knowledge base. That lets you build a clean division of labor — a "Policy" sub-agent scoped to policy docs, a "Product" sub-agent scoped to product docs — instead of one generalist agent rummaging through everything. Smaller, well-scoped knowledge per agent is almost always more accurate than one big shared pile.

Close the loop: find gaps from the tickets themselves

A knowledge library is never finished. Every authoritative guide on the subject — from Zendesk to support-AI vendors — lands on the same cadence: review regularly, and mine your own tickets for the questions your knowledge doesn't yet answer. The questions customers actually ask are the spec for what your knowledge base is missing.

Macha gives you a structured way to do this with Studies — bulk AI analysis over your real ticket history. Run a study that summarizes and categorizes the last few weeks of tickets, and the topics with no clean answer in your sources are your content backlog. Better still, a completed Study can be pushed straight into a knowledge source: each result row becomes an indexed document (the fields you select are merged into one article body per record), so insights mined from real resolved tickets become searchable context on the next live ticket. Analyze the past, then let the present agents draw on it.

The practical loop:

1. Ship a tight, deduplicated set of sources.
2. Watch what the agent gets wrong or escalates.
3. Trace each miss to a gap or a contradiction in knowledge — not the model.
4. Fix the source, re-index, repeat.

Most "the AI is dumb" complaints are knowledge bugs wearing a model costume. Fix the source and the answer fixes itself.

Watch-outs: when good knowledge design still bites

No approach is free. Be honest about the trade-offs:

• Indexed sources go stale silently. An uploaded PDF or a crawled site reflects the moment you ingested it. If the underlying content changes, you have to re-index — nothing prompts you. For anything that moves, prefer a live connector.
• Crawlers over-collect by default. Left at high depth on a root domain, a crawl pulls in marketing and legal pages that degrade retrieval. Scope the path and keep depth shallow.
• More sources is not more accuracy. Past a point, adding documents lowers precision because retrieval has more near-duplicates to confuse. Prune as deliberately as you add.
• Indexing and analysis cost credits. Ingestion and Studies runs draw on your Macha credit balance like everything else (credits are billed per AI action — roughly 0.5–9 by model, with the default GPT-5.4 Mini at 1). Big crawls and big studies cost real credits, so scope them. See the pricing page for current plans and credit allowances.
• Live sources inherit their source's mess. A connected Notion workspace full of half-finished drafts will feed the agent half-finished drafts. Connect the clean spaces, not the scratchpad.

A starter blueprint

If you're building a knowledge library from scratch, this is a sane day-one shape:

Scope each source to the agents that need it, start narrow, and expand only when a real ticket proves a gap.

FAQ

What's the difference between a knowledge source and a connector in Macha? A connector is the integration that lets an agent take actions (look up an order, update a ticket). A knowledge source is content an agent can read to answer questions. Some connectors — Google Workspace, Notion, Confluence, a Zendesk Help Center — also auto-create a live knowledge source when you connect them. See the docs for the full breakdown.

Does Macha chunk and embed my documents? Yes. Small files are injected directly into the agent's prompt; larger files are chunked, embedded, and searched on demand. You don't configure the embedding pipeline — you control what goes in and which agent can see it.

How do I keep knowledge from going stale? Use live connector sources (Google Docs, Notion, Confluence, your help center) for anything that changes — they read the latest content with no re-upload. Reserve uploads and crawls for stable, authoritative content, and re-index when it changes.

Should every agent see every source? No. Scope each agent's Data Sources to what it actually needs, and use Selected rather than All documents when an agent only needs part of a source. Narrower knowledge means more precise answers. Sub-agents each get their own scoped knowledge base for the same reason.

How do I find what my knowledge base is missing? Mine your tickets. Run a Study over recent tickets to surface the topics your sources don't answer cleanly, then add or fix those documents — and you can push the study results back in as a new source.

Get started

Designing knowledge sources is the highest-leverage hour you'll spend on an AI support agent — more than prompt-tuning, more than model choice. Start with one canonical document per fact, put volatile knowledge behind a live connector, scope each agent tightly, and let your tickets tell you what's missing.

Want to try it on your own content? Start a 7-day free trial, no credit card required, connect Zendesk, add your first sources, and watch your agent answer from knowledge you actually trust. The Macha docs have the full walkthrough.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.