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 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:
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.
integrations.yml
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
integrations.yml
integrations.yml
integrations.yml
deployment rather than the model, and give the
endpoint and API version:
integrations.yml
provider, model, and api_base are all
required:
integrations.yml
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:
.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::
rasa train and live LLM / embeddings load reject literal values for those
keys.
channels
Declares the channels customers reach the agent through.
addons.my_channel.MyChannel. See
Custom channel. Values may be:
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.
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,
then set that side to the group’s id:
integrations.yml
agent.yml:
agent.yml
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.
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. 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 (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:
integrations.yml
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.
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 block as a whole.
While the cooldown is active, caller speech that overlaps agent audio is recorded as user_input_suppressed 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 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:- Speech of at least
min_wordswords, ignoring punctuation, is accepted as an interruption immediately, without a model call. - 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, 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 abovebackchannel_thresholdis 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.
user_input_suppressed 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.
pause_after_filler
Minimum seconds between a filler, 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.
background_audio
Plays background noise, such as a busy office or call centre, under the call.
Omit the block to play none.
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:
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. Setprovider to deepgram_flux. provider: deepgram stays on Nova.
language_map chooses the model for each conversation language:
integrations.yml
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. Setprovider to deepgram_flux and a flux- model for every conversation
language. provider: deepgram is Nova synthesis and uses Aura voices:
integrations.yml
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
Theinspector 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.
integrations.yml
Telephony channels
Channels that connect to a phone network stream audio through the same speech model groups. Each needs aserver_url, plus asr and tts on the channel or
in agent.yml, and any credentials its
provider uses. A telephony channel has no built-in speech default, and it
requires a license with voice enabled:
Webhook URLs and provider setup for each are on
Connect a phone line.
model_groups
Required. Named model configurations used by the agent’s LLM, speech
recognition and synthesis, and, when configured, the references embedder.
agent.yml orchestrator.model_group names the group that runs the agent.
Point agent.yml at an embeddings group by id:
agent.yml
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
in agent.yml, and asr / tts on a voice channel, name them by id. See
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.
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.
integrations.yml
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
Bearer token
Bearer token
integrations.yml
API key
API key
integrations.yml
OAuth2 client credentials
OAuth2 client credentials
integrations.yml
Custom module
Custom module
integrations.yml
meta_map
Optional. Builds an MCP _meta object on each tool call without exposing those
values to the LLM:
integrations.yml
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.
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’simport_tools:
skills/check_balance/skill.md
mcp/<name>:<prefix>* or
mcp/<name>:*. See Import MCP tools for a short
walkthrough and skill.md → import_tools
for collision and load-failure rules.
Validation
rasa train and rasa data validate check this file:
Keys this file does not accept
Only the top-level sections documented on this page are valid. A CALM-only key failsrasa train with the replacement named in the error.
Tracing
Optional. Configure undertracing: in integrations.yml. Supported types:
langfuse, otlp, and jaeger. Restart the process after changing this
section. Span catalog: Observability.
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.
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
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
Jaeger
With credentials, set
insecure: false so they are not sent in plaintext:
Langfuse with OTLP or Jaeger
List both tracers to send LLM traces to Langfuse and spans to a collector:langfuse entries, or both otlp and jaeger, is a validation error.
Metrics
Optional. Export OpenTelemetry metrics to an OTLP collector:
Metrics can be enabled without configuring tracing. Metric catalog:
Metrics.
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.
integrations.yml
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
Whenpush_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
Whenauth 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.
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
Withoutagent_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
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.
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.
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 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.
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).
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.
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.
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.
integrations.yml
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 and
Custom knowledge store.
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. Configure the inbound
A2A server under a2a_server.
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.
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: identity, persona, prompt tuning, andvoice.asr/voice.tts- Speech providers: built-in ASR and TTS providers and their settings
- Observability: voice span catalog
- Metrics: metric catalog