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

> Pre-defined wording the framework delivers without the LLM.

Some moments need specific wording: a recording notice at the start of a call, a
fraud warning when a card is reported stolen, a legal disclaimer after a
transaction. Responses let you declare that text once in `responses.yml` and
have the framework deliver it exactly as written. The LLM never rewrites it.

## Defining responses

Response text lives in the skill's `responses.yml`:

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_recording_notice:
    - text: >-
        This interaction may be recorded for quality assurance
        and training purposes.

  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: >-
        Your replacement card has been ordered and will ship via
        {session.card_replace.order_shipping_summary} delivery.
```

Each name maps to a **list of variants**. At delivery the engine picks **one**
variant: the first whose `condition` is true (YAML order), or the single
**default** variant with no `condition` when none match.

Placeholders in braces are filled from memory at the moment the message is sent.
Use `{session.<skill_id>.<entry>}` or `{session.project.<entry>}` to read any
value the skill can see, or the short `{entry}` form for the skill's own values.
Interpolate only values you know are set by then: a placeholder with no value is
left in the text as written.

### Conditional wording

Add `condition` on a variant when the message should change with session
memory — for example, different replacement-fee copy for lost vs stolen cards.
When any variant is conditioned, exactly one variant must omit `condition` (the
fallback). That fallback may sit anywhere in the list.

This is different from a skill `utter:` trigger with `when:` in `skill.md`:
`when:` fires a **whole response** once when memory first becomes true;
`condition` on a variant picks **which wording** to deliver each time a
reference (utter step, collect ask, tool outcome, confirmation prompt, etc.)
resolves that response name. Both use the same [condition expression grammar](https://mantle.rasa.com/reference/conditions.md).

See the [`responses.yml` reference](https://mantle.rasa.com/reference/responses-yml#conditional-variants)
for selection order, train-time validation, static buttons, and unsupported keys.

## Delivering a response

Four things can fire a response, and which one you reach for depends on what the
wording is tied to.

**On skill activation, or when a value becomes true.** A frontmatter `utter:`
trigger. This is the one that needs no ordered block:

```markdown skills/card_replace/skill.md theme={null}
---
name: Card Replace
description: Replace a credit card that was lost, stolen, damaged, or not received

utter:
  - utter_recording_notice:
      on: activate
  - utter_stolen_warning:
      when: "session.card_replace.replacement_reason == 'stolen'"
---

Help the customer replace a credit card.
```

`on: activate` fires once when the skill becomes active. `when:` fires the first
time its condition becomes true after a memory write, so a warning tied to a
value lands the moment that value is recorded, wherever in the conversation that
happens.

> [!WARNING]
>
> `on: activate` resolves response variants **after** that skill's memory is
> reset for the new run. A conditional variant that reads the skill's own fields
> usually misses (those fields are back at `initial_value` / `null`) and you get
> the default wording. Prefer **project memory** or a matching skill-field
> `initial_value` for activation CRVs; use `when:` when the value is written
> after the skill starts. See
> [Conditional variants](https://mantle.rasa.com/reference/responses-yml.md#conditional-variants).

**Around a tool call.** `on_success:` and `on_failure:` on a `tool_constraints`
entry deliver a response after the tool runs, and `requires_confirmation:` names
the approval question and the line for a declined one. Do not also ask for that
approval in skill prose — the engine already asks. See
[Tool Constraints](https://mantle.rasa.com/build-guide/tool-constraints.md).

**At a fixed point in a sequence.** Ordered-block steps:

```yaml theme={null}
:::ordered_block id=main
steps:
  - id: notice
    utter: utter_recording_notice        # say it, then move on

  - id: ask_shipping
    collect: shipping_type
    utterance: utter_ask_shipping         # the question for this value
