> ## Documentation Index
> Fetch the complete documentation index at: https://rasa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Builder-facing changes collected under Unreleased, then labeled by version at release.

This changelog tracks changes to the builder interface. Only changes that affect how you
write skills, tools, memory, or responses are listed here. Internal runtime changes without
builder-facing impact are omitted.

**Unreleased** lists builder-facing changes that have landed but are not yet part of a
tagged Mantle release. Older releases appear below as their own version sections.
When Unreleased is empty it shows a short placeholder; once entries land they are
grouped under typed subsections. Each version section starts with **Breaking Changes**
when that subsection has entries — scan Breaking Changes first when upgrading.

**Unreleased**

### Improvements

* [#7471](https://github.com/RasaHQ/rasa-private/pull/7471): `rasa init` now asks
  which coding agents to set up (Claude Code, Cursor, VS Code, or OpenAI Codex),
  with Claude Code and Cursor pre-selected, and installs the Mantle skills,
  registers the Rasa MCP server, and downloads the Mantle documentation only for
  the ones you pick. Pass `--ides` (for example `--ides claude,vscode`) to choose
  without the prompt, or `--ides ''` to skip. With `--no-prompt` and no `--ides`,
  Claude Code and Cursor are set up as before.
* [#7528](https://github.com/RasaHQ/rasa-private/pull/7528): Improved default
  tool-call acknowledgements (fillers). They are less likely to promise or
  predict the result, such as "I'll place the order now" or "Sure, I can help
  with that", and are phrased to stay true if a tool fails, finds nothing, or
  needs the user's confirmation. The reply after the tools is more likely to
  continue from them instead of repeating or contradicting them. Agents that
  set their own `fillers.instructions` keep their wording.

### Documentation

* [#7557](https://github.com/RasaHQ/rasa-private/pull/7557): The Anthropic
  `integrations.yml` example recommends `claude-sonnet-4-6`.

***

**3.22.0.dev1**

2026-10-22

### Features

* [#7539](https://github.com/RasaHQ/rasa-private/pull/7539): Project memory
  fields can opt into mid-session updates with `mutable: true` and restrict
  which skills may write them with `writable_by`.
* [#7483](https://github.com/RasaHQ/rasa-private/pull/7483): A `modify_tool_call` hook can attach `metadata` sent only as MCP `_meta` on that call (not in tool arguments or model history). When tool-call hooks run, preflight rejects duplicate tool-call ids in one batch. When an MCP tool requires confirmation, that metadata is stored on `system.pending_tool_confirmation` and replayed on resume. The write stays in tracker history after the slot is cleared, so do not put secrets in `metadata`.
* [#7552](https://github.com/RasaHQ/rasa-private/pull/7552): Ordered blocks
  can record a decided human handoff with `execute_tool: record_handoff`.
  Studio analytics use that call for containment and escalation, and the model
  is never offered the tool.

### Improvements

* [#7565](https://github.com/RasaHQ/rasa-private/pull/7565): Scenarios can now set an optional `type` to label the kind of case they cover, such as `happy_path`, `edge_case`, or `escalation`.
* [#7581](https://github.com/RasaHQ/rasa-private/pull/7581): A Copilot build
  from an approved plan now survives a page reload and a service restart.
  Studio can follow the build again, and a build that a restart stopped ends
  as built or failed instead of staying in progress. Approving a plan twice
  starts only one build.
* [#7590](https://github.com/RasaHQ/rasa-private/pull/7590): The builder service's `GET /api/eval/scenarios` now returns each scenario's parsed fields (`type`, `simulation_context`, `criteria`, `initial_slots`, `assertions`, and `expected_tools`) alongside its raw contents.
* [#7606](https://github.com/RasaHQ/rasa-private/pull/7606): Copilot keeps
  each plan in the conversation that made it, so other users never see or
  change it. A Copilot chat can no longer change an agent while a build runs,
  and approving a plan never replaces an agent that already exists.

### Bugfixes

* [#7550](https://github.com/RasaHQ/rasa-private/pull/7550): When a user repeats
  a request for a skill that is waiting on an open question and the agent answers
  in its own words, it now follows that reply with the authored question and its
  buttons instead of leaving the question unasked.

**3.21.0**

2026-10-20

> [!NOTE]
>
> **First official open beta.** Rasa Pro 3.21.0 is the first official open beta
> release of Mantle. Start a project with `rasa init --engine mantle`, then follow
> the [getting started](https://rasa.com/docs/mantle/getting-started.md) guide.

### Features

* [#7536](https://github.com/RasaHQ/rasa-private/pull/7536): Mantle CLI commands
  accept `--integrations` to load runtime configuration from a file outside the
  project root.

### Bugfixes

* [#7461](https://github.com/RasaHQ/rasa-private/pull/7461): A rephrased reply from a Mantle assistant called over A2A is no longer stored only as token artifacts. Non-streaming callers receive one agent message per utterance and no token artifacts. Streaming callers still receive the tokens, and each finished utterance is also a history message whose metadata `streamed_artifact_id` names that artifact. An interrupted stream is not stored as a finished message.
* [#7537](https://github.com/RasaHQ/rasa-private/pull/7537): The message that
  pauses a task for a side question can no longer also answer whether to resume
  it. The agent asks whether to continue instead.

**3.21.0.dev12**

2026-10-20

### Breaking Changes

* [#7521](https://github.com/RasaHQ/rasa-private/pull/7521): Use
  `name: deepgram_flux` for Flux ASR configurations. `name: deepgram` now
  selects Nova, so update existing Flux configurations before upgrading.

### Improvements

* [#7450](https://github.com/RasaHQ/rasa-private/pull/7450): The voice backchannel detection model is now downloaded from the Rasa CDN instead of Hugging Face.
* [#7494](https://github.com/RasaHQ/rasa-private/pull/7494): Voice agents now mistake fewer real interruptions for backchannels like "uh-huh", so callers who cut in are heard more reliably.
  The default [`backchannel_threshold`](https://rasa.com/docs/mantle/reference/integrations-yml) is now `0.7`. If you set it explicitly, re-check your value.

### Bugfixes

* [#7553](https://github.com/RasaHQ/rasa-private/pull/7553): Starting a conversation with `/session_start` (for example from Inspector) no longer routes the trigger as user input, so the bundled `default_session_start` skill runs without an agent message before the customer speaks. A project override of that skill that includes an utterance step can still speak on bootstrap. Inspector no longer shows the typing indicator after a silent bootstrap.
* [#7453](https://github.com/RasaHQ/rasa-private/pull/7453): A short "thank you" while the agent is still waiting for an answer no longer ends the active skill or gets a silent reply; the agent asks its question again.
* [#7521](https://github.com/RasaHQ/rasa-private/pull/7521): Deepgram Flux no
  longer loses an utterance's final transcript when it differs from the last
  partial transcript.
* [#7526](https://github.com/RasaHQ/rasa-private/pull/7526): Mantle agents
  without privacy configuration publish conversation events to Conversation
  Review again.
* [#7546](https://github.com/RasaHQ/rasa-private/pull/7546): When a user asks
  for a skill that has to wait for a question the running skill is still
  asking, the agent repeats that question with its buttons instead of
  rewording it, declining, or filling in an answer the user never gave.
* [#7549](https://github.com/RasaHQ/rasa-private/pull/7549): When the agent
  declines an off-topic request while a skill is waiting on a question, it
  repeats that question with its buttons right after the decline instead of
  rewording it or filling in an answer the user never gave.

**3.21.0.dev11**

2026-10-15

### Features

* [#7510](https://github.com/RasaHQ/rasa-private/pull/7510): Voice channels can
  use ElevenLabs for speech recognition with Scribe v2 Realtime and speech
  synthesis with Eleven Multilingual v2, including word-level timestamps.
  Speech synthesis requires a voice ID configured for each language.
* [#7475](https://github.com/RasaHQ/rasa-private/pull/7475): Voice agents can play
  ambient background audio, such as office noise, during calls. Add a
  `background_audio` block to a voice channel in `integrations.yml` to set the
  volume or use your own audio file.

### Improvements

* [#7492](https://github.com/RasaHQ/rasa-private/pull/7492): Voice channels can
  set the pause between consecutive agent messages with
  `pause_between_messages` in `integrations.yml`. The default stays at 1
  second, and `0` adds no pause.
* [#7490](https://github.com/RasaHQ/rasa-private/pull/7490): Voice channels now
  wait 0.8 seconds after a filler before the next message. Set
  `pause_after_filler` on the channel in `integrations.yml` to change it, or
  set it to `0` for no pause.

### Bugfixes

* [#7509](https://github.com/RasaHQ/rasa-private/pull/7509): Twilio Media Streams can now use a custom sender ID to select an existing conversation while keeping call audio and playback controls working.
* [#7500](https://github.com/RasaHQ/rasa-private/pull/7500): The `recordings` configuration no longer accepts unknown or misspelled keys. `provider` is required when recordings are enabled, and `s3` is no longer the default provider.

**3.21.0.dev10**

2026-10-12

### Breaking Changes

* [#7425](https://github.com/RasaHQ/rasa-private/pull/7425): An `endpoints.yml` file at the project root fails startup, and passing `--endpoints` fails too.
  Mantle only accepts `integrations.yml`. Delete `endpoints.yml`. The silence timeout belongs in `agent.yml` as `voice.silence_timeout`.
  Call recordings are read only from `integrations.yml`. Move a `recordings:` block to [`recordings:`](https://rasa.com/docs/mantle/reference/integrations-yml#recordings) before upgrading. Omit it to leave recording off.
  Studio trains and runs a Mantle assistant without `--endpoints`, so those launches succeed.
  An `endpoints.yml` in another working directory is not this project's file and does not fail startup.

### Features

* [#7428](https://github.com/RasaHQ/rasa-private/pull/7428): Copilot now searches the Rasa docs and answers Mantle questions from the Mantle docs without extra configuration, because the `rasa-pro` package and the `rasa/rasa-pro` Docker image include both documentation indexes.

### Improvements

* [#7446](https://github.com/RasaHQ/rasa-private/pull/7446): Copilot for Mantle agents now refers to Rasa Studio instead of Hello Rasa, answers how-to questions with the agent's own skills, memory, and responses, and offers to make the change.
* [#7392](https://github.com/RasaHQ/rasa-private/pull/7392): `rasa tools init` now
  sets up Mantle projects: it detects them, downloads the Mantle documentation,
  and offers to install the Mantle agent skills. Use `--engine mantle` to choose
  Mantle explicitly. For Mantle projects, the Rasa MCP server no longer describes
  CALM-only tools it does not offer, and `train_rasa_assistant` also works when
  your IDE starts the server outside the project folder.
* [#7320](https://github.com/RasaHQ/rasa-private/pull/7320): Voice now uses word-level timestamps as intermediate markers.
  On barge-in LLM is now aware of the playback state based on the last acknowledged marker. This is available for selected TTS channels: Cartesia, Rime and Azure.

### Bugfixes

* [#7447](https://github.com/RasaHQ/rasa-private/pull/7447): After a digression that finishes or answers a knowledge question in the same turn, the agent now asks whether to resume the paused task instead of sometimes dropping it without asking.
* [#7443](https://github.com/RasaHQ/rasa-private/pull/7443): The model answers from relevant tool results before it finishes a skill, so a lookup is not replaced by the wrap-up question.
* [#7423](https://github.com/RasaHQ/rasa-private/pull/7423): When a turn hits the orchestration iteration limit, the agent now speaks `utter_model_call_error` instead of staying silent. Set `metadata.rephrase: true` on your override to have it reworded.
* [#7417](https://github.com/RasaHQ/rasa-private/pull/7417): `rasa train` validation logs, the error for a removed collect `tool:` key, and the text returned when a write is rejected now refer to `run_after_setting_<entry>` tools as memory validation tools.

### Documentation

* [#7445](https://github.com/RasaHQ/rasa-private/pull/7445): Docs for `ActivateSkill` now say a blocks-only skill starts at its entry block, and that a confirmation in the same response holds every handoff until the user answers.

**3.21.0.dev9**

2026-10-08

### Breaking Changes

* [#7409](https://github.com/RasaHQ/rasa-private/pull/7409): Omitting `skill_retrieval` leaves retrieval off, so the full routing catalogue stays and turns do not call the embedder. Set `active: true` to opt in. Retrieval then runs only when there are more startable skills than `num_skills` (at least 1). A smaller catalogue is not indexed or embedded, and train logs a warning with both counts.
* [#7398](https://github.com/RasaHQ/rasa-private/pull/7398): Answering from documents, the pre-tool line, and channel style move in
  `agent.yml`. Use `knowledge_answering` (including `instructions` and `top_k`),
  `fillers`, and `orchestrator.text_rules` / `orchestrator.voice_rules`. A skill
  sets `knowledge_answering.instructions` in its frontmatter. `prompts` stays
  for `routing_no_active_skill`. Filler and channel-style keys belong on
  `fillers` and `orchestrator`. Omitting the new keys keeps the previous
  behavior, including four chunks and voice-on, text-off fillers. Retrain
  after you move the keys.
* [#7369](https://github.com/RasaHQ/rasa-private/pull/7369): Fully guided skills start with `activate` and the skill id. Routing and topic change list that skill id and the skill description. An ordered block no longer has a `description`; training fails if one is still set. A fully guided skill has one entry block, and other blocks are reached with `call:` or `link:`.
* [#7369](https://github.com/RasaHQ/rasa-private/pull/7369): Silence hangup is its own skill, `default_silence_timeout_hangup`. `default_silence_timeout` only checks in. An override of `default_silence_timeout` that still contains the hangup block fails training.
* [#7380](https://github.com/RasaHQ/rasa-private/pull/7380): `rasa train` rejects a `description` on a memory field the model cannot set, including project fields and bundled default skills. Keep a description only on a field marked `llm_settable` or filled by a collect step. Remove it from every other field.
* [#7301](https://github.com/RasaHQ/rasa-private/pull/7301): Lifecycle tools are now `complete` and `cancel` instead of `complete_skill` and `cancel_skill`. Update skill prose that tells the model to call the old names, and rename `orchestrator.tool_constraints` keys from `complete_skill` and `cancel_skill` to `complete` and `cancel`. A custom `@tool` cannot be named `complete` or `cancel`.
* [#7372](https://github.com/RasaHQ/rasa-private/pull/7372): `rasa train` now
  rejects unknown top-level keys in `integrations.yml`. CALM-only keys (`nlg`,
  `nlu`, `action_endpoint`, `vector_store`, `interaction_handling`) were
  silently ignored before; each error names what to use instead. A
  `recordings:` section logs a warning, since it still belongs in
  `endpoints.yml`. See [Keys this file does not accept](https://rasa.com/docs/mantle/reference/integrations-yml.md#keys-this-file-does-not-accept).
* [#7337](https://github.com/RasaHQ/rasa-private/pull/7337): Training rejects a memory field the model can set when it has no description. Put the description on the memory field or on the collect step that fills it. When both are set, training warns and the collect-step description is the one shown to the model.

### Features

* [#7370](https://github.com/RasaHQ/rasa-private/pull/7370): You can
  mark memory fields `pii: true` and set an `anonymization` method on that
  field. `agent.yml` `privacy` holds tracker-store cron settings only.
  Published events are anonymized when `integrations.yml` sets
  `stream_pii: false`. Optional GLiNER-based detection (when the `pii` install
  extra and model are available) masks additional entities in user and bot
  message text.

* [#7363](https://github.com/RasaHQ/rasa-private/pull/7363): You can set `orchestrator.tool_constraints` in `agent.yml` to turn off `cancel`, `complete`, `search_knowledge`, or `cannot_help`, and to replace a built-in tool's when-to-call guidance with `invoke_when`. Omitting the section keeps today's prompt and offer rules. A retrain is required to pick up `tool_constraints` from `agent.yml`.

* [#7365](https://github.com/RasaHQ/rasa-private/pull/7365): A top-level [`a2a_server`](https://rasa.com/docs/mantle/reference/integrations-yml#a2a_server) block in `integrations.yml` configures the inbound A2A server. It accepts `include_default_skills`, `a2a_message_cache_ttl_seconds`, and the push notification keys; `${ENV_VAR}` references are expanded, unknown keys (including `enabled`) and a literal JWT `secret` are rejected, and `channels.a2a` is not an input channel. With the block present, `session_config` in `agent.yml` must set `start_session_after_expiry: false`. When `push_notifications_enabled` is true, task updates are posted to callback URLs and the AgentCard advertises them.

* [#7403](https://github.com/RasaHQ/rasa-private/pull/7403): A Mantle assistant called over A2A reports a finished skill as completed together with that skill's public memory, stays on input required while a skill or a tool confirmation is still open, and rejects a decline that leaves nothing else to do. Button titles travel on the working update. Cancelling the task marks the skill cancelled.

* [#7376](https://github.com/RasaHQ/rasa-private/pull/7376): The inbound A2A AgentCard is generated from the skill catalog and named with `agent.id` from `agent.yml`. Routable skills are advertised with their `skill.md` name and description; `engine_managed`, `disabled`, and `hidden` skills stay off the card, and a default skill appears only when [`include_default_skills`](https://rasa.com/docs/mantle/reference/integrations-yml#a2a_server) is `true` and a project override made it routable. A static `agent_card_path` must be A2A 1.0 JSON with `supportedInterfaces`. The card is generated when the model loads at startup.

* [#7381](https://github.com/RasaHQ/rasa-private/pull/7381): `PUT /model` and `DELETE /model` on the Rasa HTTP API point the inbound A2A server at the swapped model and rebuild the AgentCard. The response waits until a turn already in progress finishes on the model it started with, and that model is retired only after the turn finishes. `DELETE /model` publishes a card with no generated skills. A model that fails the A2A engine or session check is rejected and the current model stays loaded. `PUT /model` of a model trained for the other engine fails the same way, so a running CALM server is not migrated to Mantle through these endpoints; restart `rasa run` with the retrained model.

* [#7385](https://github.com/RasaHQ/rasa-private/pull/7385): You can require confirmation before `cancel` runs by setting
  `orchestrator.tool_constraints.cancel.requires_confirmation` in
  `agent.yml`. If the user confirms, the skill is cancelled as it is today; if they
  decline, the skill stays in place. Omitting the setting keeps immediate cancel. See
  [`tool_constraints`](https://rasa.com/docs/mantle/reference/agent-yml#tool_constraints).

### Improvements

* [#7393](https://github.com/RasaHQ/rasa-private/pull/7393): Coding agents that simulate a Mantle conversation write scenarios with the current checks and wait for you to choose a fix when an evaluation fails.
* [#7308](https://github.com/RasaHQ/rasa-private/pull/7308): The system prompt no longer includes the skills glossary.
* [#7388](https://github.com/RasaHQ/rasa-private/pull/7388): Coding agents that author skills now apply the decision rules for when a sentence in the skill body is not enough.
* [#7344](https://github.com/RasaHQ/rasa-private/pull/7344): On a voice call, during a
  collect step, the agent waits silently when the user has started answering but not
  finished (for example, halfway through a card number) instead of talking over them.

### Bugfixes

* [#7407](https://github.com/RasaHQ/rasa-private/pull/7407): When loading a trained model fails, the error log names the underlying problem and refers to the model as Mantle. Training logs that the Mantle model package was saved.
* [#7405](https://github.com/RasaHQ/rasa-private/pull/7405): `rasa run` and `rasa inspect` load channels, endpoints, and the secrets manager from `integrations.yml` in the project directory when `--model` is a Mantle archive, even with no `skills/` folder beside it. Tracker, lock, and timer values that remain only in `endpoints.yml` fall back to memory, and an event broker or model server left only there is ignored, so move those blocks into `integrations.yml` before serving this way. If the archive cannot be read as Mantle, those commands keep `credentials.yml` and `endpoints.yml` and log a warning.
* [#7386](https://github.com/RasaHQ/rasa-private/pull/7386): `rasa init --engine mantle`
  registers the rasa-tools MCP server for Claude Code and Cursor, so
  simulation and evaluation no longer require a separate setup step.
* [#7366](https://github.com/RasaHQ/rasa-private/pull/7366): On voice, the silence
  timeout now also starts after a turn where the agent waits with `listen`, so a caller
  who stays quiet gets the silence check-in instead of dead air.
* [#7360](https://github.com/RasaHQ/rasa-private/pull/7360): A button that stores a memory value now counts as the user's answer, so the agent continues the conversation instead of treating the question as unanswered.

### Documentation

* [#7370](https://github.com/RasaHQ/rasa-private/pull/7370): Documented
  `privacy` in [`agent.yml`](https://rasa.com/docs/mantle/reference/agent-yml#privacy) and the Mantle PII
  pipeline in [`memory.yml`](https://rasa.com/docs/mantle/reference/memory-yml). The
  `mantle_privacy_e2e` agent in
  [maestro-benchmarking-agents](https://github.com/RasaHQ/maestro-benchmarking-agents)
  includes local Kafka and GLiNER verification steps.

* [#7363](https://github.com/RasaHQ/rasa-private/pull/7363): The tools reference defines each built-in tool, including what it does and when the model is offered it.

**3.21.0.dev8**

2026-10-06

### Breaking Changes

* [#7361](https://github.com/RasaHQ/rasa-private/pull/7361): The tracker store, lock store, and secrets manager are read only from
  `integrations.yml`. `tracker_store:`, `lock_store:`, and `secrets_manager:`
  blocks in `endpoints.yml` are ignored, and startup logs a warning. Move
  them to
  [`tracker_store:`](https://rasa.com/docs/mantle/reference/integrations-yml#tracker_store),
  [`lock_store:`](https://rasa.com/docs/mantle/reference/integrations-yml#lock_store), and
  [`secrets_manager:`](https://rasa.com/docs/mantle/reference/integrations-yml#secrets_manager)
  before upgrading. A `tracker_store:` block left only in `endpoints.yml`
  stores conversations in memory, so they are lost when the process restarts.

* [#7296](https://github.com/RasaHQ/rasa-private/pull/7296): The event
  broker, timer store, and remote model server are read only from
  `integrations.yml`. `event_broker:`, `timer_store:`, and `models:`
  blocks in `endpoints.yml` are now ignored, and startup logs a warning.
  Move them to
  [`event_broker:`](https://rasa.com/docs/mantle/reference/integrations-yml#event_broker),
  [`timer_store:`](https://rasa.com/docs/mantle/reference/integrations-yml#timer_store), and
  [`rasa_model_server:`](https://rasa.com/docs/mantle/reference/integrations-yml#rasa_model_server)
  in `integrations.yml`.

* [#7289](https://github.com/RasaHQ/rasa-private/pull/7289): The orchestrator model group is named with `orchestrator.model_group` in `agent.yml`. Optional `orchestrator.max_prompt_tokens` defaults to 8000. `integrations.yml` must not contain an `llm:` section; define the group under `model_groups`. Existing projects need that name added and a retrain.

* [#7217](https://github.com/RasaHQ/rasa-private/pull/7217): Unknown top-level keys in `skill.md` frontmatter are rejected at train. Remove the extra key.

### Features

* [#7286](https://github.com/RasaHQ/rasa-private/pull/7286): Tools can stream a message to the user and attach buttons to a message they send.

* [#7361](https://github.com/RasaHQ/rasa-private/pull/7361): You can configure the tracker store, lock store, and Vault secrets manager
  in `integrations.yml`. `VAULT_URL`, `VAULT_TOKEN`, and
  `VAULT_RASA_SECRETS_PATH` still override `secrets_manager:` and still work
  when that section is omitted. See
  [Tracker store](https://rasa.com/docs/mantle/reference/integrations-yml.md#tracker_store),
  [Lock store](https://rasa.com/docs/mantle/reference/integrations-yml.md#lock_store), and
  [Secrets manager](https://rasa.com/docs/mantle/reference/integrations-yml.md#secrets_manager).

* [#7296](https://github.com/RasaHQ/rasa-private/pull/7296): You can
  configure the event broker, timer store, and remote model server under
  `integrations.yml` instead of `endpoints.yml`. Use
  `rasa_model_server:` for the remote model server, not the `models` list
  inside a model group. With no local model, `rasa run` points at
  `integrations.yml`. See
  [Event broker](https://rasa.com/docs/mantle/reference/integrations-yml.md#event_broker),
  [Timer store](https://rasa.com/docs/mantle/reference/integrations-yml.md#timer_store), and
  [Remote model server](https://rasa.com/docs/mantle/reference/integrations-yml.md#rasa_model_server).

* [#7224](https://github.com/RasaHQ/rasa-private/pull/7224): A tool can now hand
  off to another skill by returning `ToolResult(next=[ActivateSkill(skill_id=...)])`.
  The skill activates after the tool's result is recorded, following the same
  rules as the LLM's `activate` tool. See
  [`ActivateSkill`](https://rasa.com/docs/mantle/reference/tools#activateskill).

* [#7217](https://github.com/RasaHQ/rasa-private/pull/7217): JSON Schema for Mantle authoring files is published under Reference → Schemas, generated from the models that load those files, including skill frontmatter and preconditions.

### Improvements

* [#7375](https://github.com/RasaHQ/rasa-private/pull/7375): Voice calls that use Deepgram speech recognition now include the Deepgram request ID in the metadata of each user message (`metadata.asr.request_id`), so you can match a conversation to Deepgram's own logs when debugging transcription issues with Deepgram support. If you subclass `VoiceInputChannel` and override `handle_asr_event`, add the new optional `asr_metadata` keyword argument to your override.

* [#7335](https://github.com/RasaHQ/rasa-private/pull/7335): Voice agents now
  keep work already underway when a user speaks over a response, then respond
  to their latest input once that work finishes.

* [#7354](https://github.com/RasaHQ/rasa-private/pull/7354): A missing model group named by `references.embeddings` or `orchestrator.model_group` now reports that id. The `references.embeddings` error says to clear the field to use the built-in OpenAI embedder. A missing orchestrator group stops the server instead of starting with no model loaded.

* [#7336](https://github.com/RasaHQ/rasa-private/pull/7336): Turns no longer wait on an extra model call after a skill switch to store facts the conversation does not use.

* [#7145](https://github.com/RasaHQ/rasa-private/pull/7145): `on_model_request` /
  `modify_model_request` and `on_model_response` / `modify_model_response` also
  run on rephrase, confirm-rephrase, and the post-activate `set_fields` fill.
  A request-hook crash does not send that prompt. `RetryModel` on those calls
  discards the completion instead of starting another main-loop iteration.

* [#7227](https://github.com/RasaHQ/rasa-private/pull/7227): `rasa export` publishes Mantle ProtoJSON when `--integrations` points at an existing integrations file (default `integrations.yml`). Classic projects keep flat events.

* [#7257](https://github.com/RasaHQ/rasa-private/pull/7257): Training or validating a Mantle project that has no skills reports that no `skills/<id>/skill.md` files were found.

* [#7284](https://github.com/RasaHQ/rasa-private/pull/7284): When training fails on a
  Mantle project, Copilot's analysis now searches the Mantle documentation, as Copilot
  chat already does.

* [#7292](https://github.com/RasaHQ/rasa-private/pull/7292): Mantle trackers now
  record skill, block, and memory changes only as `skill_*`, `ordered_block_*`,
  `memory_set`, and `memory_cleared` events; the classic `flow_*` and `slot_set`
  copies are no longer written. Conversations recorded with those copies still
  load.

### Bugfixes

* [#7361](https://github.com/RasaHQ/rasa-private/pull/7361): Sanic workers now load the secrets manager. A Vault-backed tracker store
  works with more than one worker for Mantle and for classic projects.
* [#7250](https://github.com/RasaHQ/rasa-private/pull/7250): Resuming an older
  paused skill with `activate` pauses the task in progress and keeps newer
  paused tasks on the stack. Returning to that skill or to its block also
  keeps an earlier block of that skill that was parked by a block switch, and
  finishing the resumed block continues that earlier block. When the resumed
  task finishes, the user is offered to continue the nearest paused task.
* [#7145](https://github.com/RasaHQ/rasa-private/pull/7145): When activating a
  skill lands on an ordered block that would immediately wait for the user, a
  collect or settable memory value already stated in that same message is
  recorded before the skill asks for it again.

### Documentation

* [#7355](https://github.com/RasaHQ/rasa-private/pull/7355): Mantle docs now explain how to simulate and evaluate an agent, including the assertion keys a Mantle scenario can use.
* [#7275](https://github.com/RasaHQ/rasa-private/pull/7275): A best-practices page covers what to put in memory, responses, constraints, and ordered blocks when a sentence in the skill body is not enough.
* [#7272](https://github.com/RasaHQ/rasa-private/pull/7272): Skill-writing guidance now says when to name another skill with `@skill.<id>` so a related request stays part of the current task, and when to leave a topic change alone.
* [#7364](https://github.com/RasaHQ/rasa-private/pull/7364): A new Voice section covers how Mantle runs skills in a voice conversation, a build-a-voice-agent tutorial, designing for voice, connecting a phone line, and testing and monitoring. Getting Started now lets you talk to your agent in the Inspector. The reference gains Speech providers and Custom speech providers pages, documents `language_map`, `interruptions`, and `silence_timeout` for voice channels, and documents keypad input with `dtmf:` on a collect step and the `user_input_suppressed` event.

### Deprecations and Removals

* [#7284](https://github.com/RasaHQ/rasa-private/pull/7284): `rasa tools run` no longer
  offers the `search_rasa_documentation` tool, which searched the CALM docs. Your coding
  agent reads the Mantle docs in `.rasa/docs/mantle/` through the `mantle-docs` skill; add
  them to an existing project with `rasa tools init docs mantle`.

**3.21.0.dev7**

2026-10-01

### Breaking Changes

* [#7242](https://github.com/RasaHQ/rasa-private/pull/7242): Tracing and
  metrics are read only from `integrations.yml`. `tracing:` (including
  Langfuse) and `metrics:` blocks in `endpoints.yml` are now ignored, and
  startup logs a warning. Move them to
  [`tracing:`](https://rasa.com/docs/mantle/reference/integrations-yml#tracing) and
  [`metrics:`](https://rasa.com/docs/mantle/reference/integrations-yml#metrics) in `integrations.yml`.

### Features

* [#7242](https://github.com/RasaHQ/rasa-private/pull/7242): You can configure
  OpenTelemetry tracing (`otlp` or `jaeger`) and OTLP metrics under
  `integrations.yml` instead of `endpoints.yml`. List Langfuse and an OTLP or
  Jaeger tracer together under `tracing:` to use both. A Jaeger entry with
  `username`/`password` must set `insecure` (`false` exports over TLS). See
  [Tracing](https://rasa.com/docs/mantle/reference/integrations-yml.md#tracing) and
  [Metrics](https://rasa.com/docs/mantle/reference/integrations-yml.md#metrics).

**3.21.0.dev6**

2026-09-30

### Breaking Changes

* [#7156](https://github.com/RasaHQ/rasa-private/pull/7156): Models trained before skill retrieval that still have independently startable skills must be retrained before they will load (or set `skill_retrieval.active: false`). Omitting `skill_retrieval` leaves retrieval on.
* [#7189](https://github.com/RasaHQ/rasa-private/pull/7189): `rasa train` requires a non-empty skill `description`, rejects unknown `skill.md` frontmatter keys and non-string `name`/`description`, and fails on incomplete `@skill` / `@block` / `@tool` tokens. Bundled default skills are checked the same way. See [`skill.md`](https://rasa.com/docs/mantle/reference/skill-md).

### Features

* [#7156](https://github.com/RasaHQ/rasa-private/pull/7156): Mantle agents can now retrieve a subset of independently startable skills for routing. `skill_retrieval` is on by default; set `active: false` to keep the full routing catalogue.
* [#7157](https://github.com/RasaHQ/rasa-private/pull/7157): Skill retrieval can pin skills with `always_include_in_prompt` and keep recently started skills in the routing catalogue. A search outage fails the turn instead of listing every skill. This is not knowledge search (`search_knowledge`).
* [#7282](https://github.com/RasaHQ/rasa-private/pull/7282): A collect step can accept keypad input via `dtmf`, using `length` or `finish_on_key`. Set `allow_audio_input: false` to ignore speech while digits are expected.

### Improvements

* [#7223](https://github.com/RasaHQ/rasa-private/pull/7223): Inspector NextGen
  now shows Mantle conversation events in nested ProtoJSON form while still
  accepting classic flat event JSON. Mantle inspect tracker dumps and downloaded
  logs preserve the ProtoJSON envelopes for replay.

### Bugfixes

* [#7268](https://github.com/RasaHQ/rasa-private/pull/7268): The first message of a new conversation no longer activates a skill before that message is visible.
* [#7183](https://github.com/RasaHQ/rasa-private/pull/7183): Skills can import an MCP tool when an unused shared tool has the same name without causing model loading to fail, including when that MCP tool is gated with `tool_constraints` or ordered-block `tools`.

### Documentation

* [#7260](https://github.com/RasaHQ/rasa-private/pull/7260): Builders can look up Mantle's default skills and the wording of the built-in messages.
* [#7262](https://github.com/RasaHQ/rasa-private/pull/7262): Docs call `run_after_setting_<entry>` tools memory validation tools.

### Deprecations and Removals

* [#7260](https://github.com/RasaHQ/rasa-private/pull/7260): The unused default response `utter_ask_how_to_help` is removed. Completed still asks with `utter_ask_wants_to_continue`.

**3.21.0.dev5**

2026-09-29

### Improvements

* [ENG-3360](https://rasahq.atlassian.net/browse/ENG-3360): When
  `modify_model_request` or `modify_tool_call` crashes or times out, or the
  main model call fails, the user hears `utter_model_request_hook_error`,
  `utter_tool_call_hook_error`, or `utter_model_call_error` instead of
  silence. Override those names in `responses.yml`. The exception text is not
  spoken, and `rephrase` on those responses is ignored.

**3.21.0.dev4**

2026-09-29

**3.21.0.dev3**

2026-09-28

### Bugfixes

* [#7225](https://github.com/RasaHQ/rasa-private/pull/7225): The `hangup` tool is
  now offered only when an ordered block explicitly uses `action: hangup`, so it
  is not selected in other contexts.

**3.21.0.dev2**

2026-09-28

### Breaking Changes

* [#7185](https://github.com/RasaHQ/rasa-private/pull/7185): Mantle model
  credentials must use `api_key: ${ENV_VAR_NAME}` (and the same `${…}` form for
  other sensitive model keys). Literal secrets are rejected. See
  [Secrets](https://rasa.com/docs/mantle/reference/integrations-yml.md#secrets).

* [#7104](https://github.com/RasaHQ/rasa-private/pull/7104): Skill-level `requires` is rejected at train. Use `precondition` plus `agent.yml` `orchestrator.preconditions` to run a resolver first, or `hidden: true` to omit a skill from routing. Tool-level `requires` under `tool_constraints` is unchanged. See [`precondition`](https://rasa.com/docs/mantle/reference/skill-md#precondition), [`preconditions`](https://rasa.com/docs/mantle/reference/agent-yml#preconditions), and [`hidden`](https://rasa.com/docs/mantle/reference/skill-md#hidden).

* [#7056](https://github.com/RasaHQ/rasa-private/pull/7056): Mantle tracker
  persistence and the event broker now use nested ProtoJSON for conversation
  events instead of flat `"event"` JSON. Classic (non-Mantle) projects are
  unchanged. See [Conversation events](https://rasa.com/docs/mantle/reference/events.md).

* [#7170](https://github.com/RasaHQ/rasa-private/pull/7170): The default voice
  silence timeout is now 30 seconds (was 7). Set `silence_timeout` on the voice
  channel in `integrations.yml` if you need a different wait.

### Features

* [#7104](https://github.com/RasaHQ/rasa-private/pull/7104): Skills can declare a semantic `precondition`, and projects bind it in `agent.yml` `orchestrator.preconditions` so the engine parks the consumer, runs a resolver skill, then continues or abandons the request without hiding the skill from routing. If the resolver is already the active skill, the consumer is parked under that run instead of interrupting it. Skills can also set `hidden: true` to stay off the routing catalogue while remaining startable via `call`, `link` or `resolve_with`; prose `@skill` mentions of a hidden skill fail validation. Inspector labels a parked consumer as pending while the resolver is the active skill.

* [#7035](https://github.com/RasaHQ/rasa-private/pull/7035): `on_incoming_message` /
  `modify_incoming_message` now run on final user text before it is stored.
  Modified text is what gets stored and what the turn runs on. Rejected
  text and fail-closed hook errors stay on the tracker as discarded, are
  omitted from model and completion-judge history, skip the user-message
  orchestrator turn, and are answered with response templates:
  `HookRejection.response_message`
  may select a bot-defined response, while failures use
  `utter_incoming_message_rejected`. When that first payload also opens a
  session, `default_session_start` still runs so session-start memory writes
  apply, and named reject replies are resolved after that turn. See [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#7107](https://github.com/RasaHQ/rasa-private/pull/7107):
  `on_outgoing_text` / `modify_outgoing_text` now run once on each completed
  agent utterance, including fillers. Modified text is stored and sent;
  rejected text is dropped without being stored and replaced with a response
  template (`HookRejection.response_message` or
  `utter_outgoing_text_rejected`), so the tracker only ever records what the
  user actually received.
  `modify_outgoing_text` buffers streamed output until the whole utterance
  passes the hook; observe-only hooks do not. Incoming-message rejection
  replies also pass these outgoing hooks. See [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#7187](https://github.com/RasaHQ/rasa-private/pull/7187): Train and validate fail when `skill.md` prose references `@tool.<name>` for a tool that does not exist or is not visible to that skill.

* [#7170](https://github.com/RasaHQ/rasa-private/pull/7170): After three silence-timeout check-ins,
  the next consecutive silence ends the call with a goodbye. A skill can do the same with an ordered-block
  `action: hangup` after an authored goodbye response.

### Improvements

* [#7105](https://github.com/RasaHQ/rasa-private/pull/7105): Mantle conversation
  events now include stable `event_id` and `sequence` fields so consumers can
  order and deduplicate reliably.
* [#7130](https://github.com/RasaHQ/rasa-private/pull/7130): Mantle ProtoJSON now
  covers the remaining conversation event types (session, voice, skills,
  ordered blocks, and related engine events).
* [#7159](https://github.com/RasaHQ/rasa-private/pull/7159): Voice channels now
  use a classifier and `backchannel_threshold` to distinguish short
  backchannels from interruptions, using the current agent utterance as
  context. Accepted interruptions enter the active turn, while ignored
  backchannels remain visible as `user_input_suppressed` events; the classifier
  loads at channel startup and downloads from Rasa's CDN if it is not cached.
  See [voice interruption settings](https://rasa.com/docs/mantle/reference/integrations-yml.md#interruptions).

### Bugfixes

* [#7162](https://github.com/RasaHQ/rasa-private/pull/7162): Paged collects can
  now clear a button choice and return to the same collect to show refreshed
  dynamic buttons without an explicit listen step or an LLM turn.
* [#7202](https://github.com/RasaHQ/rasa-private/pull/7202): Memory saved during
  a conversation stays available when the assistant uses Postgres, Redis, or
  another tracker store, so collect steps continue and tools see the values
  they require.
* [#7191](https://github.com/RasaHQ/rasa-private/pull/7191): Agents no longer receive
  `set_fields` prompt guidance when the tool is unavailable for the current turn.

### Documentation

* [#7130](https://github.com/RasaHQ/rasa-private/pull/7130): Documented Mantle
  conversation event ProtoJSON under [Conversation events](https://rasa.com/docs/mantle/reference/events.md),
  including the dual-write skip list and golden fixtures for consumers.
* [#7188](https://github.com/RasaHQ/rasa-private/pull/7188): Mantle documentation now uses Rasa's rebrand colors and typography for a consistent visual experience.

**3.21.0.dev1**

2026-09-24

### Breaking Changes

* [#7123](https://github.com/RasaHQ/rasa-private/pull/7123): The bundled
  `default_session_start` skill no longer greets. Override that skill and send
  `/session_start` when the agent should speak first. See
  [Start a conversation](https://rasa.com/docs/mantle/orchestration/runtime-loop.md#start-a-conversation).

### Features

* [#7025](https://github.com/RasaHQ/rasa-private/pull/7025): `on_turn_started` /
  `on_turn_finished` now run around each Mantle turn. Builders can observe
  turn start and the final `completed` / `cancelled` / `error` status without
  blocking the turn. See [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#7024](https://github.com/RasaHQ/rasa-private/pull/7024): `on_knowledge_query` /
  `modify_knowledge_query` and `on_knowledge_results` /
  `modify_knowledge_results` now run around `search_knowledge`. Builders can
  rewrite the query or filter/reorder retrieved passages; neither point accepts
  `HookRejection` or `RetryModel`. Query-hook crashes are fail-closed (search
  skipped); results-hook crashes are fail-open (original passages kept). See
  [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#6972](https://github.com/RasaHQ/rasa-private/pull/6972): Dynamic button source
  tools are engine-only and validated by `rasa train`; missing, MCP, and
  confirmation-gated sources are rejected, while invalid runtime button
  references are omitted without dropping valid siblings.

* [#6969](https://github.com/RasaHQ/rasa-private/pull/6969): A response variant can
  name a tool with `buttons: {source: <tool_name>}`, and that tool supplies the
  buttons for the message with `context.set_buttons([...])`. Buttons built with a
  `ref` write the chosen value to memory on tap, exactly like a static
  `set:session.<skill>.<entry>=<value>` button; the message is sent without buttons
  when the tool returns none or fails.

* [#6707](https://github.com/RasaHQ/rasa-private/pull/6707): The model can now wait for the next user message without sending a reply,
  by calling the reserved `listen` tool after a question already asked this
  turn. Guided collect steps, post-search answer calls, and pending tool
  confirmation do not offer this tool. Mixed `listen` plus text or other tools
  ignores `listen`.

* [#6760](https://github.com/RasaHQ/rasa-private/pull/6760): `on_model_request` /
  `modify_model_request` now run on each main LLM loop iteration. Builders can
  rewrite provider-bound messages and allowlisted per-call `model_settings`
  (`temperature`, `top_p`, `max_tokens`, `presence_penalty`, `frequency_penalty`,
  `stop`, `seed`). Empty-completion retries reuse that hooked request without
  re-running hooks. Credentials, provider/model, and tools stay engine-owned;
  this point has no intentional veto (`HookRejection` is not accepted). See
  [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#6771](https://github.com/RasaHQ/rasa-private/pull/6771): `on_model_response` /
  `modify_model_response` now run after each main LLM completion and before any
  user-visible emit or tool dispatch. Builders can rewrite response text and
  tool calls, or raise `RetryModel(feedback=...)` to discard the response and
  steer the next iteration with an engine-only system note. `HookRejection` is
  not accepted at this point; unexpected crashes, timeouts, or invalid returns
  are fail-open. A registered response modifier buffers the main completion
  (no live token stream) so rewrites and retries match what the user hears.
  See [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

* [#7023](https://github.com/RasaHQ/rasa-private/pull/7023): `on_tool_call` /
  `modify_tool_call` and `on_tool_result` / `modify_tool_result` now run on the
  LLM tool-call batch path. The engine prefights every proposed call before any
  tool runs; `RetryModel` discards the whole batch (including accompanying
  text) and steers the next iteration. A registered tool-call modifier buffers
  the main completion (no live token stream) so retries and fail-closed
  crashes cannot leak speech. Modified arguments reach dispatch; modified
  results are what `McpToolExecuted` / `ToolExecuted` store and the next prompt
  replays. `HookRejection` is not accepted on tool calls; tool results have no
  control signals. Confirmation resume, settable writes, and correction replay
  do not invoke these hooks. See [Hooks](https://rasa.com/docs/mantle/reference/hooks.md).

### Improvements

* [#6987](https://github.com/RasaHQ/rasa-private/pull/6987): Session-start
  channel metadata on Mantle conversations is now recorded as a `memory_set`
  event (with write provenance), so Studio and other consumers can read it
  without relying on a legacy `slot` event for that value.

* [#6895](https://github.com/RasaHQ/rasa-private/pull/6895): `context.memory.get`
  accepts an optional default. Unset, `None`, or unreadable fields return that
  fallback (`get("card_list", [])` is `[]`) instead of `None` or a `TypeError`.
  Local tool failures log `error_type` at ERROR and the exception message at DEBUG.

* [#6831](https://github.com/RasaHQ/rasa-private/pull/6831): Inspector bot-turn
  latency details now include time spent in earlier LLM calls, making multi-step
  and tool-driven responses easier to diagnose.

* [#6824](https://github.com/RasaHQ/rasa-private/pull/6824): `complete_skill` is
  offered when the active skill has prose instructions, including while a hybrid
  skill is in an ordered block. Ordered-block-only skills omit the tool and
  finish when the block ends; `cancel_skill` is still available.

* [#6773](https://github.com/RasaHQ/rasa-private/pull/6773): Voice conversations now
  process overlapping transcripts normally and preserve rejected barge-ins or audio
  blocked during DTMF collection in the new `user_input_suppressed` tracker event.

* [#7144](https://github.com/RasaHQ/rasa-private/pull/7144): Evaluation scenarios can
  now assert skill and ordered-block lifecycles, memory writes and clears, and tool runs,
  including several tools in one user turn, and can check those facts in order.
  Inspector downloads include these assertions. A Mantle run rejects `slot_was_set`,
  `slot_was_not_set`, `generative_response_is_relevant`, and
  `generative_response_is_grounded`. Use the memory assertions for written state.

### Bugfixes

* [#7346](https://github.com/RasaHQ/rasa-private/pull/7346): Deepgram Flux TTS
  now accepts the provider's full speed range and supports models that require
  the default speed setting.

* [#7161](https://github.com/RasaHQ/rasa-private/pull/7161): Hybrid skills no
  longer offer `complete_skill` while an ordered block is active, preventing
  repeated refused completion calls before the block finishes.

* [#7123](https://github.com/RasaHQ/rasa-private/pull/7123): When a new or
  expired session starts on a real user message, that message is now handled
  in the same request instead of being answered only after the next turn.

* [#7060](https://github.com/RasaHQ/rasa-private/pull/7060): `complete_skill` no longer
  intermittently refuses to complete a skill whose exit criteria were actually met,
  which could otherwise re-engage the caller with an unnecessary step after the
  conversation had already wrapped up.

* [#7057](https://github.com/RasaHQ/rasa-private/pull/7057): Copilot documentation
  search now finds pages on the current docs site and omits unpublished drafts.

* [#7052](https://github.com/RasaHQ/rasa-private/pull/7052): Mantle voice calls now keep
  processing spans in a single call trace, making individual calls easier to debug.

* [#6968](https://github.com/RasaHQ/rasa-private/pull/6968): Voice agents now
  release LLM requests as soon as response generation completes while speech
  continues in order and remains interruptible.

* [#6863](https://github.com/RasaHQ/rasa-private/pull/6863):
  `context.memory.set("project.<entry>", …)` and
  `context.memory.set("<active_skill>.<entry>", …)` now write the named field
  instead of failing as undeclared, matching how `get` already resolves those
  names. An own-skill qualified name does not fall through to project memory.
  Cross-skill writes stay rejected.

* [#6906](https://github.com/RasaHQ/rasa-private/pull/6906): Skills with
  `complete_when` criteria no longer refuse exit when an early path detail
  that exempts a requirement (for example a damaged-card reason) was pushed
  out of the completion check by multi-message bot replies.

* [#6826](https://github.com/RasaHQ/rasa-private/pull/6826): After a canned ordered-block
  reply, leftover hybrid prose can continue on the same turn instead of waiting
  for the next user message.

* [#6847](https://github.com/RasaHQ/rasa-private/pull/6847): Custom default
  skills now start from their configured entry and are discarded cleanly when
  the customer moves to another task.

* [#6846](https://github.com/RasaHQ/rasa-private/pull/6846): After a customer
  answers a tool confirmation, repeated same-turn LLM calls no longer ask for
  confirmation again; unanswered confirmations are still re-asked after a
  digression. A later ordered `execute_tool` step of the same tool can still
  ask again in that turn.

### Documentation

* [#7080](https://github.com/RasaHQ/rasa-private/pull/7080): New
  [Writing prose](https://rasa.com/docs/mantle/best-practices/writing-prose.md) page covers how to word a skill's
  `description` and body. Name the subject before the action in a description, and
  separate them with a dash, so routing matches on the thing being asked about.
* [#6850](https://github.com/RasaHQ/rasa-private/pull/6850): Skills that use
  `requires_confirmation` must not also ask for confirmation in prose — pick
  one mechanism so the customer is not prompted twice.
* [#6762](https://github.com/RasaHQ/rasa-private/pull/6762): Clarified hook
  control-flow semantics, including `RetryModel` feedback as a non-persisted
  system note, sequential multi-tool `modify_tool_call` preflight, discarded
  text handling, and unavailable audio hooks.

### Deprecations and Removals

* [#6912](https://github.com/RasaHQ/rasa-private/pull/6912): Skill
  `deny_read` / `deny_write` lists are removed. Memory visibility and writes
  follow public, private, and project scopes only. Leftover `access:` /
  `deny_read` / `deny_write` keys in skill `memory.yml` are ignored and are
  not enforced.

***

**3.20.0.dev9**

2026-09-08

### Breaking Changes

* [#6729](https://github.com/RasaHQ/rasa-private/pull/6729): Skill-level
  `complete_when` must be a mapping with `condition` and/or `criteria`
  (bare strings are rejected). Use it on skills that have prose instructions;
  ordered-block-only skills cannot declare it (they finish via block end
  without this gate). When authored, `complete_skill` is hard-gated on those
  requirements and is refused while an ordered block is active.
  See [skill.md](https://rasa.com/docs/mantle/reference/skill-md.md#complete_when).

### Features

* [#6783](https://github.com/RasaHQ/rasa-private/pull/6783): The live conversation
  stack now distinguishes skills from ordered blocks. Guided skills show the
  skill together with a `main` block. Inspector and Copilot display this stack
  shape. Pre-existing Mantle conversations that still use the previous
  flow-based live stack still load and replay, but are not upgraded in place —
  restart the conversation (including any in-flight Inspector session) before
  continuing under the new stack shape. Block-level `flow_*` events are still
  written as well.
* [#6732](https://github.com/RasaHQ/rasa-private/pull/6732): Mantle voice agents can now
  respond when a user remains silent for the configured timeout through the customizable
  `default_silence_timeout` skill. Silence timeouts and their configured duration are
  recorded in the conversation tracker and included in the agent's conversation context.
* [#6729](https://github.com/RasaHQ/rasa-private/pull/6729): Optional
  `complete_when.criteria` (sentences in natural language) are checked on
  `complete_skill`. The check **fails closed**: timeouts, errors, or malformed
  judge answers refuse completion (skill stays active) instead of treating the
  skill as done. With criteria present, condition-only auto-complete is disabled.

### Improvements

* [#6800](https://github.com/RasaHQ/rasa-private/pull/6800): Large FAQ files under `references/` now train without a manual split, and `search_knowledge` returns the matching section. Builders can set character chunk size and overlap under `references.chunking`.

### Bugfixes

* [#6729](https://github.com/RasaHQ/rasa-private/pull/6729): `complete_skill` is
  refused while a tool confirmation is pending for the active skill. Resolve or
  decline the confirmation first; `cancel_skill` still abandons the skill.
* [#6787](https://github.com/RasaHQ/rasa-private/pull/6787): When a user revises a
  value the agent already captured, a refused memory write is now reported as an
  error and the agent is told to use `correct` instead of silently keeping the
  old value.
* [#6759](https://github.com/RasaHQ/rasa-private/pull/6759): Invalid LLM-issued
  local and MCP tool calls now return a retryable result to the model instead of
  running the tool or sending its `on_failure` response. Ordered `execute_tool`
  steps with invalid arguments stay on the step without running the tool or
  `on_failure`.

**3.20.0.dev8**

2026-09-04

### Features

* [#6765](https://github.com/RasaHQ/rasa-private/pull/6765): Conversations now record ordered-block lifecycle
  (`ordered_block_entered` / `completed` / `cancelled` / `interrupted` /
  `resumed`). Block-level `flow_*` events are still written as well. Inspector and
  Copilot map these types. See
  [Tracker events](https://rasa.com/docs/mantle/reference/execution-loop.md#tracker-events).
* [#6699](https://github.com/RasaHQ/rasa-private/pull/6699): Tapping a button whose
  `payload` is a [`set:` memory reference](https://rasa.com/docs/mantle/reference/responses-yml#set-memory-payloads) now writes the declared memory field directly,
  without an LLM `set_fields` call (`llm_settable` is not required). Memory
  validation tools run on these taps the same way as on LLM writes. The payload must match a button on
  the latest agent message — typing a schema-valid `set:` string that was not offered
  there is rejected. If the tap targets a field the active skill cannot write (for
  example a memory entry from an earlier skill), or the payload is stale/invalid, the
  agent replies with a fixed notice that the selection is no longer available or an
  invalid value — naming it when the inbound message metadata includes `button_title`
  — and asks the user to choose an available option or type their message. A
  second tap on a
  write-once project field is rejected the same way and leaves the first value.
  Override the packaged notice by declaring `utter_set_memory_button_skipped` in
  your own `responses.yml`.
* [#6699](https://github.com/RasaHQ/rasa-private/pull/6699): Response variant
  [`metadata`](https://rasa.com/docs/mantle/reference/responses-yml#variant-metadata) from `responses.yml` is now stored on bot messages in the conversation tracker, not only
  the internal `rephrase` flag.

### Improvements

* [#6789](https://github.com/RasaHQ/rasa-private/pull/6789): Conversation-scoped
  structured logs now include `conversation_id` across engine and voice processing.
  Voice TTS debug events no longer also emit a duplicate `recipient_id`.

### Bugfixes

* [#6746](https://github.com/RasaHQ/rasa-private/pull/6746): Updated the prompt to
  instruct the agent to answer in-skill follow-ups instead of calling
  `cannot_help`.
* [#6745](https://github.com/RasaHQ/rasa-private/pull/6745): Clarification questions
  and task switches no longer cancel a pending tool confirmation.

**3.20.0.dev7**

2026-09-03

### Features

* [#6669](https://github.com/RasaHQ/rasa-private/pull/6669): You can now add static
  [`buttons`](https://rasa.com/docs/mantle/reference/responses-yml#static-buttons) to named responses in `responses.yml`; the engine delivers them on collect
  and action asks in chat and web channels, including after streamed rephrase, with
  memory placeholders resolved in button titles and payloads. Taps with a free-text
  `payload` (or an omitted payload that defaults to the title) are handled like typed
  input — see
  [Plain-text payloads](https://rasa.com/docs/mantle/reference/responses-yml.md#plain-text-payloads).
* Mantle hooks authoring surface (preview): import `on_*` and `modify_*`
  decorators, typed payloads, and `HookRejection` / `RetryModel` from
  `rasa.mantle.hooks`. Place modules in `hooks.py` or `hooks/**/*.py`; train-time
  validation runs before packaging. The runtime does not invoke hooks yet —
  turn-path wiring lands in a follow-up release.

### Improvements

* [#6587](https://github.com/RasaHQ/rasa-private/pull/6587): `rasa init --engine mantle`
  now bundles the Mantle documentation into your project at `.rasa/docs/mantle/`, and the
  installed agent skills tell your coding agent to read it rather than guess. Add it to an
  existing project with `rasa tools init docs mantle`. See
  [Getting started](https://rasa.com/docs/mantle/getting-started.md).

### Bugfixes

* [#6695](https://github.com/RasaHQ/rasa-private/pull/6695): Rasa CLI commands now work on Python 3.14.
  Previously every command, including `rasa init` and `rasa --version`, failed immediately on startup.

**3.20.0.dev6**

2026-09-01

### Breaking Changes

* [#6610](https://github.com/RasaHQ/rasa-private/pull/6610): The orchestrator LLM now
  uses `llm.model_group` and a matching `model_groups` entry. Move inline
  provider, model, and credential settings from `llm:` into that group:

  ```yaml theme={null}
  llm:
    model_group: orchestrator

  model_groups:
    - id: orchestrator
      models:
        - provider: openai
          model: gpt-5.1
          api_key_env: OPENAI_API_KEY
  ```

  See [`integrations.yml`](https://rasa.com/docs/mantle/reference/integrations-yml).
* [#6733](https://github.com/RasaHQ/rasa-private/pull/6733): `rasa data validate` now
  requires every conditional `next` to include an `else` fallback:

  ```yaml theme={null}
  next:
    - if: "session.card_replace.selected_card_id"
      then: check_card_eligible
    - else: END
  ```

  See [Conditional branching](https://rasa.com/docs/mantle/reference/ordered-block-steps.md#conditional-branching).

### Bugfixes

* [#6733](https://github.com/RasaHQ/rasa-private/pull/6733): Called skills no longer
  restart when no conditional `next` branch matches.

**3.20.0.dev5**

2026-09-01

### Breaking Changes

* [#6670](https://github.com/RasaHQ/rasa-private/pull/6670): `rasa data validate` now
  fails when a tool reaches the internal memory manager or clears memory
  entries. Clear fields this skill owns with `context.memory.set`. Fields
  another skill owns must be cleared from that skill. See
  [Tools](https://rasa.com/docs/mantle/reference/tools.md).

### Features

* [#6654](https://github.com/RasaHQ/rasa-private/pull/6654): You can now declare static
  `buttons` on response variants in `responses.yml` (each with a `title` and optional
  `payload`). This PR adds parsing and train-time validation only — `rasa train` checks
  button shape and `set:` memory payloads against the same readable and settable memory
  rules the engine will use when those buttons write memory on tap; button delivery at
  runtime is not included yet.
* [#6650](https://github.com/RasaHQ/rasa-private/pull/6650): Conversations now record
  skill lifecycle (`skill_activated` / `completed` / `cancelled` / `interrupted` /
  `resumed`), tool runs (`tool_executed`, local or MCP), and memory writes
  (`memory_set` / `memory_cleared`). Skill-level `flow_*`, `mcp_tool_executed`, and
  `slot_set` events are still written as well. Inspector and Copilot map these types.
  See [Tracker events](https://rasa.com/docs/mantle/reference/execution-loop.md#tracker-events).

### Improvements

* [#6670](https://github.com/RasaHQ/rasa-private/pull/6670): When a collect
  step is skipped because the value is already known, the agent is told not
  to ask for that value again in the same turn. See
  [Prompt templates](https://rasa.com/docs/mantle/reference/prompt-templates.md).

### Bugfixes

* [#6715](https://github.com/RasaHQ/rasa-private/pull/6715): Voice responses no longer
  play stale audio from an interrupted response after a barge-in.

**3.20.0.dev4**

2026-08-28

### Breaking Changes

* [#6678](https://github.com/RasaHQ/rasa-private/pull/6678): Starting the same
  skill again in a session now resets that skill's public and private memory
  to each field's `initial_value` (`null` when unset). Values still stay after
  complete, cancel, and interrupt until that next run. Put session-long facts
  in project memory. See [Lifetime](https://rasa.com/docs/mantle/reference/memory-yml.md#lifetime).
* [#6637](https://github.com/RasaHQ/rasa-private/pull/6637): Project memory is no longer writable by the LLM (`set_fields`, `collect`, or `correct`). Train rejects `llm_settable: true` and `collect:` on a project field. Collect user-facing values in skill memory, then write `project.*` from a tool or post-write hook. After the first successful write, further writes fail for the rest of the session. See [Skill vs project memory](https://rasa.com/docs/mantle/reference/memory-yml.md#skill-vs-project-memory).
* [#6637](https://github.com/RasaHQ/rasa-private/pull/6637): Memory fields no longer support `immutable`. Skill public and private memory stays writable. Project fields remain write-once after the first successful write. See [memory.yml](https://rasa.com/docs/mantle/reference/memory-yml.md).
* [#6608](https://github.com/RasaHQ/rasa-private/pull/6608): Tool calls now
  time out after `10` seconds by default. Set the top-level
  [`tool_timeout` in `agent.yml`](https://rasa.com/docs/mantle/reference/agent-yml#tool_timeout) for slow
  local `@tool` functions. Imported MCP tools use the same default unless their
  server sets its own `tool_timeout` in `integrations.yml`.

### Features

* [#6608](https://github.com/RasaHQ/rasa-private/pull/6608): You can connect
  agents to MCP servers. Declare servers under `mcp_servers` in
  [`integrations.yml`](https://rasa.com/docs/mantle/reference/integrations-yml#mcp_servers). Skills can
  import remote MCP tools with `import_tools: [mcp/<server>:<tool>]`. See
  [Import MCP tools](https://rasa.com/docs/mantle/concepts/tools.md#mcp-tools).

### Improvements

* [#6718](https://github.com/RasaHQ/rasa-private/pull/6718): OpenTelemetry metrics now show the time between consecutive agent responses in a Mantle turn, including waits after fillers and before final responses.
* [#6637](https://github.com/RasaHQ/rasa-private/pull/6637): Set project memory now stays visible in a dedicated `### Project Memory` prompt section, including while routing. That section tells the model those facts are already set for the session and will remain so. See [System Prompt](https://rasa.com/docs/mantle/reference/system-prompt.md) and [Prompt templates](https://rasa.com/docs/mantle/reference/prompt-templates.md).
* [#6637](https://github.com/RasaHQ/rasa-private/pull/6637): Session-start metadata can populate project memory for fields marked `seed: true`. A metadata value that does not match the declared field type is skipped (the field stays unset). Train rejects `seed: true` on skill public or private fields. See [Seeding from session start](https://rasa.com/docs/mantle/reference/memory-yml.md#seeding-from-session-start).
* [#6608](https://github.com/RasaHQ/rasa-private/pull/6608): Langfuse tool-call
  traces now record the tool name and argument keys as the span input, not
  argument values, so account identifiers and other inputs stay out of the
  trace.
* [#6693](https://github.com/RasaHQ/rasa-private/pull/6693): When call recording is enabled, voice traces now
  include a span for storing the recording, with its storage location and whether it was saved, skipped, or failed.

**3.20.0.dev3**

2026-08-27

### Features

* [#6645](https://github.com/RasaHQ/rasa-private/pull/6645): You can now declare [conditional
  response variants](https://rasa.com/docs/mantle/reference/responses-yml.md#conditional-variants) in `responses.yml`: each variant may include a memory `condition`, the
  engine delivers the first match in YAML order or a required default, and `rasa train`
  rejects empty text, invalid conditions, and malformed default rules with a located error.

### Improvements

* [#6685](https://github.com/RasaHQ/rasa-private/pull/6685): Voice traces now
  show whether a barge-in happened while audio was playing or still queued, and
  they include dropped agent responses when content capture is enabled.

**3.20.0.dev2**

2026-08-26

### Features

* [#6697](https://github.com/RasaHQ/rasa-private/pull/6697): Added Deepgram Flux
  TTS. Voice agents can now use Deepgram Flux for streaming text-to-speech by
  setting the TTS provider name to `deepgram_flux`.

* [#6343](https://github.com/RasaHQ/rasa-private/pull/6343): Voice interruption
  events in Inspector now show how far the agent response played before the user
  interrupted, including confirmed playback progress and the full response duration
  when available. The engine also tells the model that the interrupted response may
  not have been heard in full.

### Bugfixes

* [#6679](https://github.com/RasaHQ/rasa-private/pull/6679): Installing Rasa Pro on
  macOS no longer fails while building LiteLLM. Previously LiteLLM had no prebuilt
  macOS wheel, so it was compiled from source and the install failed unless a recent
  Rust toolchain (rustc 1.94.1 or newer) was already available.

* [#6674](https://github.com/RasaHQ/rasa-private/pull/6674): Voice agents can now
  connect to speech providers on systems that require custom CA certificates configured
  through `SSL_CERT_FILE`.

**3.20.0.dev1**

2026-08-26

### Breaking Changes

* [#6603](https://github.com/RasaHQ/rasa-private/pull/6603): The engine internals are now
  named **Mantle** throughout (the `calm_v2` package became `mantle`, and the persisted
  `engine_version` value changed from `calm_v2` to `mantle`). **Custom tool modules must
  update their imports** from `rasa.calm_v2.tools.*` to `rasa.mantle.tools.*` — e.g.
  `from rasa.mantle.tools.decorator import tool, ToolContext` and
  `from rasa.mantle.tools.result import ToolResult`. Agents whose `tools.py` files import
  the old `rasa.calm_v2.*` path fail to load until updated. Models trained on earlier
  `.dev` builds will not load and must be retrained.
* [#6652](https://github.com/RasaHQ/rasa-private/pull/6652): Python 3.10 is no longer
  supported. Use Python 3.11 through 3.14.

### Improvements

* [#6652](https://github.com/RasaHQ/rasa-private/pull/6652): Mantle now includes the
  latest Rasa Pro `main` line after 3.19.0 (Sanic 25, Python 3.14, and optional voice
  call recording), and pins `rasa-sdk` to `3.20.0.dev1`.

### Bugfixes

* [#6595](https://github.com/RasaHQ/rasa-private/pull/6595): Setting `rephrase: true`
  on a response now also rewords confirmation questions, messages when the user
  says no, and success or failure messages.

**3.19.0.dev7**

2026-08-25

### Breaking Changes

* [#6576](https://github.com/RasaHQ/rasa-private/pull/6576): The CLI engine value is now
  `mantle` instead of `maestro`. Use `rasa init --engine mantle` and
  `rasa tools skills install mantle`. The old value is rejected rather than deprecated, so
  update any scripts that pass `maestro`. See
  [Getting started](https://rasa.com/docs/mantle/getting-started.md).

### Bugfixes

* [#6600](https://github.com/RasaHQ/rasa-private/pull/6600): Users can now correct a
  previously collected skill-scoped memory value.

**3.19.0.dev6**

2026-08-20

### Improvements

* [#6531](https://github.com/RasaHQ/rasa-private/pull/6531): Tool-call acknowledgement fillers (`prompts.ack_enabled`) are **off by default on text channels** and **on by default on voice**. Set `ack_enabled: true` or `false` in `agent.yml` to force either way for both modalities. Removed redundant inline-text guidance from `cancel_skill` lifecycle and tool schema; generic acknowledgement guidance still applies when ack is enabled.
* [#6512](https://github.com/RasaHQ/rasa-private/pull/6512): The default system
  prompt now places deploy-stable and episode-stable sections before the current
  date and time so provider prompt-prefix caches stay warmer across turns. The
  [System Prompt](https://rasa.com/docs/mantle/reference/system-prompt.md) and
  [Prompt templates](https://rasa.com/docs/mantle/reference/prompt-templates.md) reference pages match the new
  order and wording.

### Features

* [#6360](https://github.com/RasaHQ/rasa-private/pull/6360): Voice agents now
  expose OpenTelemetry traces for calls, provider connections, transcription,
  input decisions, speech synthesis, and audio playback. See
  [Observability](https://rasa.com/docs/mantle/reference/observability.md).
* [#6504](https://github.com/RasaHQ/rasa-private/pull/6504): Skill instruction prose can
  reference live memory with `@memory.project.<field>` and `@memory.<skill_id>.<field>`
  (prompt substitution and train validation). Unreadable `@memory` refs, incomplete `@memory`
  lookalikes, and bare `session.*` in free prose fail train. See
  [skill.md — Memory](https://rasa.com/docs/mantle/reference/skill-md.md#memory).

### Bugfixes

* [#6552](https://github.com/RasaHQ/rasa-private/pull/6552): Voice-ready and custom
  channels can now mark incoming turns as voice so the engine applies voice-specific
  prompt guidance.

* [#6546](https://github.com/RasaHQ/rasa-private/pull/6546): Voice calls now reject
  spoken input while a DTMF collect step disables audio input, with the rejection
  recorded in tracing.

* [#6558](https://github.com/RasaHQ/rasa-private/pull/6558): The tool-call
  acknowledgement section (and its examples) is no longer repeated in the system
  prompt on every agent-loop iteration. The agent acknowledges once per turn, so
  the guidance is now included only on the first LLM iteration and dropped on
  later iterations, trimming prompt tokens. See the
  [System Prompt](https://rasa.com/docs/mantle/reference/system-prompt.md) reference.

**3.19.0.dev4**

2026-08-12

### Breaking Changes

* [#6401](https://github.com/RasaHQ/rasa-private/pull/6401): Ordered-block steps now
  reject unknown YAML properties. The removed collect-step keys `force_collection`
  and `tool:` are no longer accepted — use `ask_before_filling: true` instead. The agent also fails
  to start when a skill directory cannot be parsed or when two skill directories
  in the same `skills/` tree declare the same skill id.

### Improvements

* [#6428](https://github.com/RasaHQ/rasa-private/pull/6428): Mantle projects without an
  `endpoints.yml` no longer log errors about the missing file when running CLI
  commands such as `rasa train`. Endpoint-backed tracing, metrics, and secrets
  configuration is skipped instead. CALM projects are unaffected.
* [#6423](https://github.com/RasaHQ/rasa-private/pull/6423): Tools can read
  another skill's `public` memory (and `project.*`) via fully-qualified names on
  `context.memory.get`, with the same visibility as conditions / `read_all`
  (private fields and `deny_read` still blocked). Writes stay scoped to the
  active skill and project.
* [#6401](https://github.com/RasaHQ/rasa-private/pull/6401): Step and skill load
  validation now surfaces clearer, actionable error messages (including migration
  hints for the removed collect-step keys), and `rasa data validate` reports
  unloadable skill directories instead of relying on silent skips at runtime.
* [#6405](https://github.com/RasaHQ/rasa-private/pull/6405): Langfuse tracing is configured under optional `tracing:` in
  `integrations.yml` (`type: langfuse`, `${VAR}` keys, optional knobs such as
  `environment` and `timeout`). Example agents no longer rely on `endpoints.yml`
  for tracing; Langfuse declared only in `endpoints.yml` still works with a
  deprecation warning until you migrate the block.

### Documentation

* [#6423](https://github.com/RasaHQ/rasa-private/pull/6423): The
  [tools](https://rasa.com/docs/mantle/reference/tools.md) and [memory.yml](https://rasa.com/docs/mantle/reference/memory-yml.md) references
  document fully-qualified `context.memory.get` reads for sibling public fields.
* [#6401](https://github.com/RasaHQ/rasa-private/pull/6401): The
  [skill.md reference](https://rasa.com/docs/mantle/reference/skill-md.md) documents ordered-block step
  validation, the removed-key migration table, and collect-step authoring without
  per-step `tool:` overrides.


## Related topics

- [Studio Change Log](https://rasa.com/docs/reference/changelogs/studio-changelog.md)
- [Rasa SDK Change Log](https://rasa.com/docs/reference/changelogs/rasa-sdk-changelog.md)
- [Rasa Pro Change Log](https://rasa.com/docs/reference/changelogs/rasa-pro-changelog.md)


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