System guide
Knowledge bases
Upload your own documents so an AI Agent answers from your organization's knowledge — create a knowledge base, add documents, and attach it to an AI Agent from AI Capabilities → Knowledge Bases.
A knowledge base is an organization-owned library of documents that AI agents can consult — product manuals, service terms, internal handbooks. Build one by uploading files. Instead of relying only on what the model already knows, an AI Agent retrieves the most relevant content from your dedicated knowledge base and grounds its reply in it. This page covers how to create a knowledge base, add and manage documents, read each document's processing status, and attach a knowledge base to an AI Agent.
The knowledge base list
Each row is one knowledge base. Columns:
| Column | What it shows |
|---|---|
| Name | The knowledge base name |
| Description | A short note, or a dash if left blank |
| Documents | How many documents the knowledge base holds |
| Chunks | Total number of indexed pieces across all ready documents |
| Status | Active — eligible for retrieval. Disabled — skipped during retrieval even if an AI Agent is attached. |
Use the Actions menu on each row to Edit or Delete the knowledge base. Click a row to open its detail page and manage documents.
Creating a knowledge base
Click New Knowledge Base and fill in the form. The chunking fields have sensible defaults, so for most cases you only need a name.
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Up to 100 characters |
| Description | No | Up to 500 characters; describes what the knowledge base contains |
| Chunk Size | Yes | Characters per chunk, 100–4000, default 800 (the FAQ/support sweet spot) |
| Chunk Overlap | Yes | 0–500 and at most half the chunk size, default 100; overlap keeps key sentences from being split across chunks |
| Active | Yes | On by default; an inactive knowledge base is skipped during retrieval |
Click Create to save. The knowledge base appears in the list right away, empty. Open the detail page to start adding documents.
Adding documents
Open a knowledge base, then click Add Document. There are two ways to add content — switch between them with the Paste text and Upload file tabs at the top of the dialog.
Paste text
- Title(required) — a name for the document, for example "Refund Policy".
- Content (required) — paste the document text into the box. A live character count helps you gauge the size.
Upload file
- Title (optional) — leave it blank to use the file name.
- File (required) — drag a file in or click to select one. Accepted formats are
.md,.markdown, and.txt, up to 20 MB.
Click Add Document to submit. The document is queued for indexing and appears in the list as Pending; it becomes Ready once indexing finishes.
Managing documents
The detail page header shows the knowledge base name, description, the chunking parameters, and the total chunk count. The document table lists every document with these columns:
- Title — the document name.
- Source —
filefor an uploaded file ormanualfor pasted text. - Status — the processing state (see the table below).
- Chunks — how many indexed pieces the document produced; shown only once it is Ready.
- Indexed At — when indexing finished; shown only once it is Ready.
Document processing status
| Status | Meaning |
|---|---|
| Pending | Submitted and waiting to be indexed |
| Indexing | Currently being processed |
| Ready | Finished and available for retrieval |
| Failed | Processing failed; click the status to see the error and retry |
Per-document actions
Use the actions menu on each document row:
- Re-index — re-processes the document. Its status returns to Pendingand it is indexed again with the knowledge base's current chunking parameters.
- Delete — removes the document and every chunk that came from it. This cannot be undone.
Re-indexing everything
The Re-index Allbutton at the top of the detail page re-processes every document that is not currently indexing, using the knowledge base's current chunking parameters. Existing chunks are cleared and the documents return to Pending while they index again in the background; any document that is already indexing is skipped. This is the button to use after you change the chunk size or overlap.
Editing a knowledge base
From the list, choose Edit on a row to update the name, description, chunking parameters, and the Active toggle. The embedding model is fixed when the knowledge base is created and cannot be changed afterward.
Deleting a knowledge base
Choose Deletefrom a row's actions menu. Deleting permanently removes the knowledge base along with all of its documents and chunks — this cannot be undone. Before you confirm, the dialog checks which AI Agents are attached to this knowledge base and shows one of two results:
- Safe to delete — no AI Agent is currently attached, so you can delete right away.
- Agents attached — the dialog lists the AI Agents that use this knowledge base and warns that they will lose retrieval from it on the next customer message. You must tick the acknowledgement checkbox before the Delete button becomes available.
Attaching a knowledge base to an AI Agent
A knowledge base does nothing on its own — you attach it to an AI Agent so the agent can retrieve from it. Open the AI Agent's Edit dialog and find the Knowledge Bases (RAG) section. There are two settings:
- Authorized Knowledge Bases — tick the active knowledge bases this AI Agent may use. Each option shows its chunk count. If your organization has no active knowledge bases yet, create one first from the Knowledge Bases page.
- Auto-inject Top-K — how many snippets to retrieve for every customer message before the AI replies (0–5). Setting it to 0 is tool-only mode: the AI decides for itself when to search the knowledge base. A higher value improves recall but uses more tokens.
Save the AI Agent. From the next customer message onward, it can ground its answers in the documents you provided.