:::
```

`utter:` delivers the response and advances. `utterance:` on a `collect:` step
is the question asked for that value.

## When to use a response

Reach for one when the wording is a business requirement: compliance, legal,
brand-mandated disclosures. Use it when *the exact words* are the point.

On voice, a response is also the safe way to read out a value the caller must
hear exactly, such as an order number or a reference. The model can paraphrase
or round a value it restates; a placeholder in a response cannot. See
[Designing for voice](https://mantle.rasa.com/voice/designing-for-voice.md#use-exact-wording-for-numbers-that-must-be-right).

For everything else, let the LLM phrase things from your
[instructions](https://mantle.rasa.com/concepts/instructions.md). Declaring every message as a response
produces an agent that sounds like a scripted phone tree, which is the thing
Mantle exists to avoid.

If you want declared text that still adapts to context, a response can opt into
LLM rewording:

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

Rephrase applies to **whichever variant is selected** at delivery, not always
the first variant. Do not set this on anything compliance-sensitive.

## Static buttons

Variants may declare a `buttons:` list so collect asks, utter steps, and
confirmation prompts show tap targets alongside the response text. Each button
has a `title` (required) and an optional `payload`. Placeholders in titles and
payloads resolve from memory at delivery the same way as in `text`.

* **Plain-text payload** (or no payload — then the resolved title is used):
  treated like typed user input. The LLM can call `set_memory` on a collect
  step.
* **Confirmation payload** (`set:session.system.confirmation=true` or
  `=false`): on the confirmation question only. A tap agrees or declines
  without a model call and without writing a memory field. Any other button
  on that question is rejected at train time. See
  [Explicit confirmations](https://mantle.rasa.com/build-guide/tool-constraints.md#explicit-confirmations).
* **`set:` payload** (`set:session.<skill|project>.<entry>=<value>`): on tap,
  the engine writes memory itself (`llm_settable` not required), runs
  [memory validation tools](https://mantle.rasa.com/reference/tools.md#memory-validation-tools), and does
  **not** put the raw payload in the LLM prompt. The tap turn's user line is
  the button label when the channel sent `button_title`, plus a system
  instruction that the field is already stored. Later turns show that label,
  not the payload and not the instruction.
  Prefer this for deterministic collect shortcuts. A successful tap still
  stores a user utterance on the tracker (the raw `set:` string); the engine
  then continues the turn, so a collect whose field was just written advances
  without asking the LLM to record the answer.
  * If the tap is stale, not writable, or the value cannot be applied, the
    engine utters the packaged default `utter_set_memory_button_skipped`
    (overridable; rephrase is off on the packaged copy) and ends the turn
    without calling the LLM.
  * Channels should send the visible label as inbound metadata `button_title`
    so that notice can name the button.

Train-time validation checks button shape, readable placeholders, `set:`
targets against button-writable memory (declared own-skill and project
fields), and that `set:session.system.confirmation=true` / `false` appear
only on a confirmation question. See
[Static buttons](https://mantle.rasa.com/reference/responses-yml.md#static-buttons) for
payload grammar, stale-notice behavior, `button_title` metadata, and
memory validation tools.

## Dynamic buttons

When choices depend on live data, set `buttons: {source: <tool_name>}` on the
response variant. The engine runs that local tool at delivery time, and the
tool supplies the choices with `context.set_buttons([Button(...)])`.

A `Button` with `ref` writes its `value` to that fully qualified memory field
on tap. A button without `ref` sends `value`, or its `title` when no value is
set, as plain user input. One call can mix both kinds.

Button-source tools are internal to the engine: they are hidden from the LLM
and cannot require confirmation or come from MCP. If the source fails or
supplies no valid choices, the response text is still delivered without
buttons.

See [Dynamic buttons](https://mantle.rasa.com/reference/responses-yml.md#dynamic-buttons) for the YAML and
Python example, validation rules, and failure behavior.

## Overriding built-in messages

Bundled skills and a few packaged responses ship default wording. The full
list, including when each message is sent, is located in
[Builtin skills](https://mantle.rasa.com/reference/builtin-skills.md).

Every `responses.yml` merges into one registry keyed by name, so declaring a
name in your project-root file replaces the built-in one:

```yaml responses.yml theme={null}
responses:
  utter_silence_timeout_check_in:
    - text: "Still there? Tell me how I can help."
```

Session start is different: the bundled skill has no greeting to override. To
make the agent speak first, replace the skill itself — see
[Start a conversation](https://mantle.rasa.com/mantle/runtime-loop.md#start-a-conversation).

That shared registry is also why response names are worth prefixing with the
skill they belong to.

## Reference

For the merge order, both interpolation forms, conditional variants, and every
field, see the [`responses.yml` reference](https://mantle.rasa.com/reference/responses-yml).


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