> ## Documentation Index
> Fetch the complete documentation index at: https://maestro.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](/docs/maestro/concepts/instructions) while staying available to the agent.

## How it works

Drop markdown files in a `references/` folder. At `rasa train`, every `.md` file
is 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.

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

No configuration, no tools to write, no wiring in `integrations.yml`. If a
`references/` folder exists, the tool appears.

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.

## What happens in a turn

1. The user asks something.
2. The model calls `search_knowledge` with a natural-language query.
3. Matching snippets come back as a tool message, each with its source file.
4. The model answers from those snippets, 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 are withheld** for the rest of the
  turn. `activate`, `search_knowledge`, and `cannot_help` remain, plus
  `resolve_tool_confirmation` when a confirmation is pending, so a grounded
  answer doesn't accidentally re-drive the active skill. The skill's tools 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}
llm:
  provider: openai
  model: gpt-5.1
  api_key_env: OPENAI_API_KEY

model_groups:
  - 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.

references:
  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.

## What references are for

References answer *questions*. A [tool](/docs/maestro/concepts/tools) 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.