Skip to main content
A corpus is a searchable collection of your documents. Link one to an agent and the agent gains a search tool it can call during a conversation — grounding its answers in your material rather than in its prompt. This is how you give an agent knowledge. An older knowledgeBases field still exists on the agent payload for legacy integrations, but it is deprecated — use corpora.
Corpora are created and managed in the dashboard, under Corpora. There is no API-key endpoint for creating one — the management routes authenticate with your dashboard session. What is automatic is the search: once a corpus is linked, the agent queries it on its own during calls.

​
What you can put in one

Three kinds of source:

File

Upload a document. Up to 4 MB each.

Text

Paste content directly. Up to 4 MB.

URL

Give a page address and it is fetched and indexed.

​
Supported file types

PowerPoint and legacy Office formats are not supported. Export .pptx / .ppt slides to PDF, save .doc as .docx or PDF, and .xls as .xlsx or .csv. Uploading one of these returns an explanatory error rather than failing silently.

​
Indexing

Adding a source does not make it searchable immediately. Each one moves through: URL sources are fetched in the background, so they sit in PENDING briefly before processing begins. Large PDFs take longest.
Test only once every source shows PROCESSED. An agent asked about content that is still indexing will correctly say it cannot find it — which looks like a broken agent but is the system telling the truth.

​
Linking a corpus to an agent

Include corpus IDs in the agent payload, or use the agent page in the dashboard:
The agent automatically gains a tool named search_<corpus_name> — you do not create or configure it. Its description tells the model to reach for it whenever a caller asks something that corpus might answer.

​
Covering the pause

Retrieval takes a moment, and silence on a phone call feels far longer than it is. kbSearchAnnouncement is spoken verbatim immediately before the search:
Write it in whatever language your agent speaks — it is not translated. Maximum 300 characters, though one short sentence is the right length.

​
How search behaves during a call

The agent sends the caller’s question, and passages come back ranked. By default it retrieves 8 passages; the model may request up to 12. That default is deliberately generous. On real PDFs the passage containing the actual answer — a row in a pricing table, say — often ranks tenth or lower, because generic introductory text matches the query more strongly. Returning more passages means the answer is present in context for the model to find.

​
Writing documents that retrieve well

Retrieval returns passages, not whole files. What survives being lifted out of context:
  • Put the answer next to the question. A heading phrased as a question with the answer directly beneath is close to ideal.
  • Keep related facts together. A price three paragraphs away from the product name may come back without it.
  • Prefer several small documents over one large one — chunk boundaries fall in kinder places.
  • Avoid cross-references. “See section 4.2” is meaningless once a passage is read on its own.
Tables in PDFs are the most common disappointment. A table that reads clearly to a human frequently flattens into unusable text when extracted. If specific numbers matter, state them in a sentence as well as showing the table.

​
Corpora and workspaces

A corpus belongs to a workspace and can be linked to any number of agents in it. Update the documents once and every agent using it answers from the new version — there is no per-agent copy to keep in sync.

Attach one to an agent

The corpora field on the agent payload.

Tools

Let the agent act, not just recall.