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

# integrations.yml

> Model groups, input channels, optional MCP servers, tracing, metrics, and the A2A server.

`integrations.yml` is required at the project root. It defines named model
groups, the channels customers reach the agent through, optional MCP tool
servers, and optional OpenTelemetry tracing and metrics.
[`agent.yml`](https://mantle.rasa.com/reference/agent-yml) `orchestrator` names which group runs the
agent.

The file is copied into the model archive at `rasa train`, and each section is
read from the place that suits what it configures:

| Section | Read from | Effect |
| - | - | - |
| `channels` | The live project directory | Change channel settings and restart. |
| `mcp_servers` | The live project directory | Change MCP URLs or auth and restart so connections reopen. |
| `model_groups` named by `orchestrator.model_group` | The live project directory | Restart after changing the models inside that group. Changing which group `agent.yml` names needs a retrain. |
| `model_groups` named by `voice.asr`, `voice.tts`, or a channel `asr` / `tts` | The live project directory | Restart after changing the group, or after changing which id `agent.yml` or the channel names. No retrain. |
| `model_groups` used by embeddings | The packaged snapshot | Retrain after changing a reference embedder. |
| `tracing` | The live project directory | Optional Langfuse, OTLP, or Jaeger tracing; restart to pick up changes. |
| `metrics` | The live project directory | Optional OTLP metrics export; restart to pick up changes. |
| `a2a_server` | The live project directory | Optional inbound A2A sub-agent server; restart to pick up changes. |
| `recordings` | The live project directory | Optional call recording storage; restart to pick up changes. |

The agent's LLM and reference embedder use the same model-group syntax, but have
different lifecycles. The LLM group is resolved from the live project at
startup. Reference embeddings are resolved from the packaged snapshot because
query vectors must match the vectors built at training time.

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_base: https://api.openai.com/v1
        api_key: ${OPENAI_API_KEY}

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

# Optional — tracing (Langfuse, OTLP, or Jaeger)
# tracing:
#   type: langfuse
#   public_key: ${LANGFUSE_PUBLIC_KEY}
#   private_key: ${LANGFUSE_SECRET_KEY}
#   host: https://cloud.langfuse.com

# Optional — OTLP metrics
# metrics:
#   type: otlp
#   endpoint: localhost:4317
#   insecure: true
```

That is a complete, working file. Everything else is optional.

## Provider examples

`agent.yml` `orchestrator.model_group` names one of the groups below.
`orchestrator.max_prompt_tokens` is optional and defaults to `8000`. Provider,
model, credentials, and provider-specific options belong on the group. A
leftover `llm:` section is invalid.

`provider: openai`, `azure`, and `self-hosted` have dedicated clients. Any other
value is passed through to LiteLLM, so a provider LiteLLM supports works by
naming it and its model.

**OpenAI**

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

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

**Anthropic**

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: anthropic
        model: claude-sonnet-4-6
        api_key: ${ANTHROPIC_API_KEY}

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

**Google Gemini**

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: gemini
        model: gemini-2.5-pro
        api_key: ${GEMINI_API_KEY}

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

**Azure OpenAI.** Name the `deployment` rather than the model, and give the
endpoint and API version:

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: azure
        deployment: my-gpt-deployment
        api_base: https://my-resource.openai.azure.com/
        api_version: "2024-10-21"
        api_key: ${AZURE_OPENAI_API_KEY}

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

**Self-hosted, OpenAI-compatible.** For vLLM, Ollama, TGI, or anything else
serving the OpenAI API shape. `provider`, `model`, and `api_base` are all
required:

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: self-hosted
        model: mistralai/Mistral-7B-Instruct-v0.3
        api_base: http://localhost:8000/v1
        api_key: ${LOCAL_LLM_API_KEY}

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

`model` is the name your server advertises, and `api_base` points at the
OpenAI-compatible route, usually ending in `/v1`. **Omit `api_key`** if the
server takes no key. A present `api_key: ${LOCAL_LLM_API_KEY}` is sent to the
provider even when that variable is unset (the unsubstituted `${…}` string),
so keyless servers must not declare the key.

### Secrets

Sensitive values in config files use environment-variable references — never
literal secrets. Write the whole field as `${ENV_VAR_NAME}` with no extra
text:

```yaml theme={null}
api_key: ${OPENAI_API_KEY}
```

Put the real value in the process environment (for example a project `.env`
that your shell loads before `rasa train` / `rasa run`). Unset `${VAR}`
placeholders are forwarded as-is to the provider; omit `api_key` for keyless
self-hosted servers instead of pointing at a missing variable.

On a model entry, these keys must use `${…}` when present — including when
nested under `oauth:`:

| Key | Typical use |
| - | - |
| `api_key` | Provider API key |
| `aws_access_key_id` / `aws_secret_access_key` / `aws_session_token` | Bedrock / SageMaker |
| `client_id` / `client_secret` / `token_url` | OAuth (for example Azure Entra ID) |
| `public_key` / `private_key` | Langfuse tracing |
| `secret` | A2A JWT secret |

`rasa train` and live LLM / embeddings load reject literal values for those
keys.

## `channels`

Declares the channels customers reach the agent through.

```yaml theme={null}
channels:
  rest: { enabled: true }
  inspector: { enabled: true }
```

Each key is a built-in channel name, or the module path of a custom channel
class such as `addons.my_channel.MyChannel`. See
[Custom channel](https://mantle.rasa.com/reference/custom-channels.md). Values may be:

| Form | Meaning |
| - | - |
| `{ enabled: true }` | Enable with defaults |
| `{ enabled: true, <key>: <value>, … }` | Enable with those keyword arguments |
| `{ enabled: false }` | Disabled: kept in the file but not registered |
| *(empty / null)* | Enable with defaults |

The `enabled` flag is stripped before the remaining keys are handed to the
channel. A non-boolean `enabled`, or an entry that is neither a mapping nor
empty, raises at load.

> [!NOTE]
>
> `rest` and `inspector` are the practical minimum: `rest` is what the evaluation
> runner talks to, and `inspector` is required for `rasa inspect`. A project with
> no `channels:` block registers no channels at all.

`${VAR}` references inside `channels:` are expanded when the file is read, so
channel credentials can come from the environment.

### Voice channels

A voice channel names a speech model group for recognition (`asr`) and
synthesis (`tts`). Declare each group under [`model_groups`](#model_groups),
then set that side to the group's id:

```yaml integrations.yml theme={null}
model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}
  - id: phone_asr
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            language: en
            model: flux-general-en
        eot_threshold: 0.8
  - id: phone_tts
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            model: flux-alexis-en

channels:
  rest: { enabled: true }
  inspector: { enabled: true }
  twilio_media_streams:
    enabled: true
    server_url: agent.example.com
    asr: phone_asr
    tts: phone_tts
    interruptions:
      enabled: true
    silence_timeout: 30
    pause_after_filler: 0.8
    pause_between_messages: 1
