Giving Your AI Agent a Knowledge Base: Uploads, Website Crawl & Live Sources

In Macha, a knowledge base is assembled from data sources: documents you upload, websites you crawl, and live documents you connect from Google Workspace, Notion, or Confluence. This is the pillar guide to all three. We'll cover what each source type is for, the three different ways an agent actually reads a source (this is the part most guides skip), the real limits you'll hit, and how to decide which kind of source a given piece of content belongs in.

Macha is an AI agent layer that sits on top of the helpdesk you already run — Zendesk, Freshdesk, Gorgias, or Front. Data sources are how you hand those agents the knowledge to resolve tickets accurately instead of confidently wrong.

Connectors take actions; data sources supply knowledge

It's worth drawing one line up front, because mixing these up is the most common setup mistake. Connectors let an agent do things in external tools — look up a Shopify order, post to Slack, update a Zendesk ticket. Data sources let an agent reference information to answer better. Same agent, two different jobs: one acts, one knows.

This guide is about the second one. (For the first, see Macha's integrations.)

On the Sources page, the top of the screen gives you three ways to add knowledge — Upload documents, Add a website, and Add a web page — and below that sits your list of everything already connected, each row tagged with a status badge.

Live vs Ready: the status badge that tells you everything

Every source carries one of two status badges, and the distinction maps directly onto how fresh the agent's knowledge is:

• Live — the source pulls content in real time from a connected app (Google Workspace, Confluence, Notion). The agent always reads the current version.
• Ready — the source has been indexed and is good to go (uploaded files, your Zendesk Help Center, crawled websites). The agent searches a snapshot that was captured at index time.

That single word — Live or Ready — is the answer to "will my agent see edits I made this morning?" Live sources, yes. Ready sources, only after a re-index. Keep it in mind for the rest of this guide.

Option 1: Upload documents (static files)

If you have static content — a returns policy, a product manual, an internal escalation guide — the simplest path is to upload it straight into Macha.

You can add up to 10 files at a time, each up to 20 MB. Indexing starts immediately — Macha reads the content, breaks it into chunks, and makes it searchable, usually within a few seconds to a couple of minutes. Supported formats:

The one thing to internalise: uploaded files don't auto-refresh. If you edit the original document, Macha keeps serving the old version until you delete it and re-upload. For anything that changes weekly, an upload is the wrong tool — use a live connector source instead (Option 3 below).

Option 2: Crawl a website (or grab one page)

Most teams already have their best support content published somewhere — a help center, a docs site, product pages. Rather than copy it into files, point Macha at the URL. There are two modes, and you pick based on how much of the site you need.

Add Website crawls the whole site. Macha follows the links it finds, discovers pages, and indexes them — you'll watch pages populate in real time. Use this for an entire documentation site or help center. There's a system limit of 200 pages (Macha indexes the first 200 it finds), and a crawl typically finishes in a few minutes, landing on a Ready status when done. After a fix in April 2026, the crawler handles pages up to 2 MB each (up from 512 KB), so content-heavy pages like e-commerce product listings ingest cleanly.

Add Web Page is the surgical version: one specific URL — a single blog post, one FAQ, a particular product page — indexed and ready, no crawling.

Two caveats worth flagging. First, like uploads, crawled websites are a snapshot — Macha doesn't watch the site for changes. When you update content, hit the Resync button on the source to pull the latest version; a resync also cleans out pages that have been removed. Second, crawlers can only reach publicly accessible pages — anything behind a login won't be indexed, which is consistent guidance across the industry (Zendesk documents the same constraint for its web crawler).

Option 3: Connect live sources (Google Docs, Notion, Confluence)

This is the option that solves the "snapshot goes stale" problem. Connect a live source and the agent reads the content directly from the service every time it needs it — never a copy from last week.

• Google Docs / Sheets — the agent reads live with google_read_doc (and google_read_sheet for sheets). Edit the doc, and the agent sees the change on its next read.
• Notion — the agent reads pages live with notion_get_page, always the current content.
• Confluence — connecting Confluence automatically creates a data source, the same way Google and Notion do.

There's a quiet bit of automation here that saves a lot of fumbling. When you add a Google or Notion source to an agent, Macha auto-links the required read tools and the connector instance — you don't manually assign anything. Google sources auto-add google_read_doc, google_read_sheet, and google_list_drive_files; Notion sources auto-add notion_search and notion_get_page. These auto-added tools are locked while the source is attached — to remove them, remove the data source first. (More on connecting these services in Macha's integrations.)

The part most guides skip: how an agent actually reads a source

Here's where Macha's knowledge base differs from "upload a PDF and pray." The type of source determines how the agent accesses it, and there are three distinct modes. Knowing them is the difference between an agent that nails the answer and one that misses data sitting right in front of it.

Mode 1 — Injected (always in context)

Small CSV and XLSX files of 2,000 rows or fewer are injected directly into the agent's system prompt. The entire file is available at all times — no searching, no tool calls. This is the fastest, most reliable way for an agent to work with structured data: it can reference any row or column immediately. The trade-off is context-window space, which is why it's reserved for small spreadsheets.

Mode 2 — Searchable (chunked and embedded)

Large files, PDFs, DOCX documents, and all website content are chunked, embedded as vectors, and searched on demand. When the agent needs something, it:

1. Calls search_knowledge with a query to find the most relevant chunks.
2. Reviews the results to spot the right sections.
3. Calls get_document to pull the full content of those chunks.

This two-step retrieval is what lets a single agent work over a very large knowledge base efficiently — it only loads the parts it needs. For spreadsheets that exceed the injection threshold, chunking is row-aware: roughly 75 rows per chunk with the header row preserved in every chunk, so the agent always knows what each column means.

Mode 3 — Live connector (read on every request)

Google Docs and Notion pages are read live via their respective tools every time the agent references them — always the latest version.

The useful insight: you can mix all three on the same agent. Inject a small pricing spreadsheet, add a big policy PDF as searchable knowledge, and connect a live Google Doc with your evolving FAQ — one agent, three access modes, each chosen to fit the content.

Knowledge source vs. tool: a decision in one question

When you're staring at a piece of content unsure how to add it, the decision reduces to a single question: is this content static or does it change?

Both are data sources. The only difference is whether the agent gets a frozen copy or a live read. Pick by cadence, not by format.

Scope filtering: not every agent needs every document

A source can hold a lot of documents, and not every agent should see all of them. Each source row on an agent carries an inline toggle, added in the April 2026 scope-toggle update:

• All documents — the agent can access everything in the source, and automatically gains access to new documents as they're added.
• Selected — the agent only sees the specific documents you hand-pick. Choosing "Selected" expands a document picker.

Scope filtering works across all source types — uploads, websites, Google Docs, and Notion — so a billing agent can be scoped to billing docs while a shipping agent reads only logistics content, all drawing from the same underlying sources.

Watch-outs: when knowledge sources are the wrong answer

No tool is free of trade-offs. A few honest ones:

• Uploads and crawls go stale silently. They're snapshots. If your return policy changes and you forget to re-upload or Resync, the agent will keep quoting the old one — confidently. For volatile content, live sources exist precisely so you never have to remember.
• Public-only crawling. Anything gated behind a login is invisible to the crawler. Put that content in an uploaded file or a connected Google/Notion doc instead.
• More sources isn't always better. Industry guidance — including Zendesk's own — is to keep the number of knowledge sources reasonable; piling on too many can dilute retrieval accuracy and add latency. Curate; don't dump.
• Knowledge isn't action. A data source lets an agent tell a customer the refund policy. To actually process the refund, the agent needs a connector and a tool. Knowledge and tools are complements, not substitutes.
• Plan limits on source count. The number of knowledge sources is plan-limited (Starter, Professional, and Enterprise allow progressively more — see the pricing page for current limits). It's a count of sources, not a per-document cap.

For teams running on Zendesk specifically, the same knowledge a Macha agent searches can include your existing Help Center — see Macha on Zendesk for how the layer fits on top of your current setup. And once your agents are answering, Studies can analyse which questions they're actually getting, so you know what knowledge to add next.

FAQ

What file types can I upload as a knowledge source? PDF, CSV, XLSX, DOCX, and TXT — up to 10 files at a time, each up to 20 MB. Indexing starts immediately and usually finishes within a couple of minutes.

Does Macha keep my website knowledge up to date automatically? No. Crawled websites and uploaded files are snapshots. Macha doesn't monitor your site for changes — hit Resync on the source to pull the latest version (which also removes deleted pages). For content that changes often, connect a live source (Google Docs, Notion, Confluence) instead, which the agent reads in real time.

How many pages can the website crawler index? Up to 200 pages per site — Macha indexes the first 200 it discovers. Each page can be up to 2 MB. For a single page, use Add Web Page instead of crawling.

What's the difference between a Live and a Ready source? Live sources read content in real time from a connected app, so the agent always sees the current version. Ready sources (uploads, websites, Help Center) are indexed snapshots the agent searches.

Do I have to manually add tools for Google or Notion sources? No. Adding a Google or Notion data source auto-links the required read tools and the connector instance. Those tools stay locked while the source is attached; remove the source to remove them.

How does the agent decide whether to search or inject a document? It's automatic and based on size. Small spreadsheets (≤2,000 rows) are injected into context; larger files, PDFs, DOCX, and websites are chunked, embedded, and searched with search_knowledge and get_document. You can mix all modes on one agent.

Get started

Pick one high-volume question your team answers daily, find where the answer lives, and add it as the right kind of source — upload the file, crawl the help center, or connect the live doc. Start a 7-day free trial, no credit card required, open the Sources page, and give your first agent something real to read. The full walkthrough lives in the data sources docs.

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