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

# responses.yml

> Named response templates, memory interpolation, and how they are delivered.

`responses.yml` holds named text templates the framework delivers verbatim. Use
it for wording that must be exact: legal disclosures, compliance notices,
regulated confirmations. Everything else should stay prose so the agent sounds
natural.

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_ask_shipping:
    - text: >-
        How would you like the new card shipped: rush delivery in 1 to 2
        business days, or standard in 5 to 7?

  utter_card_replacement_fee:
    - text: Standard replacement is free.
    - text: A fee applies for lost-card replacement.
      condition: 'session.card_replace.replacement_reason == "lost"'

  utter_card_replace_completed:
    - text: >-
        All set. Your replacement card has been ordered and will ship via
        {session.card_replace.order_shipping_summary} delivery.
```

The top-level key is `responses:`. Each name maps to a **list of variants**. At
delivery the engine selects **one** variant from that list (see
[Conditional variants](#conditional-variants) below). A response with a single
variant and no `condition` always selects that single variant.

An entry is either a mapping with a `text` key, or a plain string:

```yaml theme={null}
responses:
  utter_goodbye:
    - "Thanks for calling. Goodbye!"
```

## Conditional variants

Add an optional `condition` on a variant to gate its wording on current memory.
Conditions use the same [expression grammar](https://mantle.rasa.com/reference/conditions.md) as skill
`requires:` and prose `if:` lines.

```yaml theme={null}
responses:
  utter_card_replacement_fee:
    - text: Standard replacement is free.
    - text: A fee applies for lost-card replacement.
      condition: 'session.card_replace.replacement_reason == "lost"'
    - text: No fee for cards reported stolen.
      condition: 'session.card_replace.replacement_reason == "stolen"'