```

The same ids can be the default for every voice channel in
[`agent.yml`](https://mantle.rasa.com/reference/agent-yml#asr-and-tts):

```yaml agent.yml theme={null}
voice:
  asr: phone_asr
  tts: phone_tts
```

For each side, the channel value wins, then `voice.asr` or `voice.tts`, then
that channel's built-in default. The Inspector uses Deepgram when a side is
unset on both the channel and in `agent.yml`. Every other voice channel fails
to start until that side is set in one of those two places.

A channel side that is a mapping still loads, and Mantle warns that this shape
is deprecated. On that mapping, `provider` names the engine. `name` still works
and warns. Declare a model group and set the side to that group's id.

| Side | `provider` |
| - | - |
| ASR | `deepgram`, `deepgram_flux`, `azure`, `speechmatics`, `elevenlabs` |
| TTS | `deepgram`, `deepgram_flux`, `azure`, `cartesia`, `rime`, `elevenlabs` |

`provider` is the engine id. `deepgram` is Nova. `deepgram_flux` is Flux for
recognition and for synthesis. The model id does not choose the engine:
`provider: deepgram` stays on Nova even when `model` starts with `flux-`.

A speech group lists exactly one model. A second model fails the group. Speech
has no `router`.

Every other key on the model is a setting for that engine. Those settings are
on [Speech providers](https://mantle.rasa.com/reference/speech-providers.md). Set `api_key` to
`${ENV_VAR_NAME}`, or omit it so the engine reads its usual variable, such as
`DEEPGRAM_API_KEY`. A literal key is rejected. `api_key_env` is no longer
supported.

A `provider` cannot be a Python module path. A
[custom provider](https://mantle.rasa.com/reference/custom-speech-providers.md) (beta) is configured on
the channel, with `provider` set to the module path.

#### `language_map`

`language_map` sets the model, language, and voice per conversation language.
Each key is a language code from `agent.yml` `agent.language`, so an agent with
`language: en` uses the key `en`. A key that is not one of the agent's languages
fails at startup. The provider's own language code, such as `en-US`, goes inside
the entry:

```yaml integrations.yml theme={null}
model_groups:
  - id: phone_asr
    models:
      - provider: azure
        api_key: ${AZURE_SPEECH_API_KEY}
        speech_region: eastus
        language_map:
          en:
            language: en-US
```

| Entry key | Applies to | Meaning |
| - | - | - |
| `language` | ASR and TTS | The provider's language code |
| `model` | ASR and TTS | The provider's model. For Deepgram TTS this selects the voice. |
| `voice` | TTS | The provider's voice name or id |

`language_map` is optional. Entries you write are merged over the engine's
defaults. Do not also set `model`, `language`, or `voice` next to `provider`
when `language_map` is set. Deepgram (non-Flux), Azure, and Speechmatics speech
recognition need `language` in every entry you write. The built-in defaults are
English, so an agent in another language must set `language_map`.

#### `interruptions`

Lets the caller talk over the agent. When an interruption is accepted, playback
stops. A tool that is already running finishes, then the agent answers what the
caller said. Tools are cancelled only when the turn ends, such as on a hangup.
See [Cancellation](https://mantle.rasa.com/reference/tools.md#cancellation).

```yaml theme={null}
interruptions:
  enabled: true
  min_words: 3
  backchannel_threshold: 0.7
  cooldown:
    max_interruptions: 3
    window: 10
    duration: 8
    scope: call
```

| Key | Default | Effect |
| - | - | - |
| `enabled` | `false` (`true` on `inspector`) | Accept interruptions while agent audio is playing or queued. Interruption handling is in beta. |
| `min_words` | `3` | Transcripts shorter than this are scored as possible backchannels before they can interrupt |
| `backchannel_threshold` | `0.7` | Score at or above which a short transcript is ignored as a backchannel. Lower it to ignore more short speech; raise it to let more of it interrupt. |
| `cooldown` | unset | Pause interruptions after too many happen in a short time. Same shape as [`voice.interruptions.cooldown`](https://mantle.rasa.com/reference/agent-yml#cooldown). Omit the block to leave this off. |

`cooldown` requires `max_interruptions`, `window`, and `duration` together. The fields inside the block are those three names plus optional `scope`. `scope` is `call` or `response` and defaults to `call`. `call` forgets interruptions as they age out of the window. `response` also clears the count after one agent response finishes playing without being interrupted.

This nested block belongs under the channel's `interruptions` key. A block on the channel replaces the agent's [`voice.interruptions.cooldown`](https://mantle.rasa.com/reference/agent-yml#cooldown) block as a whole.

While the cooldown is active, caller speech that overlaps agent audio is recorded as [`user_input_suppressed`](https://mantle.rasa.com/reference/events#suppressed-user-input) with reason `interruption_cooldown` and does not start a turn. Choose the three numbers from calls where the two sides talk over each other; there is no built-in default.

To set these once for every voice channel, use
[`voice.interruptions`](https://mantle.rasa.com/reference/agent-yml#interruptions) in `agent.yml`. A
key set here overrides the agent value for this channel only.

##### How backchannels are classified

When the caller speaks while agent audio is playing or queued, each transcript,
including partial ones, is classified in two steps:

1. Speech of at least `min_words` words, ignoring punctuation, is accepted as an
   interruption immediately, without a model call.
2. Shorter speech is scored by a natural language inference (NLI) cross-encoder:
   a quantized ONNX build of
   [`MoritzLaurer/deberta-v3-xsmall-zeroshot-v1.1-all-33`](https://huggingface.co/MoritzLaurer/deberta-v3-xsmall-zeroshot-v1.1-all-33),
   run on the CPU. The classifier builds a premise from the last 40 words of the
   agent utterance that is playing and the caller's words, then scores the
   probability that the premise entails the hypothesis "The user briefly
   acknowledges the assistant while it continues speaking, without taking
   the floor." A score at or above
   `backchannel_threshold` is ignored as a backchannel. A lower score is
   accepted as an interruption. A lower threshold therefore ignores more short
   speech, and a higher one lets more of it interrupt.

An accepted interruption stops playback and routes the caller's transcript into
the active turn. A transcript classified as a backchannel does not enter the
turn; it is recorded as a
[`user_input_suppressed`](https://mantle.rasa.com/reference/events#suppressed-user-input) event.

The score depends on both the caller's words and what the agent is saying, so
tune `backchannel_threshold` against your own calls rather than assuming a
particular phrase is ignored.

Scoring adds about 15 ms per short transcript and has a 200 ms budget. If the
model is not loaded, fails, or times out, short speech is ignored, so only speech
of at least `min_words` words interrupts.

Mantle loads the classifier when a voice channel with `interruptions` enabled
starts, or when a trained model with `voice.interruptions.enabled: true` loads.
If its files are not cached locally, Mantle downloads them (approximately 90 MB)
from the Rasa CDN at `cdn.rasa.ai`. Loading the model at startup keeps the first
interruption from waiting for model setup. The `user_input_suppressed` event
carries the classifier verdict, including its score and threshold, and the
Inspector shows the reason.

On `genesys`, audio already sent to Genesys is not flushed when an
interruption is accepted.

#### `silence_timeout`

Seconds of caller silence before the agent checks in. Defaults to `30`. When it
expires, the bundled silence-timeout skill runs; after three consecutive
check-ins, the agent says goodbye and hangs up. See
[Silence timeout](https://mantle.rasa.com/reference/builtin-skills.md#silence-timeout).

#### `pause_after_filler`

Minimum seconds between a [filler](https://mantle.rasa.com/reference/agent-yml.md#fillers), the short
line the agent says before a tool call, and its next message. Defaults to
`0.8`; `0` adds no pause. A value that is not a number of seconds of at least
`0` fails at startup.

The pause counts from when the filler's audio is sent, not from when the caller
hears it finish. If the tool call and reply take longer than the pause, nothing
is added.

#### `pause_between_messages`

Minimum seconds between consecutive agent messages that do not follow a filler.
Defaults to `1`; `0` adds no pause. A value that is not a number of seconds of
at least `0` fails at startup.

The pause counts from when the previous message's audio is sent. If the next
message is ready later than that, nothing is added. The pause after a filler is
[`pause_after_filler`](#pause_after_filler).

#### `background_audio`

Plays background noise, such as a busy office or call centre, under the call.
Omit the block to play none.

```yaml theme={null}
background_audio:
  source: office
  level: 0.2
