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

# agent.yml

> Agent identity, persona, global rules, prompt tuning, and session settings.

`agent.yml` is required at the project root. It carries the agent's identity in
an `agent:` block, plus several top-level tuning sections.

```yaml agent.yml theme={null}
agent:
  id: telco-support
  language: en
  persona: |
    You are Telco support. A friendly, concise customer service assistant.

rules:
  - Help with billing and plan questions only.
  - Never quote a balance without looking up the account first.

knowledge_answering:
  embeddings: reference_embeddings

# Optional. Omit the block to leave skill retrieval off.
# skill_retrieval:
#   active: true
#   num_skills: 20
#   turns_to_embed: 1
#   should_embed_memory: true
#   embeddings: skill_embeddings

conversation:
  before_end:
    - builtin_customer_satisfaction

orchestrator:
  model_group: main_model
  text_rules: |
    Plain sentences only. No markdown or bullet lists.
  preconditions:
    customer_authenticated:
      satisfied_when: session.project.authenticated
      resolve_with: authentication

# Optional. Wall-clock limit for local @tool and MCP tool calls (seconds).
# tool_timeout: 30

session_config:
  session_expiration_time: 60
  start_session_after_expiry: true
```

The file has two levels. `id`, `language`, and `persona` are the agent's
identity and live **inside** the `agent:` block. `rules`, `fillers`,
`knowledge_answering`, `skill_retrieval`, `conversation`,
`tool_timeout`, `orchestrator`, and `session_config` are tuning sections and
sit at the **top level** as siblings of it.

## The `agent:` block

Required. A missing or non-mapping `agent:` section fails the load.

| Key | Required | Default | Description |
| - | - | - | - |
| `persona` | **Yes** | none | Free text prepended to every system prompt. Must be a non-empty string. |
| `id` | No | generated | Stable agent identifier. |
| `language` | No | `en` | Primary conversation language. |

### `persona`

Required, together with `orchestrator.model_group`. A missing or blank `persona`
raises `config.agent.missing_persona` at load.

It sets global tone and identity.

### `id`

When absent or blank, a unique id is generated in the form
`YYYYMMDD-HHMMSS-<duoname>` and **written back into `agent.yml`**, with a warning.
`language` is not written back. The `en` default is applied at parse time only.

## `rules`

A list of strings, rendered into the system prompt as a bullet list. These are
global do/don't guidance applied across every skill: scope limits, tone guards,
ordering constraints.

```yaml theme={null}
rules:
  - You help with card replacement, balance checks, and fraud reports only.
  - Do not mention skill, tool, or memory names to the customer.
  - >
    If the user already provided the information you need, do not ask again:
    record it and continue.
```

> [!NOTE]
>
> A rule containing `:` followed by a space parses as a YAML mapping and breaks
> the load. Quote it, or use a `>` folded scalar as above.

## `fillers`

The short message before a tool call. Every key is optional; an empty or
absent value falls back to the built-in default.

| Key | Type | Description |
| - | - | - |
| `enabled` | bool | Whether the acknowledgement section and reminder are included. When omitted, enabled on **voice** turns and disabled on **text** turns. Set explicitly to override both modalities. |
| `instructions` | string | Guidance for acknowledging a tool call in progress. Omit it to keep the built-in instruction, which asks for an acknowledgement that stays true if the tool fails, finds nothing, or needs confirmation. Setting it also removes the built-in examples. |
| `reminder` | string | Short reminder injected after the user message on the first LLM iteration. Omit it to keep the built-in nudge. |
| `examples` | list | Few-shot examples, each `{user, ack}`. They replace the built-in examples. Omit the key to keep the built-in examples, or to have none when `instructions` is set. |

```yaml theme={null}
fillers:
  enabled: true
  examples:
    - user: I lost my card
      ack: Oh no, let me take a look.
```

Unknown keys under `fillers` fail the load.