```

### How a variant is selected

When a response is delivered, the engine evaluates variants **in YAML order**:

1. Skip variants with no `condition` during this pass.
2. For each conditioned variant, evaluate its `condition` against readable
   memory. The **first** variant whose condition is true is delivered.
3. If none match, deliver the **default** variant — the one that omits
   `condition`.
4. If every variant is unconditioned, deliver the first variant.

If evaluating a condition raises an error at delivery time (for example a
comparison the current memory type cannot satisfy), that variant is skipped and
evaluation continues. When no conditioned variant matches, the default is used.

If there is no default and nothing can be selected (every variant is conditioned
and none match, or every condition fails evaluation), delivery fails closed the
same way as a missing response name: the engine utters the response name as
literal text and does not rephrase.

`metadata.rephrase` applies to whichever variant is selected, not always the
first variant. Other keys under `metadata` are delivered with the bot message on
the tracker (see [Variant metadata](#variant-metadata) below).

> [!WARNING]
>
> When an `utter:` trigger fires with `on: activate`, variant selection runs
> **after** the skill's memory is reset for that new run. Conditions that read
> that skill's own fields therefore see each field's
> [`initial_value`](https://mantle.rasa.com/reference/memory-yml#field-attributes) (or `null` when
> unset) — not leftovers from a previous run. Unless those fields declare a
> matching `initial_value`, conditioned variants miss and the **default**
> variant is delivered.
>
> For activation wording that depends on facts already known in the session, gate
> on **project memory** (`session.project.*`) or set a skill-field
> `initial_value` that the condition can match. For values collected **after**
> the skill starts, use a skill `utter:` `when:` trigger (or deliver the response
> from a later step) instead of relying on skill memory at `on: activate`.

### Default variant rules

When **any** variant on a response has a `condition`, exactly **one** variant
must omit `condition`. That variant is the **fallback** when no condition matches.
It may appear **anywhere** in the YAML list — first, last, or between
conditioned variants. The engine skips default variants while evaluating conditions,
then delivers that single fallback variant.

`rasa train` rejects:

* empty or non-list response entries (must be a non-empty variant list)
* empty or whitespace-only `text` on a variant that has no `custom` object
* a `custom` value that is not a JSON object
* invalid or empty `condition` syntax (must be a string expression)
* memory references in a `condition` that are not declared in skill or project
  `memory.yml`
* conditioned variants with no default, or more than one default

**Train errors during project validation** (`rasa data validate`, packaging):

| Problem | What you see |
| - | - |
| Empty list, mapping, or scalar instead of a variant list | Finding with code `mantle.validation.response.invalid_variant_shape`, plus file path and response name |
| Unknown variant keys (e.g. `channel:`, typos like `conditon:`) | Finding with code `mantle.validation.response.invalid_variant_key`, plus file path, response name, and variant index |
| Empty text with no `custom` object | Finding with code `mantle.validation.response.empty_body`, plus file path, response name, and variant index |
| `custom` that is not a JSON object | Finding with code `mantle.validation.response.invalid_custom`, plus file path, response name, and variant index |
| Bad conditions, memory refs, default rules | Finding with code `mantle.validation.response.*`, plus file path, response name, and variant index |
| Malformed `buttons`, invalid `set:` payloads, non-writable targets | Finding with code `mantle.validation.response.invalid_button_payload`, `mantle.validation.response.not_writable_memory_key`, or related codes, plus button index |
| A confirmation question with a button that is not `set:session.system.confirmation=true` or `set:session.system.confirmation=false`, or that key on any other response | Finding with code `mantle.validation.response.invalid_confirmation_button`, plus file path, response name, and button index |
| Missing, MCP, or confirmation-gated dynamic button source | Finding with code `mantle.validation.response.*_button_source_tool`, plus file path, response name, variant index, and observing skill |
| Project-root response with `buttons.source` that no skill references | Finding with code `mantle.validation.response.unbound_button_source`, plus file path, response name, and variant index. A sourced project response must have at least one observing skill |

All project `responses.yml` files are checked; findings accumulate across files.

**Runtime model load** (packaged agent) still uses strict registry parsing.
Unknown variant keys there raise `ValidationError` with code
`responses.registry.invalid_variant` and stop loading that file.

### Unsupported variant keys

Permitted keys on a variant are `text`, `metadata`, `condition`, `buttons`, and
`custom`. `channel:` is **not** supported — adding it is reported at project
validation time and causes strict registry load to fail at runtime.

## Custom JSON

Add an optional `custom:` object on a variant to send channel-specific JSON
with the response. Mantle does not interpret the object. It stores a copy on
`BotUttered.data["custom"]` and delivers it through the channel's existing
custom-JSON path. Inspector shows that object on the agent message.

The value must be a JSON object, meaning a mapping such as
`{type: card_ordered}`. An empty mapping `{}` is allowed. A list is valid JSON
and is still rejected, including a list of objects such as `[{}]`. A string,
number, boolean, or `null` is rejected the same way. `rasa train` and
`rasa data validate` report that shape. Strict load raises
`responses.registry.invalid_variant` and stops loading the file.

An unquoted YAML date or timestamp, including one nested in an object or a
list, is stored as an ISO-8601 string. Quote the value when you want to keep a
different format.

`text` may be empty or whitespace only when `custom` is an object. A variant
with neither non-whitespace text nor a custom object still fails validation.

String values inside the object, including values nested in objects and lists,
use the same `{session.<namespace>.<entry>}` and `{entry}` placeholders as
`text`. Keys, numbers, booleans, and `null` stay as written. A value inserted
from memory is not scanned for further placeholders.

> [!WARNING]
>
> `custom` is stored on the tracker event and sent to the channel client.
> `modify_outgoing_message` does not inspect or redact it. Do not interpolate
> secrets, tokens, or other sensitive memory values into this object.

`metadata.rephrase` rewrites the response `text` only. The custom object is the
substituted JSON, not a reworded copy. When the text has no non-whitespace
characters, Mantle skips the rephrase call and still delivers the object.
`modify_outgoing_message` is the same: it rewrites `text` only and leaves
`custom` unchanged unless it raises `HookRejection`, which drops the draft
object.

On a streaming channel the text is streamed once. The custom object is sent
afterward with no text, the same way buttons are, so the client attaches it
to the utterance just streamed.

An empty object `{}` is stored on the event. The channel does not send it.

The generic voice channel does not read the JSON aloud. It suppresses custom
JSON the same way it does for any other custom payload. Channels that already
forward custom JSON still receive the object.

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_card_replace_completed:
    - text: >-
        All set. Your replacement card has been ordered and will ship via
        {session.card_replace.order_shipping_summary} delivery.
      custom:
        type: card_replacement_ordered
        shipping: "{session.card_replace.order_shipping_summary}"
        reason: "{session.card_replace.replacement_reason}"
        expedited: false
  utter_card_status:
    - text: ""
      custom:
        widget: card_status
        shipping: "{session.card_replace.order_shipping_summary}"
```

