responses.yml - Rasa Documentation

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.

skills/card_replace/responses.yml

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

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 as skill requires: and prose if: lines.

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:

Skip variants with no condition during this pass.
For each conditioned variant, evaluate its condition against readable memory. The first variant whose condition is true is delivered.
If none match, deliver the default variant — the one that omits condition.
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.

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 any variant
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 (`channel:`, `buttons:`, typos like `conditon:`)	Finding with code `mantle.validation.response.invalid_variant_key`, plus file path, response name, and variant index
Empty text, bad conditions, memory refs, default rules	Finding with code `mantle.validation.response.*`, plus file path, response name, and variant 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

Only text, metadata, condition, and buttons are permitted on a variant. channel: is not supported in this release. Adding it is reported at project validation time and causes strict registry load to fail at runtime. See Dynamic buttons for the accepted buttons: shape.

Dynamic buttons

Use a local source tool when the tap targets are only known at delivery time. The variant names the tool instead of listing choices inline:

skills/delivery/responses.yml

responses:
  utter_ask_delivery_window:
    - text: Which delivery window works for you?
      buttons:
        source: list_delivery_windows

The source tool builds the buttons and hands them back with context.set_buttons():

skills/delivery/tools.py

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:
    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 decide 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 (`session.<skill\|project>.<entry>`). With `ref`, the engine writes `value` to that field on tap and no `set_fields` LLM call is needed. `value` is required when `ref` is set.

One set_buttons() call may mix memory-writing (ref) and plain-text buttons, as in the example. Calling set_buttons() again inside the same tool invocation replaces the previously supplied list. Messages the tool emits with context.send() remain separate and carry no buttons. Source tools are internal to the engine:

the engine omits them from the LLM tool schemas, so the model cannot dispatch them directly
rasa train requires each source to resolve to a local tool for the owning skill, or for every skill that references a project-root response
rasa train rejects MCP tools and tools with requires_confirmation as sources

At delivery, the engine still sends the response text when the source is unavailable. This covers:

the source tool is missing at runtime
a barge-in cancels the invocation, it times out, or it raises
the tool returns no buttons, or every button it returned is invalid

The engine drops invalid entries individually, so valid siblings survive. A ref that is unknown or not writable by the active skill counts as invalid. The engine logs it and skips the button rather than propagating the error.

A variant’s buttons: value is either a static list or a {source: ...} mapping, never both. Put mixed static and runtime choices in the source tool’s single set_buttons() call.

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:

Packaged system defaults
Each bundled default skill’s responses.yml
Each project skill’s responses.yml, in directory order
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 default_silence_timeout skill delivers. The bundled default_session_start skill has no greeting response. To greet, override the skill as described in 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

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

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. Leave it off (the default) for anything compliance-sensitive: that is the entire point of declaring the response.

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
`action:` / `utterance:`	An ordered-block step	The step runs

The two step fields differ:

:::ordered_block id=main
steps:
  - id: present_cards
    action: 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
`action: utter_<name>`	Deliver the response, then advance
`utterance: utter_<name>`	On a `collect:` step, the question asked for that value

utter: is accepted as a step-level alias for action: and is normalised at load. Prefer action:. 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 (non-empty text, valid conditions, default-variant rules). A name that is not in the registry, or a malformed variant list, is caught before the agent runs.

​Conditional variants

​How a variant is selected

​Default variant rules

​Unsupported variant keys

​Dynamic buttons

​Where the file lives

​Interpolation

​metadata.rephrase

​How a response is delivered

​See also

Conditional variants

How a variant is selected

Default variant rules

Unsupported variant keys

Dynamic buttons

Where the file lives

Interpolation

`metadata.rephrase`

How a response is delivered

See also