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

# References

> Reference material the agent answers questions from.

References are the material your agent draws on to answer questions: FAQs,
policies, product docs. They let facts live outside the
[instructions](https://mantle.rasa.com/concepts/instructions.md) while staying available to the agent.

## How it works

Drop markdown files in a `references/` folder. At `rasa train`, every `.md` file
is split into overlapping character chunks, then those chunks are embedded into
a local vector index that ships inside the model. At runtime the agent gets a
built-in `search_knowledge` tool and calls it when a question needs looking up.
Retrieved hits are the matching sections, not the whole file.

```
my-agent/
├── references/                  # agent-wide
│   ├── account_security.md
│   └── card_shipping_and_fees.md
└── skills/
    └── billing/
        └── references/
            └── fees.md          # also indexed
```

You do not write a retrieval tool. If a `references/` folder exists at train
time, `search_knowledge` appears. Optional embedder and chunk-size settings
live under `knowledge_answering` in [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#knowledge_answering).

Markdown is the indexed format: every `**/*.md` file under a `references/`
folder, with empty and whitespace-only files skipped.

## Both locations feed one index

Files at the agent root and files under `skills/<id>/references/` are indexed
together into a **single** searchable store, and every `search_knowledge` call
covers all of it whatever skill is active. The two locations are there to keep
your files organised alongside the skill they belong to.

Write each document so it stands on its own, then. A retrieved chunk arrives
without the folder it came from, so a fees document that opens with "Billing
fees for postpaid plans" is usable in a way that one opening with "The
following fees apply" is not.

A large FAQ can stay in one markdown file. You do not need to split it by hand
before training: index-time chunking does that. Headings and short sections
still help retrieval, because each stored vector is one chunk.

## What happens in a turn

1. The user asks something.
2. The model calls `search_knowledge` with a natural-language query.
3. Matching sections come back as a tool message, each with its source file.
4. The model answers from those sections, or calls `search_knowledge` again
   with a refined query.

Two behaviours are worth knowing because they shape how the agent feels:

* **After a search, the skill's own tools and `listen` are withheld** for the
  rest of the turn. `activate`, `search_knowledge`, and `cannot_help` remain,
  plus `resolve_tool_confirmation` when a confirmation is pending. `enter` is
  not added. A grounded answer neither re-drives the active skill nor ends
  before presenting the retrieved information. When the user's message also
  continues the task, the model can answer and call `activate` with the
  running skill to resume it in the same turn. Otherwise the skill's tools and
  `listen` come back on the next turn.
* **`cannot_help` is withheld until a search has run.** When a knowledge base
  exists, the agent cannot decline a request before retrieval has had a chance
  to answer it.

## Choosing the embedding model

By default the index uses the built-in OpenAI embeddings. To choose another,
declare a model group and name it:

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}
  - id: reference_embeddings
    models:
      - provider: openai
        model: text-embedding-3-large

channels:
  rest: { enabled: true }
  inspector: { enabled: true }
```

```yaml agent.yml theme={null}
agent:
  persona: You are Telco support.

orchestrator:
  model_group: main_model

knowledge_answering:
  embeddings: reference_embeddings
```

The index is built at `rasa train` and loaded at serve time with the same
embedder, so keep the named model group in `integrations.yml` for as long as the
trained model is in use. Renaming or removing it means retraining.

## How files are split

Each markdown file is split with recursive character chunking before it is
embedded. Size and overlap are measured in **characters**, not embedding tokens.

Omit `chunking` to use the defaults (`chunk_size: 1000`, `chunk_overlap: 20`).
Override them when a document's sections are much shorter or longer than that:

```yaml agent.yml theme={null}
knowledge_answering:
  embeddings: reference_embeddings
  top_k: 4
  chunking:
    chunk_size: 1000
    chunk_overlap: 20
```

`top_k` is how many chunks a search of the local index returns. Remote stores
are unchanged. Omit it to keep four. `rasa train` rebuilds the index from the
files under `references/`. `top_k` is not stored in that index; the trained
model reads it when it loads. Changing `top_k` needs another train so the new
value is packaged with the model.

Keep `chunk_size` well under the embedder's maximum input. Azure OpenAI
embeddings and OpenAI `text-embedding-3-small` / `text-embedding-3-large` reject
inputs over **8192 tokens**. A 1000-character default stays under that; a very
large `chunk_size` can still fail train.

Changing `chunking` has no effect until you run `rasa train` again. Field names,
defaults, and validation are in [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#knowledge_answering).

## What references are for

References answer *questions*. A [tool](https://mantle.rasa.com/concepts/tools.md) performs *tasks*. If
the customer needs something from a live system, such as a balance or an order
status, that is a tool call, and the reference index is for the policies and
explanations around it.


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