Resources

Knowledge base

Give the agent facts to draw on, so it looks things up instead of inventing them.

The knowledge base is the source material the agent reads to answer questions the prompt alone cannot cover: your pricing, your policies, your FAQ, your product details.

You add sources, the platform splits and indexes them, and the agent retrieves the relevant pieces when a caller asks. It is one of the agent's shared capabilities, so the same knowledge serves voice and text.

When to use one

Keep persona and rules in the prompt: how the agent behaves, the order it does things, the tone it takes. Keep facts in the knowledge base. Use a source when the information is:

  • Too long for the prompt. A 40-line refund policy or a full price list bloats it, and the agent reads it on every turn whether the caller asked or not.
  • Likely to change. Prices, opening hours, plan tiers, eligibility rules. A price change is then one edit to one source, not a prompt rewrite.
  • Reference material the caller asks about by name. Product specs, a FAQ, terms and conditions.

Each agent has its own sources, and they belong to its draft: a change reaches callers when you publish. The workspace Knowledge base page holds shared sources too, and once you publish them there, every agent in the workspace can answer from them. Within one agent, the voice and text surfaces read the same knowledge.

Three kinds of source

You add knowledge from the Knowledge base section of the agent editor.

  • Upload a file. PDF, Word (.docx), plain text (.txt), Markdown (.md) and CSV (.csv), up to 10MB each.
  • Website: one web page, or a whole site of up to 100 pages on the same host, kept as one source. The platform fetches the pages and reads their content. Pages behind a login, or that render entirely in the browser, may come back empty, and the source is marked failed with a reason.
  • Text pasted directly, with an optional name. A snippet or a whole article.

You never edit the indexed passages by hand. You add a source, re-fetch a website source, or edit the text of a pasted one.

How ingestion works

Every source, whatever its type, goes through the same three steps.

  1. Extract. The raw text is pulled out of the file, the web page, or the pasted content.
  2. Chunk. The text is split into overlapping pieces of up to roughly 500 tokens each, broken on paragraph and sentence boundaries so a chunk reads as a coherent passage. The overlap keeps context from spilling across a boundary.
  3. Embed. Each chunk is indexed by meaning rather than by keyword. Embedding runs onshore in Australia, and the stored vectors stay onshore.

A source moves through pending, extracting, embedding, then ready, or failed with an error message in the detail pane. A ready source is searchable and a failed one is not.

Ingestion runs a paid embedding step, metered to your workspace by token count. The add dialog says so before you confirm. See Billing.

How the agent retrieves it

The knowledge base does nothing on its own. The agent reaches it through the Search knowledge base builtin tool, calling it with a short search query when a caller asks something the prompt does not answer.

The platform embeds the query the same way it embedded the chunks, finds the closest matches by meaning, and returns the most relevant passages for the model to answer from.

The tool must be on the agent

Adding your first source attaches the tool to the draft automatically. If you removed it, add it back from the Tools section.

Retrieval is by relevance

The agent gets back a small set of the closest-matching passages, not the whole knowledge base. Only passages above a relevance threshold come back, so a query with no good match returns nothing rather than a weak guess.

When the search finds nothing relevant, the tool tells the model to say it does not have that information and offer to take a message or transfer to a human.

This is deliberate: the agent looks it up, and when it is not there it admits the gap rather than inventing an answer.

Pairing it with the prompt and tools

The prompt sets the rule, the tool description sets the trigger, and the knowledge base supplies the facts.

In the prompt

Tell the agent to look things up in its prompt.

For anything about pricing, plans, or policy, use the Search knowledge base
tool before answering. If it returns nothing, say you do not have that detail
and offer to take a message.

In the tool description

Tell it when to search. A good description means the agent reaches for the knowledge base at the right moments. See Tools.

Use this when the caller asks about plans, pricing, refunds, or eligibility.

Managing sources

The Knowledge section lists every source down one side and the selected source's detail on the other. From the detail pane you can:

  • Preview the indexed content as the chunks the agent will actually search.
  • Re-fetch a website source to pull the page again and re-index it, which is also how you retry a source that failed.
  • Edit a pasted text source.
  • Delete a source. This removes its indexed content from the draft too, and callers stop getting it once you publish.

Because the agent answers from what is indexed, a stale source means a stale answer.

Scheduling a URL re-crawl

A website source goes stale on its own when the page behind it changes. Set its Refresh to Daily or Weekly in the source's detail pane, and the platform re-fetches and re-indexes it regularly. The edit_kb_source_schedule MCP tool sets any other schedule, such as every day at 3am, in the timezone you choose.

The schedule is set per source, needs a plan that includes scheduled knowledge refresh, and fires on the platform's own clock without anyone clicking re-fetch. It refreshes the source the published version uses.

Auto-sync is for website sources only. Text and uploaded files have no remote to re-fetch, so there is nothing to schedule.

Each scheduled sync is a real re-ingest: it re-fetches and re-embeds the page, and is metered to your workspace the same way a manual add is, not a free poll. It is a time-based pull only, not a webhook push.

Writing a good source

Keep each source focused and well-written. Clear headings and short paragraphs chunk cleanly and retrieve better than a wall of text or a scanned document.

On this page