Skip to main content
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
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
integrations.yml
Anthropic
integrations.yml
Google Gemini
integrations.yml
Azure OpenAI. Name the deployment rather than the model, and give the endpoint and API version:
integrations.yml
Self-hosted, OpenAI-compatible. For vLLM, Ollama, TGI, or anything else serving the OpenAI API shape. 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:
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:: rasa train and live LLM / embeddings load reject literal values for those keys.

channels

Declares the channels customers reach the agent through.
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. 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
The same ids can be the default for every voice channel in agent.yml:
agent.yml
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. 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:
  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, 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 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. Set provider to deepgram_flux. provider: deepgram stays on Nova. language_map chooses the model for each conversation language:
integrations.yml
The two turn-detection knobs are optional: 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:
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

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

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

integrations.yml
integrations.yml
integrations.yml
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’s import_tools:
skills/check_balance/skill.md
To attach a family of tools from this server, use 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 fails rasa train with the replacement named in the error.

Tracing

Optional. Configure under tracing: 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:
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:
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

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.
Rotating the JWT key invalidates existing A2A contextsOwnership 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 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