On voice channels, the pauses between agent messages are set per channel in
`integrations.yml`:
[`pause_after_filler`](https://mantle.rasa.com/reference/integrations-yml#pause_after_filler) after a
filler, and
[`pause_between_messages`](https://mantle.rasa.com/reference/integrations-yml#pause_between_messages)
between other consecutive messages.

## `prompts`

Settings that are not the pre-tool line or a channel style. Unknown keys are
ignored.

| Key | Type | Description |
| - | - | - |
| `routing_no_active_skill` | string | Extra routing guidance appended to the catalogue when no skill is active. Omit it to add none. |

```yaml theme={null}
prompts:
  routing_no_active_skill: |
    Greet the user, then help them pick a task.
```

## `knowledge_answering`

Controls how the agent answers from retrieved knowledge.

| Key | Description |
| - | - |
| `instructions` | How to write the answer. When set, this is its own paragraph after the lifecycle search bullet. The when-to-search bullet stays, including the built-in instruction. Omit it to add no extra paragraph. A skill's `knowledge_answering.instructions` replaces this text while that skill is active. |
| `top_k` | How many chunks the local index returns. Default `4`. Must be a positive integer. Remote stores are unchanged. Read when the trained model loads, so changing it needs another train. It is not stored in the index. |
| `embeddings` | Id of an LLM group in `integrations.yml`, used to embed `references/**/*.md`. Leave it empty to use the built-in OpenAI default. A speech group cannot be used. |
| `chunking` | How markdown files are split before embedding. Omit the key to use the defaults below. Unknown keys under `chunking` fail the load. |

Unknown keys under `knowledge_answering` fail the load.

The same model group embeds the corpus at `rasa train` and loads it at serve
time, so keep it declared for as long as the trained model is in use.

### `chunking`

At `rasa train`, each reference `.md` file is split with recursive character
chunking, then each chunk is embedded. `search_knowledge` returns those
sections, not whole files. Size and overlap are **characters**, not embedding
tokens.

| Key | Type | Default | Constraints |
| - | - | - | - |
| `chunk_size` | int | `1000` | Must be greater than `0`. |
| `chunk_overlap` | int | `20` | Must be `>= 0` and **smaller than** `chunk_size`. |

```yaml agent.yml theme={null}
knowledge_answering:
  embeddings: reference_embeddings
  top_k: 4
  chunking:
    chunk_size: 1000
    chunk_overlap: 20
```

Keep `chunk_size` well under the embedder's maximum input. Azure OpenAI
embeddings and OpenAI `text-embedding-3-small` / `text-embedding-3-large` cap
input at **8192 tokens**. The default 1000 characters stays under that limit; a
much larger character size can still fail train.

Changing `chunking` requires `rasa train`, which rebuilds the index. Serving
does not re-read `references/` from disk. `top_k` is not stored in the index;
it is read from the packaged spec when the model loads, so changing it also
needs another train. See
[References](https://mantle.rasa.com/concepts/references.md#how-files-are-split) for when to override
the chunking defaults.

## `skill_retrieval`

Optional top-level block. When retrieval runs, each user turn offers only a
retrieved subset of **startable skills** in the routing catalogue and the
`activate` tool — not the full list.

A startable skill is one the model can start itself with `activate`. Retrieval
indexes and can return only those skills. A skill is startable when it is
not engine-managed, not [`disabled`](https://mantle.rasa.com/reference/skill-md#disabled), not
[`hidden`](https://mantle.rasa.com/reference/skill-md#hidden), and it has a routable entry. Other
skills stay out of the index and out of search results:

* Engine-managed skills are started by the engine (for example silence timeout).
  They never appear in the routing prompt or the `activate` list, so retrieval
  does not return them.
* `hidden` and `disabled` skills are omitted from the routing catalogue, so
  they are not returned either.
* A skill with no routable entry is internal. `call:`, `link:`, and
  `resolve_with` can still start it, and it does not take a search slot.

This is **not** knowledge search. `knowledge_answering` / `search_knowledge`
retrieve passages from `references/` to answer questions. `skill_retrieval`
chooses which startable skills the model may start.

Omit the block, or omit `active`, to leave retrieval **off**. The full legal
catalogue stays, and no index is written. Set `active: true` to opt in.

Retrieval runs only when there are more startable skills than `num_skills`.
Skills that are not startable do not take a `num_skills` slot. At or below
that count, train does not write the index and logs a warning with both counts.
The turn keeps the full catalogue. `active` stays `true`. The next train writes
the index once the catalogue is larger than `num_skills`, or once `num_skills`
is lowered below the current count.

When retrieval runs, the index is required. A model whose startable count is
above `num_skills` and was trained without that index must be retrained.
Silence-timeout turns do not search; they keep always-include, previously
started, and the live skill.

| Key | Type | Default | Description |
| - | - | - | - |
| `active` | bool | `false` | Whether skill retrieval is enabled. |
| `num_skills` | int | `20` | Maximum skills returned by search (`>= 1`). Retrieval runs only when startable skills exceed this number. |
| `turns_to_embed` | int | `1` | How many recent user and agent utterance lines go into the search query. `1` is only the current user message. |
| `should_embed_memory` | bool | `true` | Include each skill's memory field names, descriptions, and allowed values in the index. |
| `embeddings` | string | empty | Id of a `model_groups` entry in `integrations.yml`. Empty uses the built-in default embedder. |

Unknown keys under `skill_retrieval` fail the load. `num_skills` below 1 fails
the load. To keep every legal skill, set `active: false`.

```yaml agent.yml theme={null}
skill_retrieval:
  active: true
  num_skills: 20
  turns_to_embed: 1
  should_embed_memory: true
  embeddings: skill_embeddings
```

At `rasa train`, when retrieval runs, only startable skills are indexed.
The same filter applies at runtime, so a retrieved or pinned skill stays out of
the catalogue when the model cannot start it. Engine-managed, `hidden`,
`disabled`, and skills with no routable entry stay out because they never
appear in the routing prompt.

Skills with [`always_include_in_prompt`](https://mantle.rasa.com/reference/skill-md#always_include_in_prompt)
stay in the catalogue when they are legal, even if search missed them. Skills
started in the last 20 utterance lines of the **current** conversation stay offered the
same way. A restart or a new session starts a new window.

If search or embedding fails while retrieval is running, the turn fails the
same way as an LLM outage. The agent does not fall back to listing every skill.

A train with `active: false` and more than 20 startable skills logs a warning
with that count. The catalogue is large enough that turning retrieval on would
filter it. A train with `active: true` and a startable count at or below
`num_skills` logs a warning with both counts and does not write the index.

## `conversation`

```yaml theme={null}
conversation:
  before_end:
    - builtin_customer_satisfaction
```

`before_end` lists skill ids that should complete before the conversation ends.
The names are rendered into the routing prompt, so the orchestrator knows to
pick those skills up before wrapping up.

Voice silence is engine-managed: three check-ins, then goodbye and hangup on the
next timeout. Any user speech resets that counter. Builders can override the
bundled silence responses; the retry count is not configurable. Default wording
is on [Silence timeout](https://mantle.rasa.com/reference/builtin-skills.md#silence-timeout).

## `tool_timeout`

Optional top-level key. Wall-clock timeout in seconds for tool calls.

| Key | Required | Default | Description |
| - | - | - | - |
| `tool_timeout` | No | `10` | Positive finite number of seconds. Applies to local `@tool` functions. Also used for imported MCP tools when the server omits its own `tool_timeout` in [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers); a per-server value overrides this default. |

```yaml agent.yml theme={null}
tool_timeout: 30
```

When a tool exceeds the limit, the runtime cancels the call and returns an
error payload to the LLM so it can recover (for example, retry or ask the
user). Raise this value for slow backends (databases, long HTTP calls); leave
it unset to keep the `10` second default.

## `session_config`

| Key | Default | Description |
| - | - | - |
| `session_expiration_time` | 60 | Session lifetime in minutes. `0` disables expiry entirely. A negative value fails validation. |
| `start_session_after_expiry` | `true` | Whether a new session auto-starts on the next message after expiry. |

## Voice

Voice is a channel in
[`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#voice-channels). Speech
recognition and synthesis are model groups named by
[`asr` and `tts`](#asr-and-tts) here, or on that channel. The runtime detects a
voice channel and applies the voice settings from this file:

| Setting | Effect on voice turns |
| - | - |
| `orchestrator.voice_rules` | Replaces the built-in spoken-style rules |
| `fillers.enabled` | Acknowledgements before tool calls; on by default for voice |
| `fillers.examples`, `fillers.instructions`, `fillers.reminder` | Shape those acknowledgements |
| `rules` | Apply on every channel; a closing rule such as "say goodbye once and stop" matters most on a call |

```yaml agent.yml theme={null}
fillers:
  examples:
    - user: I lost my card
      ack: Oh no, let me take a look.
```

See [Voice agents](https://mantle.rasa.com/voice/overview.md) for what else changes on a call, and
[Designing for voice](https://mantle.rasa.com/voice/designing-for-voice.md) for how to use these settings.

## `asr` and `tts`

Optional, under the top-level `voice:` key. Each value is the id of a
[speech model group](https://mantle.rasa.com/reference/integrations-yml.md#voice-channels) in
`integrations.yml`. `asr` is speech recognition. `tts` is speech synthesis.
Leave a side empty when every voice channel sets that side itself.

| Key | Default | Description |
| - | - | - |
| `asr` | unset | Model group id used when a voice channel omits `asr`. |
| `tts` | unset | Model group id used when a voice channel omits `tts`. |

A string on the channel replaces that side. The Inspector still uses Deepgram
when both the channel and these keys omit a side. Every other voice channel
fails to start until the missing side is set here or on the channel. A value
that is not a string, or that names a group the side cannot use, fails
`rasa data validate`.

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

Changing either id, or the group it names, is read from the live project.
Restart to pick it up. A retrain is not required.

## `silence_timeout`

Optional, under the top-level `voice:` key. This is where
`interaction_handling.global_silence_timeout` from `endpoints.yml` moves.

| Key | Default | Description |
| - | - | - |
| `silence_timeout` | `30` | Seconds to wait after the caller stops speaking. Must be greater than `0`. |

A `silence_timeout` on the voice channel overrides this value. Omit the key to keep 30 seconds.

```yaml agent.yml theme={null}
voice:
  silence_timeout: 4
```

## `interruptions`

Optional, under the top-level `voice:` key. Sets, for every voice channel:

* whether the caller can talk over the agent
* when short speech is ignored as a backchannel
* an optional cooldown after a burst of interruptions

| Key | Default | Description |
| - | - | - |
| `enabled` | `false` | Accept interruptions while agent audio is playing or queued. Interruption handling is in beta. |
| `min_words` | `3` | Speech with at least this many words interrupts without being scored. Must be `0` or more. With `0`, every transcript is accepted as an interruption. |
| `backchannel_threshold` | `0.7` | Score at or above which shorter speech is ignored as a backchannel. Must be from `0` to `1`. |
| `cooldown` | none | A cooldown after a burst of interruptions. See [`cooldown`](#cooldown). |

A voice channel's [`interruptions`](https://mantle.rasa.com/reference/integrations-yml#interruptions)
block overrides only the keys it sets; the others come from this block. Omit
the block to keep the defaults. Unknown keys under `interruptions` fail the
load.

> [!NOTE]
>
> The Inspector always sets `enabled` itself, `true` by default, so
> `voice.interruptions.enabled` has no effect there. Set `enabled` on the
> Inspector channel in `integrations.yml` to change it.

```yaml agent.yml theme={null}
voice:
  interruptions:
    enabled: true
    min_words: 3
    backchannel_threshold: 0.7
```

See [How backchannels are classified](https://mantle.rasa.com/reference/integrations-yml.md#how-backchannels-are-classified)
for how short speech is scored.

### `cooldown`

Optional, under `voice.interruptions`. After too many interruptions in a short time, the agent ignores further interruptions until a cooldown passes. Use it when a caller and the agent keep cutting each other off.

| Key | Default | Description |
| - | - | - |
| `max_interruptions` | none | Accepted interruptions allowed inside `window`. The next one is ignored. Required when this block is set. |
| `window` | none | Seconds over which those interruptions are counted. Required. Must be greater than `0`. |
| `duration` | none | Seconds to ignore further interruptions after `max_interruptions` is passed. Required. Must be greater than `0`. |
| `scope` | `call` | `call` forgets interruptions as they leave the window. `response` also clears the count after one agent response finishes without being interrupted. |

A voice channel's `interruptions.cooldown` block in [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#interruptions) replaces this one as a whole. Omit the block to leave the protection off.

```yaml agent.yml theme={null}
voice:
  interruptions:
    enabled: true
    cooldown:
      max_interruptions: 3
      window: 10
      duration: 8
      scope: response
```

## Starting a conversation

The bundled `builtin_session_start` skill does not greet. Who speaks first
decides whether you should override it. The other bundled skills and their
default wording are in [Builtin skills](https://mantle.rasa.com/reference/builtin-skills.md).

* **Agent speaks first** — override `builtin_session_start` with a greeting and
  have the channel send `/session_start` as the first user message.
* **User speaks first** — leave the bundled skill silent so the first real
  utterance can be handled immediately.

`rasa shell`, the Inspector, and the built-in voice channels already send
`/session_start`. See
[Start a conversation](https://mantle.rasa.com/mantle/runtime-loop.md#start-a-conversation).

## `orchestrator`

Names the model group that runs the agent, binds skill `precondition`
names, and optionally tunes built-in tools. The group itself — provider,
model, and API key — is defined in
[`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml) `model_groups`.

```yaml agent.yml theme={null}
orchestrator:
  model_group: main_model
  max_prompt_tokens: 12000
```

| Key | Required | Default | Description |
| - | - | - | - |
| `model_group` | **Yes** | none | Id of an LLM group declared under `model_groups` in `integrations.yml`. A speech group cannot be used. |
| `max_prompt_tokens` | No | `8000` | Positive token budget for the assembled prompt. |
| `text_rules` | No | built-in | Channel rules for text conversations. A set value replaces that block. Omit it to keep the built-in text rules. |
| `voice_rules` | No | built-in | Channel rules for voice conversations. A set value replaces that block only, including the guidance on speaking numbers, dates, URLs, and email addresses, so copy any of it you want to keep. The built-in text is on [Prompt templates](https://mantle.rasa.com/reference/prompt-templates.md). Omit it to keep the built-in voice rules. |
| `preconditions` | No | none | How each skill precondition is cleared. See below. |
| `tool_constraints` | No | none | Per built-in tool, `enabled` and optional `description`; for `cancel`, also `requires_confirmation`. See below. |

A missing `orchestrator:` block, or a blank `model_group`, fails the load.
Changing `model_group` needs a retrain. Changing the models inside that group
in `integrations.yml` needs a restart. A leftover `llm:` section in
`integrations.yml` is invalid.

### `preconditions`

Maps each **precondition name** to how the engine clears it before a skill
may start. The name must match a skill's `precondition:` field (for example
`customer_authenticated` on Card Replace). Define an entry here for every
`precondition:` used in the project.

```yaml agent.yml theme={null}
orchestrator:
  model_group: main_model
  preconditions:
    customer_authenticated:
      satisfied_when: session.project.authenticated
      resolve_with: authentication
      unmet_utterance: true
```

| Key | Required | Description |
| - | - | - |
| `satisfied_when` | **Yes** | [Condition](https://mantle.rasa.com/reference/conditions.md) string. When true, the waiting skill starts normally. |
| `resolve_with` | **Yes** | Skill id to **call** while the waiting skill is pending. That skill must not declare its own `precondition`. |
| `unmet_utterance` | No | Default `true`. After one failed resolver attempt, utter `utter_precondition_unmet`. Set `false` when the resolver already explained. Default text is on [Default skills](https://mantle.rasa.com/reference/builtin-skills.md#other-packaged-responses). |

`satisfied_when` is decided only from memory that was already saved. Values
stated on `activate` are not part of that check, and the skill's own fields are
reset first. See [the precondition check](https://mantle.rasa.com/reference/tools.md#precondition-check).

The waiting skill stays in routing. The engine parks it as pending, calls the
resolver, then promotes or abandons — no resume prompt. If `resolve_with` is
already the active skill (for example the session opener is also the resolver),
the engine parks the waiting skill under that run instead of interrupting it and
starting a second resolver. When that running resolver is waiting on a
`collect` step with an `utterance`, the engine repeats that question (with
its buttons) right away, so the user sees what is still needed before the
queued skill can start. Asking for the queued skill again repeats the
question again. The question is also repeated when the agent answers such a
request in its own words, and when it declines an off-topic request and
returns to the step in the same turn.
A collect with no `utterance` has no question for the engine to repeat, so
the model asks for the field again in its reply. See
[`skill.md` `precondition`](https://mantle.rasa.com/reference/skill-md#precondition).

### `tool_constraints`

Optional mapping from a
[built-in tool](https://mantle.rasa.com/reference/tools.md#built-in-framework-tools) name to that tool's
levers. Omitting the
section, or omitting a tool inside it, keeps the default offer rules.
`enabled: true` does not force a tool onto a turn where it would not be
offered. The section is packaged with the model, so a change takes effect on
the next train. The offer rules and the per-tool lever table are on
[Built-in framework tools](https://mantle.rasa.com/reference/tools.md#tuning-built-in-tools).

```yaml agent.yml theme={null}
orchestrator:
  model_group: main_model
  tool_constraints:
    cancel:
      description: |
        Abandon the active skill only when the user clearly cancels the whole
        task ("never mind", "cancel", "forget it"). Use complete when they have
        finished the task.
```

| Key | Required | Default | Description |
| - | - | - | - |
| `enabled` | No | `true` | `false` removes the tool from the offered set. A call that still names it does not run. Allowed on `cancel`, `complete`, `search_knowledge`, `cannot_help`, and `listen`. |
| `description` | No | none | When set, **fully replaces** the engine's default description for that built-in on turns where the tool is offered. Blank text fails validation. Omit the key to keep engine defaults (voice and text differ for `listen` when omitted). See [default descriptions](https://mantle.rasa.com/reference/tools.md#default-built-in-tool-descriptions). |
| `requires_confirmation` | No | none | Mapping. `enabled: true` pauses the tool until the user confirms or declines. Allowed on `cancel` only. See [below](#cancel-requires_confirmation). |

`activate`, `enter`, and `set_memory` must stay enabled: none of them accept
`enabled: false`. A conversation cannot start a skill, enter a skill, or record
memory without them. You may still set `description` on any of the three to
replace the default tool description.

`description` changes what the model sees in the **tool list** for that built-in.
The **system prompt** still includes fixed instructions the engine adds — for
example when to call `search_knowledge`, to answer from tool results before
`complete()`, the resume-prompt `set_memory` bullet while the continue-interrupted
skill is active, out-of-scope handling while `cannot_help` is offered, and to
call `activate` when routing. Those prompt lines are not removed when you set
`description`. Keep tool wording and prompt instructions aligned so the model
does not see conflicting guidance.

A custom `description` replaces the **entire** default tool string the model
sees, including per-turn suffixes the engine appends when the key is omitted
(for example the `set_memory` correction rule or the `activate` hint to use
`enter`). Copy the published defaults from the tools reference and merge your
wording when you customize.

Turn `complete` off only when every skill that would have used it finishes
without the orchestrator: a `complete_when.condition` with no `criteria`, or an
ordered block that reaches `END`. Otherwise leave it on and use `description` if
you need different when-to-call wording.

`requires_confirmation` is rejected on every built-in tool other than
`cancel`, and the error names that tool.

Turning off `search_knowledge` still allows `cannot_help` before any search.
The references index stays packaged. Turning off only `cannot_help` leaves
search in place.

A declined optional step is not a cancel. Record it with `set_memory` and
continue the skill. That rule is in the `cancel` and `set_memory` descriptions,
not in a separate prompt line.

`listen` accepts `enabled` and `description`. Turning it off does not change
ordered-block `execute_tool: listen`. When `description` is set, the same
string is used on voice and text turns. See
[Built-in framework tools](https://mantle.rasa.com/reference/tools.md#tuning-built-in-tools).

`hangup`, `resolve_tool_confirmation`, and unknown names fail validation.
The error names the tool.

#### `cancel.requires_confirmation`

Optional confirmation before the built-in `cancel` runs. The pause matches a
skill tool's [`requires_confirmation`](https://mantle.rasa.com/reference/skill-md#tool_constraints).
The user hears one question. If they confirm, cancel proceeds the way it does
today: a side question ends and the paused task is offered again, a called step
drops with its parent, and confirming on the resume prompt drops the paused task.
If they decline, the skill stays in place. Omitting the block, or
`enabled: false`, keeps immediate cancel.

Do not also tell the model, in a skill body or in `rules`, to ask before
cancelling. That asks twice.

Name both lines:

```yaml agent.yml theme={null}
orchestrator:
  model_group: main_model
  tool_constraints:
    cancel:
      requires_confirmation:
        enabled: true
        utter_for_confirmation: utter_ask_cancel
        utter_on_user_denial: utter_cancel_declined
```

Or leave both lines to the model:

```yaml agent.yml theme={null}
orchestrator:
  model_group: main_model
  tool_constraints:
    cancel:
      requires_confirmation:
        enabled: true
```

| Key | Description |
| - | - |
| `enabled` | `true` pauses `cancel` until the user confirms or declines. Default `false`. |
| `utter_for_confirmation` | Optional response name for the question. Omit it and the model phrases the ask. |
| `utter_on_user_denial` | Optional response name spoken when the user declines, which ends the turn. Omit it and the model phrases that line. |

A set name must exist in `responses.yml` and have a non-empty body. A missing
or empty name fails train. A bare `requires_confirmation:` with nothing under
it fails train.

While the gate is on and another confirmation is already pending, the cancel
ask replaces that question. A yes drops the skill and clears the open tool
question. A no leaves the skill in place. A reply that neither confirms nor
declines leaves the cancel question waiting. The model brings the user back
in its own words. The original line is not played again.

`cancel` is offered only while a skill is active, including the resume
prompt. A call with nothing open does not ask and does not cancel. With
`enabled: false` on `cancel`, the tool is not offered and the
confirmation never runs.

## `privacy`

Optional top-level block for tracker-store anonymization and deletion cron
jobs. It accepts only `tracker_store_settings`. A `rules` list is rejected:
per-field anonymization belongs on memory fields with `pii: true` in
[`memory.yml`](https://mantle.rasa.com/reference/memory-yml#anonymization).

Mantle ignores a `privacy` block in `endpoints.yml` at runtime. Configure the
event broker (`stream_pii`, `anonymization_topics`) in
[`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml). Fields marked `pii: true`
are masked on published events. Session-start metadata
(`system.session_started_metadata`) is masked whenever a `privacy` block or a
`pii: true` field is present. A stored `session_started_metadata` event is still
masked.

```yaml theme={null}
privacy:
  tracker_store_settings:
    anonymization:
      min_after_session_end: 120
      cron: "30 1 * * *"
```

## See also

* [Start a conversation](https://mantle.rasa.com/mantle/runtime-loop.md#start-a-conversation): who speaks
  first, and when to override `builtin_session_start`
* [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml): model groups, channels, MCP servers (per-server `tool_timeout`), optional tracing and metrics
* [Speech providers](https://mantle.rasa.com/reference/speech-providers.md): built-in ASR and TTS providers and their settings
* [Tools](https://mantle.rasa.com/reference/tools.md): `@tool` interface and timeout behaviour
* [`memory.yml`](https://mantle.rasa.com/reference/memory-yml): project-wide memory
* [`skill.md`](https://mantle.rasa.com/reference/skill-md): `always_include_in_prompt` and other skill frontmatter


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