References

References are the material your agent draws on to answer questions: FAQs, policies, product docs. They let facts live outside the 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

The user asks something.
The model calls search_knowledge with a natural-language query.
Matching snippets come back as a tool message, each with its source file.
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:

integrations.yml

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 }

agent.yml

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

Getting Started

Building Skills

Progressive Control

Orchestration

More

How it works

Both locations feed one index

What happens in a turn

Choosing the embedding model

What references are for

​How it works

​Both locations feed one index

​What happens in a turn

​Choosing the embedding model

​What references are for

How it works

Both locations feed one index

What happens in a turn

Choosing the embedding model

What references are for