Knowledge base

A knowledge base lets an agent answer from documents you upload - a price list, a policy, a product manual - rather than from what the model happens to know.

Uploading documents

Upload a document under Knowledge base, or through the API (POST /knowledge-base/documents/upload for a file, POST /knowledge-base/documents for text you send as JSON).

What can be uploaded:

PDF with a text layer. The text is read from the PDF; there is no OCR, so a scanned PDF with no text in it is refused, and scanned pages inside an otherwise text PDF contribute nothing.
Any UTF-8 text file - plain text, Markdown, CSV, JSON and the like.

Anything else, or a file with no readable text, is refused with 400 unsupported_document. A file over the upload limit (10 MB unless your operator has changed it) is refused with 413 file_too_large. If your plan limits the number or total size of documents, an upload past that limit is refused with 402 quota_exceeded.

The text is read during the upload itself. The document is then split into chunks and indexed in the background: it starts as processing and becomes usable once it is ready (or failed if indexing did not succeed). Chunks are 800 characters by default; the API accepts chunk_size (100-4000) and chunk_overlap (0-1000) if your documents need something else.

Attaching it to an agent

A knowledge base is not used until an agent is pointed at it. On the agent, choose a collection, individual documents, or both. An agent with nothing selected searches nothing - it never falls back to everything your organization has uploaded.

Over the API this is the agent's knowledge_base setting (on a prompt agent's config, or on a workflow conversation node's data):

{
  "knowledge_base": {
    "document_ids": [12, 15],
    "top_k": 3,
    "min_score": 0.3
  }
}

Field	Default	What it does
`document_ids`	none	The documents this agent may search, by their numeric `id` from the document list.
`top_k`	`3`	How many passages to retrieve per search.
`min_score`	`0.3`	The similarity floor, from 0 to 1. Passages less similar than this are dropped, so an unrelated question retrieves nothing. See How retrieval works.
`vector_store_id`	none	A collection's uuid. Its documents are searched in addition to `document_ids`.

Different agents can be given different documents, so a support agent and a sales agent do not have to share one pile.

Collections

A collection is a named group of documents, so an agent can be pointed at the whole group instead of a list of ids. Create one on the Knowledge base page; while it is selected there, anything you upload or add goes into it. In the agent builder, pick the collection in the knowledge base picker (a workflow node has its own collection field). An agent searches at most one collection, together with any documents picked one by one.

A document belongs to at most one collection. Removing it from the collection leaves it in the knowledge base, and deleting a collection keeps its documents.

The API calls collections vector stores (/vector-stores): upload into one with POST /vector-stores/{uuid}/documents/upload, take a document out with DELETE /vector-stores/{uuid}/documents/{id}, and point an agent at one with vector_store_id.

How retrieval works

In chat, every user message is used as a search: the passages most relevant to it are found and put in front of the model with the message.

On a call, the agent is given a knowledge-search function and is told to use it whenever the caller asks about something the documents might cover. The model decides when to search and what to search for.

Retrieval is semantic by default: passages are matched on meaning and kept only if they clear min_score. Meaning alone is weak at exact tokens - an order number, a product code, a surname. Set min_score to 0 and exact keyword matching runs alongside the semantic search, with the two result lists merged. The cost is the floor: at 0 nothing is filtered out, so the agent always gets the closest top_k passages even for a question the documents do not answer.

Say in the prompt what the documents cover, e.g. "Answer questions about pricing and delivery from the knowledge base. Never invent a price." This is the difference between an agent that looks things up and one that guesses.

To see what a query retrieves, call POST /knowledge-base/search with query, top_k, document_ids and min_score. Its defaults differ from an agent's: without document_ids it searches every document in your organization, and min_score defaults to 0, so keyword matching is on. Pass the same values your agent uses to see what the agent sees. Each hit names its source document and its chunk position (a chunk index, not a page number).

Billing

Indexing a document and every knowledge-base search embed text with a model, and that usage is billed to your balance, unless the embedding provider's key is one you supplied. The amounts are small; see Pricing.

What it does not do

A knowledge base answers questions. It does not take actions or read live data - a stock level or an order status has to come from a tool.