Knowledge bases
Document formats, the 20 MB limit, ingestion states, knowledge_search, citations.
A knowledge base (KB) is a set of documents ingested so an agent can
search them semantically when it answers. Attach a KB to an agent
(knowledge_base_ids, see Agents) and that agent
automatically gets the knowledge_search tool — no flag to flip.
Create a knowledge base and upload a document
In the console, open Knowledge bases and click New knowledge base. Give it a Name (unique in your organization), a Slug, and an optional Description, then click Create knowledge base.
Open the knowledge base and click Upload documents. You can pick several files at once; each one is queued and ingested on its own.
Attach the knowledge base to an agent (Knowledge bases field on the agent, see Agents).
Accepted formats and limits
| Format | Extension |
|---|---|
.pdf | |
| Word (.docx) | .docx |
| Plain text | .txt |
| Markdown | .md |
Each file is capped at 20 MB. A file's content is checked against its
declared format (not just its name) — a .pdf that isn't really a PDF is
rejected.
Ingestion states
After upload, a document moves through:
- pending — waiting to be processed (the console shows Queued for processing).
- processing — being split into chunks and embedded.
- completed — ready for
knowledge_searchto find. - failed — processing failed; check the
errorfield for why.
Only completed documents are ever included in search results — a
document still processing, or one that failed, never contributes a
half-finished answer.
Your organization processes up to 2 documents at a time (a limit shared with other background work); the rest wait as pending and start as slots free up. Chat is scheduled ahead of document processing, so a large upload doesn't hold up conversations.
A document's row menu has Retry (for a failed document) and
Re-ingest (for a completed one). Both re-process it from the
original file — nothing to re-upload — and the list updates on its own as
it moves through Queued for processing, Processing, and back to
Completed or Failed. While a document is reprocessing, search skips it
until it finishes.
A document is split into fixed-size chunks with a small overlap between
neighbors so a sentence is never cut at a chunk boundary — this is why
knowledge_search returns "excerpts" rather than a whole document.
What knowledge_search returns
When the model calls knowledge_search, it gets back up to 5 of the most
relevant excerpts by default (the model can ask for up to 20 via a
top_k parameter). Each excerpt is numbered for the model to cite in its
answer, and every cited answer carries:
- The source document's name.
- The excerpt's position (chunk) within the document.
- A relevance score (0–1, higher is a closer match).
If nothing relevant is found, the model is told to answer from what it already knows and to say plainly that the documents didn't cover the question, instead of making something up.
One agent, several knowledge bases
An agent can be attached to more than one KB at once; by default
knowledge_search searches all of them, or the model can name a specific
kb_id to narrow the search.
A note on the embedding model
Every knowledge base is indexed with one fixed embedding model for your
whole deployment — you don't choose an embedding model per KB. If a
deployment's embedding model ever changes, a KB indexed under the old one
needs to be re-ingested before search over it is meaningful again; until
then, knowledge_search reports plainly that it can't compare instead of
returning nonsense results.