## Static buttons

Add an optional `buttons:` list on a variant to show tap targets with the
response. Buttons are delivered on **collect asks** (`utterance:`), **action**
steps (`utter:`), and **confirmation** prompts (`requires_confirmation`).
Inspector and other channels that render `BotUttered.data["buttons"]` show them
on the ask; voice channels may summarize buttons in a compact format.

Each button is a mapping with:

| Key | Required | Description |
| - | - | - |
| `title` | yes | Label shown on the button. Supports the same `{session.<namespace>.<entry>}` and `{entry}` placeholders as `text`. |
| `payload` | no | String sent when the customer taps the button. When omitted, the engine uses the **resolved title** (after placeholder substitution) as the payload. |

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_ask_shipping_type:
    - text: Choose shipping for {session.card_disambiguate.selected_card_label}.
      metadata:
        rephrase: true
      buttons:
        - title: Rush for {session.card_disambiguate.selected_card_label}
          payload: set:session.card_replace.shipping_type=rush
        - title: Standard for {session.card_disambiguate.selected_card_label}
          payload: set:session.card_replace.shipping_type=standard
    - text: Would you like rush or standard shipping?
      metadata:
        rephrase: true
      buttons:
        - title: Rush
          payload: set:session.card_replace.shipping_type=rush
        - title: Standard
          payload: standard
```

At delivery the engine resolves placeholders in each `title` and `payload` from
readable memory, then attaches the wired buttons to the bot message and the
output channel.

### Plain-text payloads

When `payload` does **not** start with `set:`, a tap is handled like the
customer typed that string — the orchestrator runs and the LLM may call
`set_memory` or interpret the text. On a **collect** step this is the path for
legacy-style buttons whose payload is the value itself (for example `standard`).

Use plain-text payloads when you want the model to handle ambiguity or follow-up
questions. Use the confirmation payloads below so a tap skips the yes/no call.
Use any other `set:` payload when the tap should write memory deterministically.

### Confirmation payloads

On the response given as `utter_for_confirmation` — a tool gate or cancel — these
two payloads agree or decline the pending tool without a model call, and
without writing a memory field:

```text theme={null}
set:session.system.confirmation=true
set:session.system.confirmation=false
```

`true` runs the stored tool. `false` cancels it. The values are exactly
`true` and `false`, and this key is not a memory field you declare.

A tap counts only when that button is on the latest agent message and a
confirmation is still pending. On the static buttons of that question, use
only these two payloads. Several buttons may share one of them. A question
with no buttons stays valid. Do not use this key on any other response.
`rasa train` rejects any other static button on that question, and this key
anywhere else. `buttons.source` is not part of that check: a source button
with another payload is ordinary text.

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_ask_replacement_confirmation:
    - text: Replace this card and ship it {session.card_replace.shipping_type}?
      buttons:
        - title: Yes, replace it
          payload: "set:session.system.confirmation=true"
        - title: No, keep it
          payload: "set:session.system.confirmation=false"
```

### Set-memory payloads

When `payload` starts with `set:`, it must match:

```text theme={null}
set:session.<skill_id>.<entry_name>=<value>
set:session.project.<entry_name>=<value>
```

The value is everything after the **first** `=` (values may contain `=`).

Examples:

```yaml theme={null}
payload: set:session.card_replace.shipping_type=express
payload: set:session.sim_management.wants_to_block=false
```

`rasa train` validates each `set:` payload against the same rules the engine
uses at tap time:

* The memory key must be a **declared** field that the owning skill (or, for
  project-root responses, every skill that **references** that response) is
  allowed to write — the skill's own fields or project memory. Button taps are
  engine writes, so **`llm_settable` is not required** (unlike LLM
  `set_memory`).
