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

# Ordered block steps

> Step kinds, step fields, implicit next, and conditional branching.

An ordered block is a `steps:` list inside a `:::ordered_block id=<id>` fence in
`skill.md`. The block has no `description`. Routing lists the skill id and the
skill description. This page lists every step kind. When to use a block, and
the one-entry rule for a fully guided skill, are in
[Ordered Blocks](https://mantle.rasa.com/build-guide/ordered-blocks.md).

## Step kinds

The kind is inferred from which key the step carries.

| Key | Kind | What happens |
| - | - | - |
| `instructions:` | Conversational | The LLM converses within the step. Pair with `complete_when:` |
| `collect:` | Collect | The framework collects one memory entry from the user |
| `utter:` | Utter | Deliver an `utter_*` response. Any other name is rejected. |
| `execute_tool:` | Execute | The framework calls the tool directly, without the LLM. `listen` waits for the user, and `hangup` ends the conversation. |
| `noop: true` | Route | Evaluate `next:` branches and jump, with no user-visible effect |
| `set_memory:` | Set memory | Write literal values to memory keys (project writes follow [`mutable` / `writable_by`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by)) |
| `call:` | Call | Run another block or skill, then return to this step's `next` |
| `link:` | Link | Hand off to another skill or ordered block and continue there |
| `id: END` | End | Terminate the block |

## Step fields

| Field | Applies to | Description |
| - | - | - |
| `id` | all | Step identifier, unique within the block |
| `next` | all but `noop:` / `link:` | A step id, or a list of conditional branches |
| `complete_when` | `instructions:` | Condition that ends the step |
| `optional` | `instructions:` | The step may be skipped |
| `utterance` | `collect:` | Response name used to ask for the value. When that response variant declares `buttons:`, they are delivered with the ask. A `set:` payload on those buttons writes the collect field and advances this step without an LLM `set_memory` call (see [Static buttons](https://mantle.rasa.com/reference/responses-yml.md#static-buttons)). When the field is empty after a new run's reset, the question is asked again; a previous run's question and reply do not count. After the question has been delivered in the current run, a side question or a confirmed return from another skill asks it again with its buttons; see the note below. A field that already has a value, including a non-empty default, is skipped unless `ask_before_filling` is set. |
| `description` | `collect:` | What the value means, shown to the model. Optional. When a description is set, it wins over the memory-field description. State the expected format (for example, "16-digit card number") so the agent can tell when a voice answer is unfinished and wait for the rest. |
| `ask_before_filling` | `collect:` | A value written by the block, such as an initial value, can already be set and is still asked about. `activate` and `set_memory` do not store this field until that question has been asked. Until that answer is written after the question, tool gates and `next:` branches in that block treat the field as unset. Other blocks in the same skill see the stored value, including an initial value. Correcting an earlier answer asks this question again, including when it was still waiting; a value offered with the correction is not treated as the answer. |
| `dtmf` | `collect:` | Accept phone keypad input for this step on voice channels. See [DTMF](#dtmf) |
| `parameters` | `execute_tool:` | Arguments; `session.*` values resolve from memory. `listen`, `hangup`, and `record_handoff` take none. |

> [!NOTE]
>
> A `collect:` step names its question with **`utterance:`**; an `utter:` step
> names the response to deliver with **`utter:`**. Don't confuse this with the
> skill frontmatter `utter:` list, which fires verbatim responses on skill
> activation or when a memory condition first becomes true, with no ordered
> block. See [`skill.md` → `utter`](https://mantle.rasa.com/reference/skill-md#utter).

> [!NOTE]
>
> Once a `collect:` `utterance` has been delivered in the current run, the engine
> asks that response again, including its buttons (if configured), when a turn
> would otherwise leave the collect open after a message that was not its
> answer: after the model answers a side question in its own words, and after a
> return from another skill. A return counts once the model has handled the
> message that left the collect, or when the user taps a button on the resume
> question. `rephrase: true` can still change the wording; the buttons belong to
> this new ask. A tap on buttons from the earlier ask does not write the field.
>
> The question is not repeated when the user's message arrives before the ask
> was delivered, when that same turn writes the field, or when a typed return
> from another skill happens before the model has handled the message that left
> the collect. A skill already queued under this collect is the exception: the
> engine still asks, including before the first delivery. A collect with no
> `utterance` leaves the question to the model.

> [!NOTE]
>
> Two collect steps may fill the same field. The later step wins. A blank or
> whitespace description on that later step drops an earlier collect-step
> description, and the memory-field description is what the model sees. When the
> winning collect description has text, that text is what the model sees, and
> training warns if the memory field also has one. See
> [Memory](https://mantle.rasa.com/reference/memory-yml.md#llm_settable).

## Implicit `next`

A step with no `next` falls through to the step below it, and the last step
falls through to `END`. Add `next:` where you are branching or jumping
backwards.

## Conditional branching

A `next:` branch list routes on conditions, with `else:` as the fallback:

```yaml theme={null}
- id: gate_card_selected
  noop: true
  next:
    - if: "session.card_replace.selected_card_id"
      then: check_card_eligible
    - else: card_not_found
```

Branches are evaluated in order and the first match wins, so put `else:` last.

Conditions use the standard expression grammar. See
[Conditions](https://mantle.rasa.com/reference/conditions.md).

## How a block is entered

Routing lists skills, not blocks. How a block is reached follows from the shape
of the skill:

| Skill shape | Blocks are entered |
| - | - |
| Prose + blocks (hybrid) | From that skill's prose via `@block.<id>` |
| Blocks only (fully controlled) | `activate` with the skill id starts the one entry block; the other blocks are reached via `call:` / `link:` |

## DTMF

Add `dtmf:` to a `collect:` step to let a caller answer by pressing phone keys.
Keypresses count only while that step is active.

This block offers a keypad menu. `utter_ask_account_type` says "Press 1 for
checking, or 2 for savings", and one keypress picks the branch:

```yaml theme={null}
- id: collect_account_type
  collect: account_type
  utterance: utter_ask_account_type
  dtmf:
    length: 1
  next:
    - if: "session.account_balance.account_type == '1'"
      then: checking_balance
    - else: savings_balance
```

Declare the field as `categorical` with the keys as `enum_values`, so a key
outside the menu is rejected:

```yaml skills/account_balance/memory.yml theme={null}
schema:
  public:
    account_type:
      type: categorical
      enum_values: ["1", "2"]
      description: Account to check. 1 is checking, 2 is savings.
```

| Field | Type | Default | Description |
| - | - | - | - |
| `length` | int | none | Submit once this many keys are pressed |
| `finish_on_key` | string | none | Submit the keys pressed before this key, which is not stored. Quote `"#"` and `"*"` |
| `allow_audio_input` | bool | `true` | When `false`, speech is ignored while the step is active and recorded as a [`user_input_suppressed`](https://mantle.rasa.com/reference/events#suppressed-user-input) event |

Set exactly one of `length` or `finish_on_key`. Tell the caller in the
utterance which key ends the input, or that they must use the keypad.

The digits are converted to the field's [memory type](https://mantle.rasa.com/reference/memory-yml.md),
then written before the LLM runs, through the field's
[memory validation tool](https://mantle.rasa.com/reference/tools.md#memory-validation-tools) if it has
one. If the value is rejected, nothing is written and the turn
continues as a normal user message.

Declare identifiers that can start with zero, such as account numbers, as `text`
so leading zeros are kept.

Keypad input arrives on the `twilio_media_streams`, `jambonz_stream`,
`audiocodes_stream`, and `genesys` channels. The Inspector does not send keypad
input, so test keypad steps on a real line. On other channels, and on text, the
step collects the value as usual.

## Repeating a collect

Use this when the collect utterance is a page of
[dynamic buttons](https://mantle.rasa.com/reference/responses-yml.md#dynamic-buttons)
(`buttons: {source: ...}`). Handle the tap, clear the collected field, and
route back to the same `collect:` step. You do not need a second collect or an
`execute_tool: listen` between pages. The engine asks again and the button source
runs for the new page.

This block asks for an appointment time. A **Next** button writes
`slot_choice`. The tool turns the page, clears that field, and the `else:`
branch returns to `collect_slot`.

```yaml theme={null}
- id: collect_slot
  collect: slot_choice
  utterance: utter_ask_appointment_time
  next: resolve_slot

- id: resolve_slot
  execute_tool: resolve_slot_choice
  next: route_choice

- id: route_choice
  noop: true
  next:
    - if: session.appointment.selected_time != None
      then: selected
    - else: collect_slot
```

A time button still writes `slot_choice`. The tool then stores
`selected_time` instead of clearing the field, so `route_choice` takes
`selected` rather than looping.

## Recording a human handoff

`record_handoff` is a bundled tool with no arguments. An ordered block runs it
with `execute_tool`. It does not speak, write memory, or transfer the user.
Studio analytics use this call to count the conversation as handed to a human,
including when the transfer that follows fails. Put the step at the moment the
handoff is decided. The steps after it perform the transfer.

It is not a framework tool. The model is never offered it. A `tools:` gate or
`@tool.record_handoff` in prose does not resolve. A project function, shared
tool, or MCP import with this name fails training. A `parameters:` map on the
step fails training too, including a `session.*` value, because the tool
accepts no arguments.

```yaml theme={null}
- id: record_the_handoff
  execute_tool: record_handoff
  next: start_transfer
```

## See also

* [Ordered Blocks](https://mantle.rasa.com/build-guide/ordered-blocks.md): when to use one
* [`skill.md` reference](https://mantle.rasa.com/reference/skill-md): the fence and frontmatter
* [Conditions](https://mantle.rasa.com/reference/conditions.md): the expression grammar
* [Dynamic buttons](https://mantle.rasa.com/reference/responses-yml.md#dynamic-buttons): button source tools


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