```

| Key | Required | Effect |
| - | - | - |
| `source` | **Yes** | Built-in audio name (`office`) or path to a local MP3, WAV, FLAC, or Ogg Vorbis file, relative to the directory the agent runs from. Remote URLs are not supported. |
| `level` | No | Gain applied to the audio, from `0` (silent) to `1` (as recorded). Defaults to `0.2`. |

The audio is mixed into the agent's speech and also plays while the agent is
silent, including while it is working on a reply or the caller is speaking. It
loops for the duration of the call. A missing or unreadable file fails at
startup. Omit the `background_audio` block to disable background audio. To use
your own file instead of the built-in office ambience, set `source` to its path:

```yaml theme={null}
background_audio:
  source: ./audio/call-centre.mp3
  level: 0.2
```

#### Deepgram Flux for speech recognition

Deepgram Flux models detect the end of the caller's turn inside the speech
recognizer, rather than the channel inferring it from a period of silence. The
agent starts its turn when the recognizer signals end of turn.

Set `provider` to `deepgram_flux`. `provider: deepgram` stays on Nova.
`language_map` chooses the model for each conversation language:

```yaml integrations.yml theme={null}
model_groups:
  - id: phone_asr
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            language: en
            model: flux-general-en
        eot_threshold: 0.8
        eot_timeout_ms: 5000
```

The two turn-detection knobs are optional:

| Key | Range | Default | Effect |
| - | - | - | - |
| `eot_threshold` | 0.5 to 0.9 | 0.7 | Confidence needed to call end of turn. Lower responds faster and interrupts more. |
| `eot_timeout_ms` | 500 to 10000 | 5000 | Ceiling on silence before the turn is ended regardless. |

Deepgram speech recognition configs reject unknown keys: anything unrecognised fails the
load rather than being ignored, so a typo surfaces at startup.

#### Deepgram Flux for speech synthesis

Use the Flux engine for Deepgram's turn-based streaming TTS API. Set
`provider` to `deepgram_flux` and a `flux-` model for every conversation
language. `provider: deepgram` is Nova synthesis and uses Aura voices:

```yaml integrations.yml theme={null}
model_groups:
  - id: phone_tts
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            model: flux-alexis-en
        speed: 1.05
```

`speed` is optional. When set, it accepts values from `0.5` to `1.5` in `0.05`
increments. Models that do not support runtime speed control require it to be
omitted.

#### Inspector voice

The `inspector` channel is a voice channel too. When both the channel and
`agent.yml` omit a side, that side falls back to Deepgram `nova-3` for
recognition and `aura-2-thalia-en` for synthesis, so `DEEPGRAM_API_KEY` is all
the Inspector's voice mode needs. Set a speech model group, as below, for
Deepgram Flux and faster turn-taking. It takes the same `asr`, `tts`,
`interruptions`, and `silence_timeout` keys as any other voice channel, and
does not need a voice license.

The Inspector streams audio at 48000 Hz. Set `sample_rate` on the channel, or
the `RASA_INSPECTOR_SAMPLE_RATE` environment variable, to use 8000, 16000, or
24000 instead. The channel value wins.

```yaml integrations.yml theme={null}
model_groups:
  - id: inspector_asr
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            language: en
            model: flux-general-en
  - id: inspector_tts
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            model: flux-alexis-en

channels:
  inspector:
    enabled: true
    asr: inspector_asr
    tts: inspector_tts
```

#### Telephony channels

Channels that connect to a phone network stream audio through the same speech
model groups. Each needs a `server_url`, plus `asr` and `tts` on the channel or
in [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#asr-and-tts), and any credentials its
provider uses. A telephony channel has no built-in speech default, and it
requires a license with voice enabled:

| Channel | Provider | Extra keys |
| - | - | - |
| `twilio_media_streams` | Twilio Media Streams | `username`, `password` (optional) |
| `jambonz_stream` | jambonz | `username`, `password` (optional) |
| `audiocodes_stream` | AudioCodes VoiceAI Connect (beta) | `token` |
| `genesys` | Genesys Cloud AudioHook | `api_key`, `client_secret` (optional) |

Webhook URLs and provider setup for each are on
[Connect a phone line](https://mantle.rasa.com/voice/telephony.md).

## `model_groups`

**Required.** Named model configurations used by the agent's LLM, speech
recognition and synthesis, and, when configured, the references embedder.

```yaml 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
```

`agent.yml` `orchestrator.model_group` names the group that runs the agent.
Point `agent.yml` at an embeddings group by id:

```yaml agent.yml theme={null}
agent:
  persona: You are a helpful assistant.

orchestrator:
  model_group: main_model

references:
  embeddings: reference_embeddings