* Placeholders in titles must reference **readable** memory for that observing
  skill.
* For **categorical** targets, `<value>` must be one of the declared
  `enum_values`.

The payload value is always a string after the first `=`. At runtime the
engine coerces it to the field type:

| Field type | Payload value |
| - | - |
| `text`, `any`, and other untyped strings | Used as-is |
| `bool`, `int`, `float` | Parsed as that scalar; a value that cannot be coerced is stale |
| `categorical` | Must match a declared `enum_values` entry |
| `list` | Must be a JSON array (for example `["rush","vip"]`) |
| `json` | Must be valid JSON |

At runtime a `set:` tap **writes memory directly** (no LLM `set_memory` call)
when all of these hold:

* The payload appears on the **latest** agent message's buttons (older or
  forged `set:` text is stale).
* The target is writable for the **active** skill (or `project.`).
* The field exists and the value coerces to its type.

The channel still records a user utterance whose text is the raw `set:`
string. That string stays out of the LLM prompt. On a successful tap the user
line is the sanitized `button_title` when the channel sent one, and a system
instruction says the tap already stored that field and that the model must not
call `set_memory` for it. With no title there is no user line; the
instruction still names the field. Collect steps advance because memory was
written after the ask — not because the model interpreted the tap as an answer.
Later turns show the button label for that tap, not the payload and not the
instruction. The filled value is also in the Memory section.

Behavior by scope:

