> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Base for AI Agents

> Upload documents to a knowledge base, attach it to your agents, and let them answer caller questions from your own content.

A knowledge base lets your agents answer questions using your own documents — product manuals, FAQs, policy guides, pricing sheets, and more. Instead of trying to pack all of this information into the system prompt, you upload files to a knowledge base, attach it to your agent, and the agent searches it during calls whenever a caller asks something your files cover.

## How it works

When you upload a document, Verbeo splits it into short passages and indexes each one by its meaning, so a search finds the right passage even when the caller words the question differently from your document. During a call, the agent looks up the passages that best match the caller's question and answers from them.

## Creating a knowledge base

**1. Open Knowledge Base**

Navigate to **Knowledge Base** in the left sidebar of the Verbeo dashboard.

**2. Create a knowledge base**

Click **New knowledge base** and give it a descriptive name that reflects its contents — for example, "Product Catalog" or "Support FAQs". This helps you identify it when attaching it to agents.

**3. Upload documents**

Open the knowledge base and click **Upload files**. Each file shows its upload progress — an upload that loses its connection carries on from where it stopped — then Verbeo reads it in the background, splits it into passages and makes it searchable. A large file can take several minutes; its row shows how far it has got.

**4. Check the description**

Once your documents are ready, Verbeo writes a short description of what the knowledge base covers. This description tells the agent when to search this knowledge base during a call. You can edit it, or click **Regenerate** to write it again from your files.

> [!NOTE]
>
> The description is written from the first 5,000 characters of each file. If your files are longer, check that the description names everything callers may ask about, and edit it if needed. Once you edit it, Verbeo no longer rewrites it on its own: after you add or remove files, it asks whether to update the description from your files (**Update**) or keep yours (**Keep mine**). **Regenerate** and **Update** need at least one ready file.

### File requirements

| | |
| - | - |
| File types | PDF (`.pdf`), Word (`.docx`, `.doc`), OpenDocument (`.odt`), Rich Text (`.rtf`), EPUB (`.epub`), plain text (`.txt`), Markdown (`.md`), HTML (`.html`), XML (`.xml`), JSON (`.json`), YAML (`.yaml`) |
| File size | Free: up to 5 MB per file. Pro: up to 25 MB per file; HTML, XML and YAML files up to 8 MB |
| Text | Free: about 300 pages of text per file (1,000 passages). Pro: about 3,000 pages (10,000 passages) |
| Text files | Saved as UTF-8 (or UTF-16 with a byte-order mark) |

A passage is a piece of about a paragraph; a page of text is about three of them. A table of four rows or more is a passage per row, under the table's header, so each row can be found on its own; a long table uses more passages. PDFs must have selectable text: a scanned PDF is only pictures of pages, so it has nothing to read. The same file can only be added once to a knowledge base; a copy of a file that failed can be uploaded again, for example under the name its error suggests.

> [!TIP]
>
> Clean, well-organised documents — clear headings, one topic per paragraph, tables with header rows — give the agent the most accurate answers. See [Write a knowledge base that answers well](/guides/knowledge-base-writing).

### Document processing status

After you upload a file, it moves through the following states before it becomes searchable:

```text theme={null}
uploading → processing → ready
                ↓
              error
```

If a document reaches `error` status, its row says why and what to do — for example a password-protected file, a scanned PDF, or more text than a file can hold. Fix the file and upload it again, or click **Retry** when the error was temporary. Tick several files to retry or delete them together.

### Working with your files

* **Preview** shows what your agent reads from a file: its passages, as plain text. In a newly uploaded file, each passage starts with the file's name and the headings it sits under, so your agent knows what it is about; upload an older file again to get them.
* **Download** gives you back the file you uploaded.
* **Replace** uploads a new version of a file. Your agents keep using the old one until the new one is ready, then switch to it at once; if the new one fails, the old one stays.

Owners, admins and developers can preview and download files; owners and admins can replace and delete them.

## Attaching a knowledge base to an agent

Once your knowledge base is ready, open the agent in the dashboard, expand its **Knowledge Base** section, and add the knowledge bases the agent may search.

If you manage agents through the API, include the knowledge base IDs in the `kbStoreIds` array of the agent's configuration:

```json theme={null}
{
  "agent_name": "Product Support Agent",
  "config": {
    "systemPrompt": "You are a product support agent. Use the knowledge base to answer questions about our products accurately.",
    "kbStoreIds": ["your-knowledge-base-uuid-here"],
    "voice": {
      "voiceId": "Zephyr"
    }
  }
}
```

You can attach multiple knowledge bases to the same agent by adding more IDs to the array. Each one must belong to your workspace.

### Match strictness

Each agent decides how close a passage must be to the caller's question before it uses it. In the agent's **Knowledge Base** section, raise **Match strictness** to use only close matches, or lower it to use looser matches too. Through the API it is `kbMinSimilarity` in the agent's configuration: a number from `0.40` to `0.80` in steps of `0.05`, `0.55` by default.

### Results per search

Each agent also decides how many matches one search gives it. In the agent's **Knowledge Base** section, raise **Results per search** when an answer is sometimes not among the closest matches, or lower it to give the agent only the closest ones. Through the API it is `kbTopK` in the agent's configuration: a whole number from `1` to `5`, `3` by default.

## How agents use the knowledge base

When a caller asks a question during a call, the agent decides whether your documents may answer it and, if so, searches its knowledge bases itself, then answers from the passages it finds. You do not need to write any special logic or prompting to trigger the search.

You do not need to list every possible question in the system prompt. The knowledge base handles content-specific questions; the system prompt handles persona, tone, and business rules.

### Automatic search

With **Automatic search** switched on in the agent's **Knowledge Base** section, Verbeo also searches the agent's knowledge bases while the caller is still speaking and gives the agent the best matches before it answers, so an answer does not wait on the agent deciding to search. Calls that use it add \$0.01 a minute. The switch needs a knowledge base with at least one ready file. Through the API it is `kbAutoSearch` in the agent's configuration: `true` or `false`, off by default.

## Plan limits

| | Free | Pro |
| - | - | - |
| Knowledge bases | 1 | 25 |
| File size | 5 MB | 25 MB (HTML, XML and YAML: 8 MB) |
| Text per file | About 300 pages (1,000 passages) | About 3,000 pages (10,000 passages) |
| Files per knowledge base | 3 | 25 |
| Passages per knowledge base | 1,000 | 20,000 |
| Passages across all knowledge bases | — | 100,000 |
| Storage for your files | 50 MB | 2 GB |
| Passages processed each month | 1,000 | 50,000 |

A file that failed does not count toward the files in a knowledge base, but it still uses storage until you delete it. Processing a file again (a retry) counts its passages toward the month again. The month starts on the 1st, in UTC.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.