```

Every model-group reference must name a group declared here. Naming an
undeclared group fails validation. Changing the models inside the orchestrator
group requires a restart. Changing `orchestrator.model_group`, or a reference
embeddings group, requires retraining.

A group with one model is the usual orchestrator setup. Without a `router`
block, only `models[0]` is used — extra models are ignored, there is no
fallback, and `rasa data validate` warns. Set `router` when the group should
select among multiple models.

Speech groups live in this same list. [`voice.asr` and `voice.tts`](https://mantle.rasa.com/reference/agent-yml#asr-and-tts)
in `agent.yml`, and `asr` / `tts` on a voice channel, name them by id. See
[Voice channels](#voice-channels). A speech group lists exactly one model and
has no `router`. It cannot be named by `orchestrator.model_group`,
`knowledge_answering.embeddings`, or a knowledge-store `embeddings` model.

## `mcp_servers`

Optional. A list of named MCP servers a skill can import tools from with
`mcp/<server-name>:<tool-name>` in
[`import_tools`](https://mantle.rasa.com/reference/skill-md#import_tools).

Each entry needs a unique `name` and a `url`. Auth, if any, is one of `token`,
`api_key`, `oauth`, or `module` at the top level of that entry. Secrets must
use `${ENV_VAR}` form — literal secret strings are rejected.

```yaml integrations.yml theme={null}
mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}
```

| Key | Required | Description |
| - | - | - |
| `name` | **Yes** | Server id used in `mcp/<name>:<tool>`. Letters, digits, `_`, `.`, and `-`. Must be unique. Tool names are stricter — see [`import_tools`](https://mantle.rasa.com/reference/skill-md#import_tools). |
| `url` | **Yes** | MCP server endpoint. |
| `type` | No | `http` or `https`. When omitted, inferred only from an `http://` or `https://` URL. Other schemes (or a missing scheme) are rejected. |
| `token` | No | Bearer token (`${ENV_VAR}`). |
| `api_key` | No | API key (`${ENV_VAR}`). Optional `header_name` / `header_format` override how it is sent. |
| `oauth` | No | Client-credentials OAuth mapping (`token_url`, `client_id`, `client_secret`, optional `scope` / `audience` / `timeout`). |
| `module` | No | Dotted path to a custom auth strategy class. |
| `tool_timeout` | No | Per-call timeout in seconds for tools on this server. When omitted, falls back to [`tool_timeout` in `agent.yml`](https://mantle.rasa.com/reference/agent-yml#tool_timeout), then to `10`. |
| `meta_map` | No | Optional `_meta` payload built for each tool call. See [`meta_map`](#meta_map). |

Use at most one of `token`, `api_key`, `oauth`, or `module` per server. Omit all
four when the server needs no auth. Auth examples are in
[Auth examples](#auth-examples).

### Auth examples

> [accordion] Bearer token
>
> ```yaml integrations.yml theme={null}
> mcp_servers:
>   - name: banking
>     url: http://localhost:8000/mcp/
>     token: ${MCP_BANKING_TOKEN}
> ```

> [accordion] API key
>
> ```yaml integrations.yml theme={null}
> mcp_servers:
>   - name: catalog
>     url: https://catalog.example.com/mcp/
>     api_key: ${MCP_CATALOG_API_KEY}
>     # header_name: X-API-Key
>     # header_format: "{key}"
> ```

> [accordion] OAuth2 client credentials
>
> ```yaml integrations.yml theme={null}
> mcp_servers:
>   - name: payments
>     url: https://payments.example.com/mcp/
>     oauth:
>       token_url: https://auth.example.com/oauth/token
>       client_id: mantle-agent
>       client_secret: ${MCP_PAYMENTS_CLIENT_SECRET}
>       # scope: tools.read
>       # audience: https://payments.example.com
> ```

> [accordion] Custom module
>
> ```yaml integrations.yml theme={null}
> mcp_servers:
>   - name: internal
>     url: https://internal.example.com/mcp/
>     module: my_package.auth.CustomMcpAuth
> ```

### `meta_map`

Optional. Builds an MCP `_meta` object on each tool call without exposing those
values to the LLM:

```yaml integrations.yml theme={null}
mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}
    tool_timeout: 30
    meta_map:
      static:
        api_version: "v2"
        source: "rasa_agent"
      from_memory:
        - field: user_id
          param: user_id
        - field: account_tier
          param: tier
```

`static` is a mapping of fixed string key/value pairs always sent in `_meta`.

`from_memory` reads memory when the tool runs and sends each value in `_meta`
under `param`. The LLM never sees these values.

| `field` form | Read from |
| - | - |
| Bare name | Importing skill `memory.yml`, then project `memory.yml` (same as `set_memory`) |
| `project.<field>` or `<skill_id>.<field>` | That qualified field when the importing skill may read it |

The key is always sent under `param`. The value is `null` when the field is
unset or the importing skill cannot read it.

On each call, `_meta` keys are merged in this order; a later step replaces an
earlier one for the same key: **`static` → `from_memory` → `modify_tool_call`
metadata**. Two `from_memory` rows with the same `param`: the later row wins.

Declare each referenced field on every skill that imports a tool from this
server. `rasa train` fails when a field is unknown for that skill.

### How skills use a server

Allowlist only the tools you need in the skill's `import_tools`:

```yaml skills/check_balance/skill.md theme={null}
import_tools:
  - mcp/banking:get_balance
```

To attach a family of tools from this server, use `mcp/<name>:<prefix>*` or
`mcp/<name>:*`. See [Import MCP tools](https://mantle.rasa.com/concepts/tools.md#mcp-tools) for a short
walkthrough and [`skill.md` → `import_tools`](https://mantle.rasa.com/reference/skill-md#import_tools)
for collision and load-failure rules.

## Validation

`rasa train` and `rasa data validate` check this file:

| Code | Cause |
| - | - |
| `mantle.validation.config.missing_integrations` | No `integrations.yml` at the project root |
| `mantle.validation.config.unexpected_llm` | An `llm:` section is still present. Set `orchestrator.model_group` in `agent.yml` instead. |
| `mantle.validation.config.unknown_model_group` | `orchestrator.model_group` or an embeddings reference names a group that is not declared, or `model_groups:` is missing or empty |
| `mantle.validation.config.invalid_speech_model_group` | `voice.asr`, `voice.tts`, or a voice channel's `asr` / `tts` names a group that is missing, does not list exactly one model, uses a provider that side does not support, or has a setting that engine does not accept |
| `mantle.validation.config.unused_model_group_models` | A group lists more than one model and has no `router` (warning) |
| `mantle.validation.config.invalid_tracing` | Invalid or unsupported `tracing:` section |
| `mantle.validation.config.invalid_metrics` | Invalid or unsupported `metrics:` section |
| `mantle.validation.config.invalid_mcp_server` | A `mcp_servers:` entry is invalid (shape, auth, URL, secrets) |
| `mantle.validation.config.duplicate_mcp_server_name` | Two `mcp_servers:` entries share the same `name` |
| `mantle.validation.mcp.unknown_from_memory_field` | A `meta_map.from_memory` field is not declared for a skill that imports the server |
| `mantle.validation.config.invalid_event_broker` | Invalid `event_broker:` section |
| `mantle.validation.config.invalid_timer_store` | Invalid `timer_store:` section |
| `mantle.validation.config.invalid_tracker_store` | Invalid `tracker_store:` section |
| `mantle.validation.config.invalid_lock_store` | Invalid `lock_store:` section |
| `mantle.validation.config.invalid_secrets_manager` | Invalid `secrets_manager:` section |
| `mantle.validation.config.literal_secret` | A `password`, `token`, `aws_access_key_id`, `aws_secret_access_key`, or URL with embedded credentials in `tracker_store:`, `lock_store:`, or `secrets_manager:` is a literal (warning; train still succeeds) |
| `mantle.validation.config.invalid_model_server` | Invalid `rasa_model_server:` section (the remote model server) |
| `mantle.validation.config.invalid_recordings` | Invalid `recordings:` section |
| `mantle.validation.config.unsupported_integration_key` | A CALM-only key is present. See [Keys this file does not accept](#keys-this-file-does-not-accept). |
| `mantle.validation.config.unknown_integration_key` | A top-level key that is not documented on this page |

### Keys this file does not accept

Only the top-level sections documented on this page are valid. A CALM-only key
fails `rasa train` with the replacement named in the error.

| Key | Use instead |
| - | - |
| `nlg` | Set `metadata: rephrase: true` on the response variant in the skill's [`responses.yml`](https://mantle.rasa.com/reference/responses-yml#metadata-rephrase). |
| `action_endpoint` | Write `@tool` functions or declare [`mcp_servers`](#mcp_servers). |
| `vector_store` | Declare `knowledge_stores`. |
| `nlu` | Remove it. This engine has no NLU pipeline. |
| `interaction_handling` | Set [`voice.silence_timeout`](https://mantle.rasa.com/reference/agent-yml#silence_timeout) in `agent.yml`. |

## Tracing

Optional. Configure under `tracing:` in `integrations.yml`. Supported types:
`langfuse`, `otlp`, and `jaeger`. Restart the process after changing this
section. Span catalog: [Observability](https://mantle.rasa.com/reference/observability.md).

`tracing:` takes a single tracer, or a list with at most one `langfuse` entry
and at most one `otlp` or `jaeger` entry. See
[Langfuse with OTLP or Jaeger](#langfuse-with-otlp-or-jaeger).

Tracing is read only from `integrations.yml`. An `endpoints.yml` file at the
project root fails startup. Passing `--endpoints` fails too. If the `tracing:`
section is invalid, `rasa train` reports it and `rasa run` starts without
tracing.

### Langfuse

```yaml theme={null}
tracing:
  type: langfuse
  public_key: ${LANGFUSE_PUBLIC_KEY}
  private_key: ${LANGFUSE_SECRET_KEY}
  host: https://cloud.langfuse.com
```

| Key | Required | Notes |
| - | - | - |
| `type` | yes | Must be `langfuse`. |
| `public_key` | yes | Must use a `${ENV_VAR}` reference — literal secrets are rejected. |
| `private_key` | yes | Must use a `${ENV_VAR}` reference — literal secrets are rejected. |
| `host` | yes | Langfuse Cloud or your self-hosted URL. |
| `environment` | no | Optional Langfuse environment name (lowercase, digits, `-`/`_`). |
| `timeout` | no | HTTP timeout in seconds (maps to `LANGFUSE_TIMEOUT`). |
| `debug` | no | Enable Langfuse debug logging (`LANGFUSE_DEBUG`). |
| `release` | no | Release/version tag attached to traces (`LANGFUSE_RELEASE`). |
| `sample_rate` | no | Trace sampling rate between 0 and 1 (`LANGFUSE_SAMPLE_RATE`). |
| `media_upload_thread_count` | no | Media upload thread pool size (`LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT`). |

`public_key` and `private_key` must use `${ENV_VAR}` references — literal secrets
are rejected at validation and apply time. Those references are kept as literal
strings when `integrations.yml` is parsed (they are not expanded like channel
credentials). They are resolved when Langfuse configures at CLI startup; if a
variable is unset, resolution is best-effort and may leave the literal `${VAR}`
in the process environment, so tracing is skipped rather than aborting startup.
Use `rasa data validate` to catch invalid shape or key syntax before deploy.

Install the monitoring extra (`pip install rasa-pro[monitoring]`), set
`LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY`, then enable the block. Example
agents ship it commented out so local defaults stay key-free.

### OTLP

```yaml theme={null}
tracing:
  type: otlp
  endpoint: localhost:4317
  insecure: true
```

| Key | Required | Notes |
| - | - | - |
| `type` | yes | Must be `otlp`. |
| `endpoint` | yes | Collector gRPC endpoint (`host:port`). |
| `insecure` | no | Use an insecure channel when `true`. |
| `root_certificates` | no | Path to a CA bundle for TLS. |
| `service_name` | no | Service name reported to the collector. |

### Jaeger

```yaml theme={null}
tracing:
  type: jaeger
  host: localhost
  port: 4317
```

| Key | Required | Notes |
| - | - | - |
| `type` | yes | Must be `jaeger`. |
| `host` | no | Agent host (default `localhost`). |
| `port` | no | Collector OTLP gRPC port (default `4317`). |
| `username` / `password` | no | Optional credentials, sent as a Basic `Authorization` header. When set, `insecure` is required. |
| `insecure` | no | `false` exports over TLS; `true` sends spans and credentials unencrypted. Defaults to `true` when no credentials are set. |
| `root_certificates` | no | Path to a CA bundle for TLS. Uses the system trust store when omitted. |
| `service_name` | no | Service name reported to Jaeger. |
| `sync_export` | no | `true` exports each span immediately. Omit it, or set null, to keep batched export. |

With credentials, set `insecure: false` so they are not sent in plaintext:

```yaml theme={null}
tracing:
  type: jaeger
  host: jaeger.example.com
  port: 4317
  username: ${JAEGER_USERNAME}
  password: ${JAEGER_PASSWORD}
  insecure: false
  root_certificates: certs/ca.pem
```

### Langfuse with OTLP or Jaeger

List both tracers to send LLM traces to Langfuse and spans to a collector:

```yaml theme={null}
tracing:
  - type: langfuse
    public_key: ${LANGFUSE_PUBLIC_KEY}
    private_key: ${LANGFUSE_SECRET_KEY}
    host: https://cloud.langfuse.com
  - type: otlp
    endpoint: localhost:4317
    insecure: true
```

Each entry takes the same keys as its single-tracer form above. Declaring two
`langfuse` entries, or both `otlp` and `jaeger`, is a validation error.

## Metrics

Optional. Export OpenTelemetry metrics to an OTLP collector:

```yaml theme={null}
metrics:
  type: otlp
  endpoint: localhost:4317
  insecure: true
```

| Key | Required | Notes |
| - | - | - |
| `type` | yes | Must be `otlp`. |
| `endpoint` | yes | Collector gRPC endpoint (`host:port`). |
| `insecure` | no | Use an insecure channel when `true`. |
| `root_certificates` | no | Path to a CA bundle for TLS. |
| `service_name` | no | Service name reported to the collector. |

Metrics can be enabled without configuring tracing. Metric catalog:
[Metrics](https://mantle.rasa.com/reference/metrics.md).

Metrics are read only from `integrations.yml`. An `endpoints.yml` file at the
project root fails startup. Passing `--endpoints` fails too. If the `metrics:`
section is invalid, `rasa train` reports it and `rasa run` starts without
metrics.

## `a2a_server`

Optional. Configure the agent as an inbound A2A server. An orchestrator reads
the AgentCard at `/.well-known/agent-card.json` on the main `rasa run` port.
Declare the block at the top level of `integrations.yml`. Presence of the
block turns the server on; omit the block to leave it off.

```yaml integrations.yml theme={null}
a2a_server:
  description: Handles billing questions for existing customers.
  url: https://billing-agent.example.com
  auth:
    type: bearer
    jwt:
      algorithm: HS256
      secret: ${A2A_JWT_SECRET}
```

| Key | Required | Description |
| - | - | - |
| `description` | **Yes** | Public description advertised in the AgentCard. |
| `url` | No | Public base URL orchestrators use, advertised in the AgentCard. When omitted, `rasa run` builds it from `--port`, `--interface`, and the SSL flags. |
| `agent_card_path` | No | Path to a static AgentCard JSON file served instead of the generated card. Must be A2A 1.0 JSON: declare `supportedInterfaces`; a top-level `url` fails startup with an error that names the file. |
| `include_default_skills` | No | `false` by default. CALM's `include_conversation_repair` defaults to `true`; this stays off until the project opts in. When `true`, a default skill that a project override made routable (its `skill.md` sets `routing.engine_managed: false`) is advertised on the generated card, so you decide whether the orchestrator or this agent owns it. Engine-managed, disabled, and hidden skills are never advertised. |
| `task_timeout_seconds` | No | Seconds an in-flight task may run before the server cancels it. Defaults to `600`. `0` disables the timer. |
| `a2a_message_cache_ttl_seconds` | No | Seconds a completed `message_id` can be replayed from cache. Defaults to the task timeout. `0` disables replay. |
| `max_contexts` | No | Maximum distinct `context_id` sessions kept until a terminal outcome. Defaults to `1000`. `0` disables the cap. |
| `push_notifications_enabled` | No | `false` by default. When `true`, task updates are POSTed to callback URLs and the generated AgentCard advertises push notifications. A callback that sets a token or authentication must use `https`. See [Push callbacks](#push-callbacks). |
| `push_notification_allowed_hosts` | No | Optional hostname allowlist for push callback URLs (exact or subdomain match). Loopback and private-network targets are always rejected. Applied when push notifications are enabled. |
| `auth` | No | Bearer JWT verification: `type: bearer` and a `jwt` mapping with `algorithm`, `secret` (HS256, HS512) or `public_key_path` (RS\*, ES\*, PS\*), and optional `issuer` / `audience`. When set, the first authenticated caller of a `context_id` owns it. See [Context ownership](#context-ownership). |

Unknown keys are rejected. `${ENV_VAR}` references are expanded when the file
is read; `auth.jwt.secret` must stay an `${ENV_VAR}` reference — a literal
secret fails to load. The CALM-only key `include_conversation_repair` is
rejected with a pointer to `include_default_skills`.

### Push callbacks

When `push_notifications_enabled` is true, a callback that sets a `token` or
`authentication` must use `https`. An `http` callback is accepted only when it
sets neither. `rasa run` still starts, and the startup log states this
requirement. Secret headers are not sent to an `http` callback.

`tasks/pushNotificationConfig/get` and `tasks/pushNotificationConfig/list`
return the config with `token` and `authentication.credentials` cleared.
Creating or replacing a config still returns what you sent. To update a
config, send the token and credentials again. A value read back cannot be
written back.

### Context ownership

When `auth` is set, the authenticated caller that first uses a `context_id`
owns that conversation. The caller is the JWT `sub`, otherwise
`preferred_username`, otherwise `client_id`. A validated token with none of
those claims is rejected with `401`, rather than treated as an anonymous
caller: without this, every such token would resolve to the same shared
identity and those callers could reach each other's conversations and tasks.
**This is a backward-incompatible change** for any orchestrator that was
relying on a `sub`-, `preferred_username`-, and `client_id`-less JWT — add one
of those claims to its token. A later `message/send` or `message/stream` from
a different caller is rejected as context not found. The first message may
still choose its own `context_id`, and a message that omits `context_id`
still starts a session. Without `auth`, context ids are not bound to a
caller.

The first caller is reserved in the server process before its turn starts, and
the owner is recorded when that turn is stored. Another copy of the server can
still accept a racing first message for the same `context_id` until the owner
is recorded. Route every request for a `context_id` to the same replica. The
routing key is that A2A `context_id`. A generic load-balancer session cookie,
source IP, or connection affinity does not provide it, because those keys can
group different contexts together or split one context across replicas. A
conversation that has no owner recorded yet, such as one started before `auth`
was set, is claimed by the next authenticated caller. Follow-ups need a token
for the same caller. If Rasa cannot read an existing conversation, it rejects
the request rather than treating it as unclaimed.

> [!WARNING]
>
> **Rotating the JWT key invalidates existing A2A contexts**
>
> Ownership is bound to the JWT verification material: `auth.jwt.secret` for `HS256` and `HS512`, or the public key at `auth.jwt.public_key_path` for `RS*`, `ES*`, and `PS*`. Replacing that secret or public key changes the owner recorded for every conversation. The same caller no longer matches contexts they already own, and a follow-up `message/send` or `message/stream` is rejected as context not found. Finish or abandon those conversations before you rotate the key, or keep the previous verification material until they end.
>
> The owner also includes which JWT claim supplied the caller identity (`sub`,
> `preferred_username`, or `client_id`). Changing the claim used for an existing
> caller likewise invalidates its contexts.

The same `a2a_server` keys in CALM `endpoints.yml` follow these rules.

The block is read from `RASA_PROJECT_FOLDER` when that is set, otherwise from
the working directory, when `rasa run` starts. It is bound to the model once
the model loads.

### Generated AgentCard

Without `agent_card_path`, the card is generated from the skill catalog once
the model loads. The card name is `agent.id` from `agent.yml`. Each skill the
Mantle router may activate becomes one card skill, with the skill's `name` and
`description` from `skill.md` and the skill id as its tag. Skills that are
`engine_managed`, `disabled`, or `hidden` are never advertised. Bundled default
skills are left off as well; `include_default_skills: true` advertises a default
skill only after a project override made it routable (its `skill.md` sets
`routing.engine_managed: false`). Since bundled defaults ship engine-managed,
the flag alone does not put them on the card. Internal ordered blocks
(`routable: false`) are never advertised on their own.

The card declares two JSON-RPC interfaces on the one `url` above: A2A 1.0 and
A2A 0.3. There is no second server; both versions are served on the main
`rasa run` port, and the serialized card keeps a top-level `url` so 0.3
orchestrators can still read it.

The card is generated when the model loads at startup. A later `PUT /model`
or `DELETE /model` on the Rasa HTTP API rebuilds
it after that model passes the same engine and session checks as startup. The
HTTP response waits until a turn already in progress finishes on the model it
started with. That model is retired only after the turn finishes. `DELETE /model`
publishes a card with no generated skills. A static `agent_card_path` still
replaces the generated card.

Migrating a running server from CALM to Mantle takes a restart. `PUT /model`
of a model trained for the other engine fails with
`validation.a2a_server.engine_mismatch`, and the model already loaded stays in
place. `DELETE /model` unloads that model and leaves the process on the engine
it started with. Stop `rasa run` and start it again with the retrained Mantle
model.

When the `a2a_server` block is present, [`session_config`](https://mantle.rasa.com/reference/agent-yml#session_config)
in `agent.yml` must set `start_session_after_expiry: false`, so a resumed A2A
`context_id` never silently starts a fresh session. Startup fails with
`validation.a2a_server.incompatible_session_config` otherwise. The A2A server
also requires a single Sanic worker (`SANIC_WORKERS=1`).

An `a2a_server` block in `endpoints.yml` is ignored for a Mantle project, and
startup logs a warning. If the model was trained for a different engine than
the project layout implies, A2A startup fails with
`validation.a2a_server.engine_mismatch`; retrain the model.

## `event_broker`

Optional. Stream conversation events to a broker. Read only from
`integrations.yml`. An `endpoints.yml` file at the project root fails startup. Passing `--endpoints` fails too.
Omit the section to publish no events.

```yaml theme={null}
event_broker:
  type: pika
  url: ${RABBITMQ_URL}
  username: ${RABBITMQ_USERNAME}
  password: ${RABBITMQ_PASSWORD}
  queues:
    - rasa_events
```

| Key | Required | Notes |
| - | - | - |
| `type` | no | `pika` (the default), `sql`, `file`, `kafka`, `concurrent_kafka`, `http`, or the import path of a custom event broker class. A custom path must import successfully at train and must subclass `EventBroker`. See [Custom event broker](https://mantle.rasa.com/reference/custom-event-broker.md). |
| `url` | for `pika`, `kafka`, and `concurrent_kafka` | Broker address. For `kafka` and `concurrent_kafka`, a list of `url[:port]` bootstrap servers is also valid (a comma-separated string still works). `file` uses `path` instead; `sql` uses `url` as the database host when it is not sqlite. Do not set `host` for `pika` or `sql` — it conflicts with how those brokers are constructed. |
| `username` | for `pika` | RabbitMQ username. Required even when `url` is an `amqp://` URI; credentials in that URI are not read at construction. |
| `password` | for `pika` | RabbitMQ password. Required even when `url` is an `amqp://` URI. |

Other keys are the ones that broker type already accepts (`queues`, `topic`,
`path`, and so on).

With `RASA_RECORD_COMMANDS_AND_PROMPTS=true`, a rephrased `BotUttered` event
published to the event broker carries its rephrase prompt under
`metadata.prompts` and the text before rephrasing under
`metadata.domain_ground_truth`. The tracker store, `rasa export`, and the
anonymization topics do not get them. They are not anonymized. A prompt over 60,000
characters keeps only its end, so the event fits Kafka's default 1 MB
`message.max.bytes`.

## `timer_store`

Optional. Store background session timers. Read only from `integrations.yml`.
An `endpoints.yml` file at the project root fails startup. Passing `--endpoints` fails too. Omit the section to
keep timers in memory.

```yaml theme={null}
timer_store:
  type: redis
  host: localhost
  port: 6379
  db: 2
  password: ${REDIS_PASSWORD}
```

| Key | Required | Notes |
| - | - | - |
| `type` | no | `in_memory` (the default), `redis`, or the import path of a custom timer store class. A custom path must import successfully at train and must subclass `SessionTimerStore`. See [Custom timer store](https://mantle.rasa.com/reference/custom-timer-store.md). |
| `host` | no | Redis host (default `localhost`). `url` is a deprecated alias for `host`. |
| `port` | no | Redis port (default `6379`). |
| `password` | no | Redis password. |
| `db` | no | Redis database number (default `2`). |
| `key_prefix` | no | Alphanumeric prefix for timer keys. |
| `poll_interval` | no | Seconds between checks for expired timers (default `1.0`). |
| `socket_timeout` | no | Seconds before a Redis command times out (default `10`). |

The shared Redis connection keys also apply: `username`, `use_ssl`, `ssl_certfile`, `ssl_keyfile`,
`ssl_ca_certs`, `deployment_mode`, `endpoints`, and `sentinel_service`.
Any value can be a `${VAR}` placeholder, including `port` and `db`.

## `rasa_model_server`

Optional. Pull a trained model from a server at startup, and again every
`wait_time_between_pulls` seconds. This is the remote model server. It is not
the `models` list inside a [`model_groups`](#model_groups) entry.

Read only from `integrations.yml`. An `endpoints.yml` file at the project root
fails startup. Passing `--endpoints` fails too. A top-level `models:` block in
`integrations.yml` fails train (`mantle.validation.config.invalid_model_server`);
move it to `rasa_model_server:`. Omit the section to load a local model
(`rasa train`, then `rasa run --model`) or use `--remote-storage`.

```yaml theme={null}
rasa_model_server:
  url: http://my-server.example/models/default@latest
  token: ${MODEL_SERVER_TOKEN}
  wait_time_between_pulls: 10
```

| Key | Required | Notes |
| - | - | - |
| `url` | yes | HTTP(S) URL the model archive is pulled from. Blank or non-URL values fail train and startup; `${VAR}` placeholders expand at runtime. |
| `token` | no | Token sent as a query parameter with each pull. |
| `token_name` | no | Query parameter name for `token`. Defaults to `token`. |
| `params` | no | Extra query parameters sent with each pull. |
| `headers` | no | Extra HTTP headers sent with each pull. |
| `basic_auth` | no | HTTP basic auth for the pull: `username` and `password`. |
| `cafile` | no | Path to a CA bundle for TLS verification (same key as `endpoints.yml` `models:`). |
| `wait_time_between_pulls` | no | Seconds between refresh pulls. `0` pulls once at startup and does not refresh. Defaults to 100 when omitted. |

Any value can be a `${VAR}` placeholder, including `wait_time_between_pulls`.

## `tracker_store`

Optional. Store conversation trackers. Read only from `integrations.yml`. An
`endpoints.yml` file at the project root fails startup. Passing `--endpoints`
fails too. Omit the section to keep conversations in memory (they do not
survive a restart).

```yaml theme={null}
tracker_store:
  type: sql
  dialect: postgresql
  url: ${DB_HOST}
  db: rasa
  username: ${DB_USER}
  password: ${DB_PASSWORD}
```

| Key | Required | Notes |
| - | - | - |
| `type` | no | `in_memory` (the default when omitted), `redis`, `mongod`, `sql`, `dynamo`, or the import path of a custom tracker store class. A custom path must import successfully at train and must subclass `BaseTrackerStore` from `rasa.api.tracker.v1`. See [Custom tracker store](https://mantle.rasa.com/reference/custom-tracker-store.md). |
| `url` | no | Store address. For SQL this is the database host. Do not embed `user:password@` in the URL; use `${VAR}` or a secrets manager mapping. |
| `username` | no | Database user. May be a string or `{source: secrets_manager.vault, secret_key: ...}`. |
| `password` | no | Database password. A literal value is a train-time warning. Prefer `${VAR}` or a secrets manager mapping. Quote a number (`"12345"`); an unquoted number fails train. |

Other keys are the ones that store type already accepts (`dialect`, `db`,
`port`, `region`, and so on). A literal `password`, `token`,
`aws_access_key_id`, `aws_secret_access_key`, or credential URL warns at
`rasa train` (`mantle.validation.config.literal_secret`) and does
not fail the build. An invalid block fails train and startup
(`mantle.validation.config.invalid_tracker_store`).

## `lock_store`

Optional. Lock a conversation so overlapping turns are handled one at a time.
Read only from `integrations.yml`. An `endpoints.yml` file at the project root
fails startup. Passing `--endpoints` fails too. Omit the section to keep locks
in memory.

Use `redis` or `concurrent_redis` when the agent runs with more than one
worker or replica. An in-memory lock store is not shared across processes.
Startup logs a warning when more than one Sanic worker is requested and the
lock store is in memory, and the process stays on one worker.

```yaml theme={null}
lock_store:
  type: redis
  host: ${REDIS_HOST}
  port: 6379
  username: ${REDIS_USERNAME}
  password: ${REDIS_PASSWORD}
```

| Key | Required | Notes |
| - | - | - |
| `type` | no | `in_memory` (the default when omitted), `redis`, `concurrent_redis`, or the import path of a custom lock store class. A custom path must import successfully at train and must subclass `BaseLockStore` from `rasa.api.locks.v1`. |
| `host` | no | Redis host (default `localhost`). For `redis`, `url` is a deprecated alias for `host`. `concurrent_redis` reads `host`. |
| `port` | no | Redis port (default `6379`). |
| `username` | no | Redis username. Set together with `password`, or omit both. |
| `password` | no | Redis password. A literal value is a train-time warning. Prefer `${VAR}`. Quote a number (`"12345"`); an unquoted number fails train. |

A custom lock store subclasses `BaseLockStore` and implements `connect`, `get_lock`, `save_lock`, and `delete_lock`. Conversation ordering is included. See [Write a custom lock store](https://mantle.rasa.com/reference/custom-lock-store.md).

`db`, `key_prefix`, `use_ssl`, `deployment_mode`, `endpoints`, and
`sentinel_service` are the same keys the Redis lock store already accepts.
A literal `password`, `token`, or credential URL warns at `rasa train`
(`mantle.validation.config.literal_secret`) and does not fail the build. An
invalid block fails train and startup
(`mantle.validation.config.invalid_lock_store`).

## `knowledge_stores`

Optional. Register searchable knowledge stores. Read only from `integrations.yml`.

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

knowledge_stores:
  - id: faq
    type: addons.custom_knowledge_store.MyKnowledgeStore
    embeddings: reference_embeddings
```

| Key | Required | Notes |
| - | - | - |
| `id` | yes | Unique name for the store. Duplicate ids fail validation. |
| `type` | yes | `faiss`, `qdrant`, `milvus`, or the module path of a custom knowledge store class. |
| `embeddings` | yes | Id of a text embeddings group under `model_groups`. A speech group cannot be used here. |

Each entry accepts only these three keys. Any other key fails validation
(`mantle.validation.config.invalid_knowledge_store`). `rasa train` checks the
shape of each entry. For a custom class, it does not import the class.

Mantle does not query knowledge stores yet. `search_knowledge` reads only the
local index built from `references/`. See [What's next](https://mantle.rasa.com/whats-next.md) and
[Custom knowledge store](https://mantle.rasa.com/reference/custom-knowledge-store.md).

## `secrets_manager`

Optional. Load tracker-store credentials from Vault. Read only from
`integrations.yml`. An `endpoints.yml` file at the project root fails startup. Passing `--endpoints` fails too.
Omit the section to keep today's environment
path: `SECRET_MANAGER=vault` plus `VAULT_URL`, `VAULT_TOKEN`, and
`VAULT_RASA_SECRETS_PATH`. Those variables override the same fields in this
block.

`privacy` and `a2a_server` in
`endpoints.yml` have no effect on a Mantle agent. Configure per-field
anonymization on `pii: true` memory fields and tracker-store cron in
[`agent.yml` `privacy`](https://mantle.rasa.com/reference/agent-yml#privacy). Configure the inbound
A2A server under [`a2a_server`](#a2a_server).

```yaml theme={null}
secrets_manager:
  type: vault
  url: ${VAULT_URL}
  token: ${VAULT_TOKEN}
  secrets_path: rasa-secrets
```

| Key | Required | Notes |
| - | - | - |
| `type` | yes | `vault`. |
| `url` | no | Vault address. `VAULT_URL` overrides it. A URL with embedded credentials is a train-time warning. |
| `token` | no | Vault token. `VAULT_TOKEN` overrides it. A literal value is a train-time warning. Prefer `${VAR}`. |
| `secrets_path` | no | Path of the secret in Vault. Defaults to `rasa-secrets` when omitted. `VAULT_RASA_SECRETS_PATH` overrides it. |
| `transit_mount_point` | no | Transit secrets engine mount. Optional. |
| `namespace` | no | Vault namespace. Optional. |
| `mount_point` | no | KV secrets engine mount. Optional. |

A tracker store `username` or `password` may be a mapping
`{source: secrets_manager.vault, secret_key: ...}` instead of a string. A
literal `token` or credential URL warns at `rasa train`
(`mantle.validation.config.literal_secret`) and does not fail the build. An
invalid block fails train and startup
(`mantle.validation.config.invalid_secrets_manager`).

## `recordings`

Optional. Store voice-call audio. Read only from `integrations.yml`. An
`endpoints.yml` file at the project root fails startup. Passing `--endpoints`
fails too. Omit the section to leave recording off. Restart to pick up
changes.

```yaml theme={null}
recordings:
  enabled: true
  provider: s3
  s3:
    bucket: rasa-call-recordings
    region: eu-central-1
    prefix: recordings/
```

| Key | Required | Notes |
| - | - | - |
| `enabled` | no | `false` when omitted. Provider settings are not required while recording is off. |
| `provider` | when `enabled` is `true` | `s3`, `gcs`, `azure`, or `local`. There is no default. That provider's block is required. |
| `s3` | when `provider` is `s3` | `bucket` is required. `region`, `prefix` (default `recordings/`), and `endpoint_url` are optional. |
| `gcs` | when `provider` is `gcs` | `bucket` is required. `prefix` defaults to `recordings/`. |
| `azure` | when `provider` is `azure` | `container` and `account_name` are required. `prefix` defaults to `recordings/`. `endpoint_url` is optional. |
| `local` | when `provider` is `local` | `path` is required. A directory on the server. |

An invalid block fails train and startup
(`mantle.validation.config.invalid_recordings`). A `${VAR}` placeholder in
`enabled` is checked when the process starts, not at `rasa train`.

## See also

* [`agent.yml`](https://mantle.rasa.com/reference/agent-yml): identity, persona, prompt tuning, and [`voice.asr` / `voice.tts`](https://mantle.rasa.com/reference/agent-yml#asr-and-tts)
* [Speech providers](https://mantle.rasa.com/reference/speech-providers.md): built-in ASR and TTS providers and their settings
* [Observability](https://mantle.rasa.com/reference/observability.md): voice span catalog
* [Metrics](https://mantle.rasa.com/reference/metrics.md): metric catalog


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