> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.jambonz.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.jambonz.org/_mcp/server.

# Knowledge

A knowledge base is a set of documents your agents can search while they talk: product sheets, policies, FAQ pages.
During a call the agent looks up what it needs and answers from the passages it finds.

Knowledge bases belong to the account (**Knowledge** in the navigation), and several agents can share one. The
**Knowledge** section of an agent says which ones that agent uses.

## Which agents can use it

| Kind                        | Knowledge                                                  |
| --------------------------- | ---------------------------------------------------------- |
| **Cascaded voice pipeline** | search, and pinned facts                                   |
| **Realtime voice API**      | search                                                     |
| **Custom harness**          | not available: your harness does its own retrieval         |
| **Connected agent**         | not available: knowledge lives on the agent's own platform |

## Creating a knowledge base

Search uses an embedding model on your own key. Before the first knowledge base, add one with **Embedding keys** on
the Knowledge page. Studio supports embedding keys from OpenAI, Azure OpenAI, Cohere, Voyage and Google.

**New knowledge base** asks for:

* **Name** and an optional **Description**
* **Language**: the language of the documents, used for keyword matching
* **Embedding key** and **Model**

The embedding key and model cannot be changed after the knowledge base is created.

## Adding documents

On the knowledge base's page, under **Documents**:

* **Upload files**: PDF, DOCX, HTML, Markdown or plain text, up to 20 MB each. Drop them on the page or use
  **Choose files**.
* **Import from URL**: a public **Page URL**. Tick **Also import linked pages on the same site** and set **Maximum
  pages** (1 to 50) to import more than one page. Pages behind a sign-in are not imported.

Each document is split into passages and indexed. Its status goes from **Queued** to **Parsing** to **Indexed**, or
**Failed** with the reason. From a document's menu you can **View chunks**, **Reindex** or delete it.

## Trying a search

**Try a search**, on the knowledge base's page, runs a question the way a caller would ask it and shows the passages
the agent would receive, ranked by meaning and keywords together. Use it to check that your documents answer the
questions callers ask.

## Attaching a knowledge base to an agent

In the agent's Knowledge section, **Attach knowledge base** adds one; **Remove** takes it off. An agent can have up
to 10. Only Owners and Admins can change the knowledge attached to an agent.

With at least one knowledge base attached, the agent gets a `search_knowledge_base` tool. The model calls it with a
short question when it needs facts, and gets back quoted passages from all the attached knowledge bases. With none
attached, the agent answers from its prompt only.

The fold under the list tunes the search:

| Setting                | What it does                                                                                                              | Default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Results per search** | the most passages returned for one search, 1 to 5                                                                         | 3       |
| **Minimum relevance**  | passages scoring below this are left out (applies to meaning-based matches before they are combined with keyword matches) | 0.30    |
| **Tool description**   | tells the model when to search. Empty uses Studio's own description, which names the attached knowledge bases             | empty   |

## Pinned facts

Some facts every caller may ask about, such as opening hours or an address, are better known than searched for. Put
them in **Always-known facts** on the knowledge base's page (up to 4,000 characters).

In the agent's Knowledge section, turn on **Pin facts** for that knowledge base to add its facts to the agent's
prompt, so the model always has them. Pinned facts are added as quoted reference material, with a note telling the
model not to follow instructions inside them. **Pin facts** appears only on Cascaded voice pipeline agents, the only
kind whose prompt Studio adds them to.

When you save new facts, drafts use them at once; a live agent uses them after it is published again.

If the pinned facts make the agent too large to send to jambonz, Studio leaves them out and shows **Over the call
budget** on that knowledge base. Shorten the facts or turn the pin off.

## What blocks publishing

* a knowledge base that was deleted, or is being deleted, while still attached

Remove it from the agent, or attach another one.