| Payload shape | Write rule |
| - | - |
| `set:session.<active_skill>.<entry>=…` | Writes while that skill is active. [Memory validation tools](https://mantle.rasa.com/reference/tools.md#memory-validation-tools) for that entry run the same way as after `set_memory`. |
| `set:session.project.<entry>=…` | Always writes **project** memory (write-once unless [`mutable: true`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by); [`writable_by`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by) when set). Even if the active skill also defines `<entry>`, the tap still updates `project.<entry>`, not the skill field. |
| `set:session.<other_skill>.<entry>=…`, payload not on the latest agent message, not writable for the active skill, no active scope, missing field, value that fails coerce, a project field already set without `mutable: true`, or a project write from a skill not in `writable_by` | **Skipped**. The engine utters the packaged default `utter_set_memory_button_skipped` (overridable), does **not** call the LLM, and ends the turn. |

[`run_after_setting_<entry>` memory validation tools](https://mantle.rasa.com/reference/tools#memory-validation-tools)
run after a successful write, including when the field is **not** `llm_settable`.
`rasa train` only accepts that tool when `<entry>` is `llm_settable` or owned by
a `collect:` step — so collect shortcuts can have one; a field that is only
button-writable cannot declare one. Tools named after **project** fields are
invalid at train (project is not LLM-writable); write `project.*` from a
skill-field memory validation tool or another tool instead.

If a memory validation tool rejects the write, the write is rolled back and
collect does not advance. The LLM may still respond (for example to explain the
failure) using the button title when the channel supplies it, not the raw
`set:` string. A listed button can still fail at runtime when a memory
validation tool rejects the value even though train-time validation passed —
design the tool and the copy accordingly.

Malformed `set:` shapes (prefix `set:` but not the grammar above) fall back to
the button title for LLM interpretation when the channel provides
`button_title` metadata; without a title the engine utters
`utter_set_memory_button_skipped` and does not call the LLM.

### Inbound `button_title` metadata

Channels that deliver button taps should put the visible label on the inbound
user message as metadata key **`button_title`** (a non-empty string). The engine
reads that key when:

* Filling `{button_title}` in `utter_set_memory_button_skipped` (when the title is
  missing, the quoted `{button_title}` token is dropped so the sentence stays
  grammatical — for example `That selection is no longer available…`)
* Substituting the title for the raw `set:` string after a successful write,
  after a memory validation tool rejects the write, or after a malformed `set:`
  payload that has a title, so the LLM sees the label and not the payload.
  A successful write also adds a system instruction that the field is already
  stored. Later turns keep the label in history and drop that instruction.

If your channel does not forward `button_title`, skip notices still fire.
A successful write without a title still adds the stored-field instruction and
omits the user line. A rejected write without a title still calls the LLM with
the user text omitted from the prompt.

### Stale-button default response

Packaged system defaults include `utter_set_memory_button_skipped`. It is also
listed under [Other packaged responses](https://mantle.rasa.com/reference/builtin-skills.md#other-packaged-responses).
Rephrase is off on the packaged default so untrusted button titles are not sent
to an LLM:

```yaml theme={null}
responses:
  utter_set_memory_button_skipped:
    - text: "That selection '{button_title}' is no longer available or an invalid value. Please choose an available option or type your message."
```

Override it like any other built-in by declaring the same name in your
project-root or skill `responses.yml`. Keep a `{button_title}` placeholder if
you want the channel-supplied label in the notice.

### Incoming-message reject default response

Packaged system defaults include `utter_incoming_message_rejected`. The engine
sends it when `modify_incoming_message` crashes or times out. It is also used
when `HookRejection` omits `response_message`, names a response that is not
defined, or names a response whose conditioned variants all miss. Rephrase is
off on the packaged default:

```yaml theme={null}
responses:
  utter_incoming_message_rejected:
    - text: "I'm sorry, but I can't process that message. Please try again."
```

Override it by declaring the same name in your project-root `responses.yml`.
For rejection-specific copy, define another response and pass its name—not
free-form text—to
`HookRejection(response_message="utter_message_rejected", reason="...")`.
Named reject replies are resolved against the logged tracker the same way as
other responses: conditioned variants, `{session.*}` placeholders, and static
buttons apply. LLM rephrase is skipped because the orchestrator does not run.

### Outgoing-text reject default response

Packaged system defaults include `utter_outgoing_message_rejected`. The engine
sends it when `modify_outgoing_message` raises `HookRejection` without a usable
`response_message`. Rephrase is off on the packaged default:

```yaml theme={null}
responses:
  utter_outgoing_message_rejected:
    - text: "I'm sorry, but I can't provide that response. Please try again."
```

Override it by declaring the same name in your project-root `responses.yml`.
For rejection-specific copy, pass a response name to
`HookRejection(response_message="utter_response_blocked", reason="...")`.

## Turn-error fallbacks

When Mantle must abort a turn because a fail-closed modify hook crashed or
timed out, the main model call failed, or the turn reached the iteration limit,
it speaks a packaged response. These names are also listed under
[Other packaged responses](https://mantle.rasa.com/reference/builtin-skills.md#other-packaged-responses).

| Failure | Response name |
| - | - |
| `modify_model_request` crash/timeout | `utter_model_request_hook_error` |
| `modify_tool_call` crash/timeout | `utter_tool_call_hook_error` |
| Unexpected main model call failure | `utter_model_call_error` |
| Turn reached the iteration limit (for example, a hook keeps raising `RetryModel`) | `utter_model_call_error` |
| The model repeated a tool request the engine had already refused, or an identical request that succeeded without changing anything | `utter_could_not_finish` |

```yaml theme={null}
responses:
  utter_model_request_hook_error:
    - text: "I'm sorry, but something went wrong. Please try again."
  utter_tool_call_hook_error:
    - text: "I'm sorry, but something went wrong. Please try again."
  utter_model_call_error:
    - text: "I'm sorry, but something went wrong. Please try again."
  utter_could_not_finish:
    - text: "I'm sorry, I wasn't able to do that. What else can I help you with?"
```

Override any of these names in your own `responses.yml`. The exception text is
never included. If a name is missing, no variant matches, or the matching
variant's text is empty, whitespace, or only the response name, Mantle speaks
the packaged sentence above. A `custom` object on that variant is still
delivered.

> [!NOTE]
>
> The packaged turn-error responses do not enable rephrasing. They are always
> spoken as written unless you opt in, and only one case accepts the opt-in:
>
> * When the turn reaches the iteration limit, Mantle honours `metadata.rephrase`
>   on your `utter_model_call_error` variant. With `rephrase: true` the text is
>   reworded once, with no tools, and is spoken as written if that call fails.
> * For hook crashes, model-call failures, and `utter_could_not_finish`,
>   `metadata.rephrase` is ignored. `utter_could_not_finish` is the line spoken
>   when a repeated tool request will not make progress. A hook that never lets
>   the call run still reaches the iteration limit and uses
>   `utter_model_call_error`.
>
> ```yaml theme={null}
> responses:
>   utter_model_call_error:
>     - text: "I'm sorry, I couldn't finish that. Please try again."
>       metadata:
>         rephrase: true
> ```

Other hooks do not use the hook-error responses: fail-open points keep the last
good payload, knowledge-query failures skip the search and continue the turn,
and `HookRejection` / `RetryModel` keep their own contracts.

## Dynamic buttons

Use a local source tool when the choices are only known at delivery time. The
variant names the tool instead of declaring a static list:

```yaml skills/delivery/responses.yml theme={null}
responses:
  utter_ask_delivery_window:
    - text: Which delivery window works for you?
      buttons:
        source: list_delivery_windows
```

The source tool calls `context.set_buttons()` with `Button` values:

```python skills/delivery/tools.py theme={null}
from rasa.mantle.tools.buttons import Button
from rasa.mantle.tools.decorator import ToolContext, tool
from rasa.mantle.tools.result import ToolResult


@tool(description="List the delivery windows available for this order.")
async def list_delivery_windows(context: ToolContext) -> ToolResult:
    await context.send("Looking up available delivery windows.")
    context.set_buttons(
        [
            Button(
                title="Tomorrow morning",
                value="tomorrow_morning",
                ref="session.delivery.delivery_window",
            ),
            Button(
                title="Tomorrow afternoon",
                value="tomorrow_afternoon",
                ref="session.delivery.delivery_window",
            ),
            Button(title="Show later dates", value="later"),
        ]
    )
    return ToolResult(llm_response={"count": 3})
```

`Button` fields control the tap payload:

| Field | Required | Behavior |
| - | - | - |
| `title` | yes | Label shown on the button. |
| `value` | no | Value sent on tap. Defaults to `title` when `ref` is omitted. |
| `ref` | no | Fully qualified writable memory reference. When present, the payload becomes `set:<ref>=<value>` and `value` is required. |

One `set_buttons()` call may mix memory-writing and plain-text buttons, as in
the example. Calling it again replaces the previous list. The source buffer
applies only to the named response: a message emitted with `context.send()`
remains a separate message without those buttons.

Source tools are engine-only. They are omitted from the LLM tool schemas and a
direct model-authored call is rejected. `rasa train` also requires a source to:

* resolve to a local tool for the owning skill, or for every skill that
  references a project-root response
* not be an MCP tool
* not use `requires_confirmation`

When a source fails, supplies no buttons, or supplies only invalid buttons, the
response text is still sent without buttons. Invalid items are skipped
individually, so valid siblings remain. This includes malformed buttons and
`ref` values that are unknown or not writable by the active skill.

> [!WARNING]
>
> A variant's `buttons:` value is either a static list or a `{source: ...}`
> mapping. Put mixed static and runtime choices in the source tool's single
> `set_buttons()` call; they cannot be mixed in YAML.

## Where the file lives

| Location | Scope |
| - | - |
| `skills/<id>/responses.yml` | Declared by that skill |
| `responses.yml` at the agent root | Declared project-wide |

At load, every file is merged into **one flat registry**, later sources
overriding earlier ones on duplicate names:

1. Packaged system defaults
2. Each bundled default skill's `responses.yml`
3. Each project skill's `responses.yml`, in directory order
4. The project-root `responses.yml`

This is how you override a built-in message: declare the same response name in
your own file. Redefining `utter_silence_timeout_check_in`, for example, replaces
the check-in the bundled `builtin_silence_timeout` skill delivers. The same merge
order applies to `utter_set_memory_button_skipped` and the turn-error
fallbacks (`utter_model_request_hook_error`, `utter_tool_call_hook_error`,
`utter_model_call_error`).

The bundled `builtin_session_start` skill has no greeting response. To greet,
override the skill as described in
[Start a conversation](https://mantle.rasa.com/mantle/runtime-loop.md#start-a-conversation).

Because the registry is flat, response names are global rather than scoped to
the skill that declares them. Prefix names with the skill (`utter_card_replace_completed`)
so two skills keep their wording distinct.

## Interpolation

A placeholder in braces is replaced with a memory value at delivery time. Two
forms work, and they resolve differently:

| Placeholder | Resolves against |
| - | - |
| `{session.<namespace>.<entry>}` | Everything the active skill can read: its own fields, other skills' `public` fields, and project memory |
| `{entry}` | The active skill's own schema first, then project memory |

```yaml theme={null}
utter_confirm_order:
  - text: |
      Card: {session.card_disambiguation.selected_card_label}
      Reason: {session.card_replace.replacement_reason}
      Shall I place the order?
```

Use the namespaced form to read another skill's `public` field. The bare form is
convenient for a skill's own entries and follows the same resolution order a
tool's `context.memory.get()` uses.

A placeholder whose value is unset at delivery time is left in the text as
written, so interpolate only values you know are set by the time the response is
sent, typically ones written earlier in the same ordered block.

Interpolation applies to responses. For live values in `skill.md` instruction
prose, use `@memory.…` instead — see [skill.md](https://mantle.rasa.com/reference/skill-md.md). Do not
put bare `session.*` in free prose; train fails and points you at `@memory`.

### `metadata.rephrase`

A response may opt into being reworded by the LLM instead of delivered verbatim:

```yaml theme={null}
responses:
  utter_ask_shipping:
    - text: "Rush or standard shipping?"
      metadata:
        rephrase: true
```

With `rephrase: true` the orchestrator makes a tool-free LLM call to reword the
**selected** variant's text in context, and falls back to the literal text if
that call fails or comes back empty. A `custom` object on that variant is not
sent to the rephrase call. Leave rephrase off (the default) for anything
compliance-sensitive: that is the entire point of declaring the response.

### Variant metadata

Every key under `metadata` on the selected variant is stored on the
`BotUttered` event for that delivery (for example `variant_id` for channel
routing). The engine adds its own keys (`utter_action`, `mantle_response_source`,
timing); those **win** if a name collides with authoring metadata. `prompts` and
`domain_ground_truth` are reserved for
[recorded prompts](https://mantle.rasa.com/reference/integrations-yml.md#event_broker) and are dropped
with a warning.

Buttons on the variant are independent of `metadata` — declare them on the
variant root as `buttons:` (see [Static buttons](#static-buttons)).

## How a response is delivered

Four things reference a response by name:

| Reference | Where it is declared | Delivered when |
| - | - | - |
| `utter:` trigger | `skill.md` frontmatter | The skill activates (`on: activate`), or a `when:` condition first becomes true |
| `on_success:` / `on_failure:` | A `tool_constraints` entry | After that tool succeeds or fails |
| `utter_for_confirmation` / `utter_on_user_denial` | A `requires_confirmation:` mapping | When the engine asks for approval, and when the customer declines |
| `utter:` / `utterance:` | An ordered-block step | The step runs |

The two step fields differ:

```yaml theme={null}
:::ordered_block id=main
steps:
  - id: present_cards
    utter: utter_present_card_list      # deliver the response, then advance
    next: collect_card

  - id: collect_card
    collect: selected_card_label
    utterance: utter_ask_which_card      # the question for a collect step
:::
```

| Step field | Use |
| - | - |
| `utter: utter_<name>` | Deliver the response, then advance |
| `utterance: utter_<name>` | On a `collect:` step, the question asked for that value |

`action:` on a step fails to load. Write `utter:` instead. Skill frontmatter
`utter:` is a different key: a list of verbatim triggers, not this step.

`rasa train` validates every response name referenced from any of the four
places above, and runs per-variant checks on project-authored `responses.yml`
files (text or a custom object, valid conditions, default-variant rules). A
name that is not in the registry, or a malformed variant list, is caught
before the agent runs.

## See also

* [Responses concept](https://mantle.rasa.com/concepts/responses.md): when to declare wording
* [skill.md](https://mantle.rasa.com/reference/skill-md.md): the `utter:` trigger and `tool_constraints` shapes
* [Ordered block steps](https://mantle.rasa.com/reference/ordered-block-steps.md): the step fields that deliver responses (including collect asks with buttons)
* [Conditions](https://mantle.rasa.com/reference/conditions.md): the namespaced reference form


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