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

# FLOW (structured execution steps)

The `FLOW:` section adds structured execution steps to any agent. It defines a step-by-step execution graph where each step declares actions (collect information, call tools, respond, branch) and transitions to other steps.

Agents operate in reasoning mode by default, where the LLM autonomously decides actions based on the goal. Adding a `FLOW:` section gives an agent a structured step graph, with each step declaring whether it uses LLM reasoning or deterministic execution via the `REASONING:` toggle.

## Flow structure

### Basic syntax

```yaml expandable=true theme={null}
FLOW:
  entry_point: start

  steps:
    - start
    - collect_info
    - process
    - complete

  start:
    REASONING: false
    SET:
      status = "pending"
    RESPOND: "Welcome! Let me help you get started."
    THEN: collect_info

  collect_info:
    REASONING: false
    GATHER:
      - name: required
        prompt: "What is your name?"
    THEN: process

  process:
    REASONING: false
    CALL: process_request
      WITH:
        name: name
      AS: result
    RESPOND: "Done! Your request has been processed."
    THEN: complete

  complete:
    REASONING: false
    RESPOND: "Thank you for using our service. Goodbye!"
```

### Entry point

The `entry_point:` property declares which step the flow begins at:

```yaml theme={null}
FLOW:
  entry_point: greeting
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `entry_point` | `string` | No | First step in the `steps` list | The step name where execution begins |

If omitted, execution starts at the first step listed in the `steps` array.

### Step list

The `steps:` array declares the ordered list of step names. While steps can transition to any other step (not just the next in order), the list establishes the canonical ordering:

```yaml theme={null}
FLOW:
  steps:
    - greeting
    - collect_account
    - verify
    - process
    - complete
```

### Step definitions

Each step is defined as a named block under `FLOW:` with its properties indented:

```yaml theme={null}
FLOW:
  greeting:
    REASONING: false
    RESPOND: "Hello! How can I help you today?"
    THEN: collect_account
```

#### Step headers and repeated properties

A step header is a bare `name:` line with nothing after the colon. Write it at the same indentation as the other steps: two spaces under `FLOW:`. The parser also reads a header at column 0, even with trailing spaces.

The parser does not read these lines as a step header:

* A header at any other indentation.
* A header at either accepted column that is followed by a comment.
* A two-space header that is followed by trailing spaces.

When step properties follow such a line, the parser reports warning [`W217`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w217) for the common shapes. The lines under it are read as part of the step above, where they can replace properties that step already has.

Each single-value step property holds one value. These include `REASONING`, `GOAL`, `THEN`, `ON_INPUT`, `ON_RESULT`, `CALL`, and `RESPOND`. Writing one a second time at the step's own property level reports warning [`W218`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w218).

These properties do not trigger `W218`:

* `SET`, `DO`, `LOG`, `STEP_CONSTRAINTS`, and `BEHAVIOR` accumulate.
* `ON_SUCCESS` and `ON_FAILURE` blocks merge.
* `ON_FAIL` fills a different slot for a `CHECK` and a `CALL`.
* `VOICE`, `RICH_CONTENT`, and `FORMATS` merge their members.

Both warnings are advisory. The agent compiles and runs as parsed.

### Per-step REASONING toggle

Every step in a `FLOW:` section **must** declare `REASONING: true` or `REASONING: false`. This controls whether the step uses LLM reasoning or deterministic execution.

```yaml theme={null}
FLOW:
  analyze_request:
    REASONING: true
    GOAL: "Analyze the customer's request and determine the best course of action"
    AVAILABLE_TOOLS: [search_knowledge, classify_intent]
    EXIT_WHEN: intent_classified == true
    MAX_TURNS: 5
    THEN: route_request

  route_request:
    REASONING: false
    CHECK: intent == "billing"
    ON_FAIL: general_support
    THEN: billing_flow
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `REASONING` | `boolean` | **Yes** | -- | `true` for LLM-driven reasoning, `false` for deterministic execution |

#### Reasoning step properties

When `REASONING: true`, the following additional properties are available:

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `GOAL` | `string` | No | Agent-level `GOAL:` | Step-specific goal (overrides the agent's goal for this step) |
| `AVAILABLE_TOOLS` | `string[]` | No | All agent tools | Subset of agent tools available in this step |
| `EXIT_WHEN` | `string` | No | *none* | Condition that ends the reasoning loop |
| `MAX_TURNS` | `number` | No | `10` | Maximum reasoning turns before forced exit |
| `STEP_CONSTRAINTS` | `string[]` | No | *none* | Constraints specific to this reasoning zone |
| `CONTEXT_UPDATES` | `boolean` or `string[]` | No | Omitted (`true`) | Controls whether/which fields the step's model may write via the Runtime's `__set_context__` tool. See [Controlling direct context writes](#controlling-direct-context-writes-context_updates). |

**Validation rules:**

* A step with `REASONING: true` must have either a step-level `GOAL` or an agent-level `GOAL:` defined.
* A step with `REASONING: false` shouldn't have a `GOAL` (it has no effect on deterministic steps).
* A step with `REASONING: false` shouldn't have `AVAILABLE_TOOLS` (use `CALL` to invoke tools deterministically).

#### Controlling direct context writes (`CONTEXT_UPDATES`)

`CONTEXT_UPDATES` controls direct model writes in a `REASONING: true` step: whether (and which) fields the model may write through the Runtime-owned `__set_context__` tool. It doesn't control what the model can read, which business tools it can call, or what trusted FLOW actions (`SET`, `on_result` mappings), authored `GATHER` extraction, and hooks can change. Those are separate, unaffected contracts.

| Declaration | Provider-visible result |
| - | - |
| Omitted or `true` | Runtime may add `__set_context__`; existing context-writing and `EXIT_WHEN` flows keep their previous behavior. |
| `CONTEXT_UPDATES: false` | Runtime removes `__set_context__` and its writable-field schema entirely; other authorized business and interaction-language tools remain usable. |
| `CONTEXT_UPDATES: [qr_text, qr_done]` (new in 1.8.2) | Only the listed fields appear in `__set_context__`'s writable schema; model-supplied context updates through the direct tool and through completion fields (including completion metadata) are restricted to that list. |
| `CONTEXT_UPDATES: []` (new in 1.8.2) | No direct write tool is offered, and no model-supplied context update through the direct or completion paths is accepted. |

```yaml theme={null}
FLOW:
  collect_qr_wording:
    REASONING: true
    GOAL: "Draft the QR code wording with the customer"
    CONTEXT_UPDATES: [qr_text, qr_done]
    THEN: review_wording
```

In YAML, use `context_updates: [qr_text, qr_done]` directly on the reasoning step (lowercase, same list syntax).

**List-form rules:**

* Lists are supported only on `REASONING: true` FLOW steps (not the agent-level default).
* Every list member must be a field already declared in `MEMORY.session`. Even if a `GATHER` or `EXIT_WHEN` reference would otherwise make an implicit field writable, it still needs its own `MEMORY.session` declaration to be listed. Declaring it there also makes it eligible in other, unscoped steps.
* A list that excludes a field a `GATHER` or `EXIT_WHEN` needs written can still work, but only if that field gets its value from another source (prefilled state, or a trusted authored write like `SET`/`on_result`). Otherwise the step can never progress, because the model cannot write it directly.
* A list narrows; it never grants new authority. `READONLY` and `MODEL_WRITERS` (and other Runtime-owned protections) still apply on top of it. Listing a field in `CONTEXT_UPDATES` does not bypass those.
* An `EXIT_WHEN` reference does not implicitly add its field to the list. Include a model-written exit field explicitly, or supply it through a trusted authored action instead.
* Names are case-sensitive and are normalized by trimming, deduplicating, and sorting; execution-tree paths and granted-memory keys cannot be list members.
* `CONTEXT_UPDATES: []` is different from omitting the field: omission keeps legacy full-write access; `[]` is a declared "no direct writes at all." `[]` also restricts the separate completion-fields context-update path, which plain `false` does not. This is the one sharp edge between the two opt-out forms.

A reasoning step whose only job is to present already-selected state can declare `CONTEXT_UPDATES: false` so the model is never offered a write tool it has no reason to use:

```yaml theme={null}
AGENT: ResultPresenter
GOAL: "Present the selected result"

MEMORY:
  session:
    - scratch_result
    - selected_result
```

> [!NOTE]
>
> Any list declaration, including `CONTEXT_UPDATES: []`, requires compiler and Runtime support for IR version 1.3. An older Runtime rejects an artifact built with one. Existing projects get no automatic change: a project must opt in by adding a list to a step and publishing only after every Runtime pod serving that project has been upgraded (the compiler does not block publishing out of order; that ordering is a deployment-operations responsibility). Rolling back to an older Runtime requires an artifact with no list declarations.

### Per-step EXECUTION

A `REASONING: true` step can set its own model and generation settings with an `EXECUTION:` block indented under the step. Keys the step leaves out keep the agent `EXECUTION` value. The settings apply only to the calls that produce the step's answer. Extraction, classification, and other steps keep the agent settings.

```yaml theme={null}
FLOW:
  entry_point: triage
  steps:
    - triage
    - answer

  triage:
    REASONING: true
    GOAL: "Work out which product the customer is asking about"
    EXECUTION:
      model: gpt-4o-mini
      temperature: 0.2
      max_tokens: 300
    THEN: answer

  answer:
    REASONING: true
    GOAL: "Answer the question in full"
    THEN: COMPLETE
```

#### Step EXECUTION parameters

| Key | Accepted value | Notes |
| - | - | - |
| `model` | A non-empty model name, or a `{{config.KEY}}` template. | Templates are not checked at compile time. |
| `reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. | Models without reasoning ignore it ([`STEP_EXECUTION_MODEL_CAPABILITY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_execution_model_capability)). |
| `verbosity` | `low`, `medium`, or `high`. | Supported models only. |
| `max_tokens` | Whole number, 1 or more. | Output length limit. |
| `temperature` | Number from 0 to 2. | Some models disable it. |
| `top_p` | Number from 0 to 1. | |
| `top_k` | Whole number, 0 or more. | |
| `frequency_penalty` | Any finite number. | |
| `presence_penalty` | Any finite number. | |
| `seed` | Whole number. | Reproducible output is provider-dependent. |
| `enable_thinking` | `true` or `false`. | Lowercase only. `yes` and `on` are not accepted. |
| `thinking_budget` | Whole number, 1 or more. | Token budget for extended thinking. |
| `stop_sequences` | A list of 1 to 16 non-empty strings, each at most 256 characters. | Keep to 4 or fewer so every provider receives them ([W562](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings.md#w562)). Not sent on calls that offer tools. |
| `llm_timeout` | Whole number of milliseconds, 1 or more. | Capped by the server limit and the turn's remaining time. |
| `tool_timeout` | Whole number of milliseconds, 1 or more. | |

Values are never converted. A quoted number such as `"0.2"` is text and raises W565. A number outside its range raises W564. In both cases the step uses the agent value for that key.

```yaml theme={null}
EXECUTION:
  model: "{{config.TRIAGE_MODEL}}"
  reasoning_effort: low
  temperature: 0.2
  max_tokens: 300
  stop_sequences: ["END_OF_ANSWER"]
  llm_timeout: 8000
```

Write one key per line, all at the same indent. Put `fallback_model` and `conversation_history_window` in the agent `EXECUTION` section instead. They raise W567 in a step.

* The step model outranks the agent's Model Config tab and its `EXECUTION` model. It must be a model the project can run. If not, the step uses the agent's model and the trace records `model_access:step_model_fallback`. A deployment model override still wins.
* A mistake in the block is a warning ([W563 to W569 and W573](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings.md#w563), [`STEP_EXECUTION_*`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_execution_model_capability)). The bad key is ignored and the other keys apply, so the agent still compiles.
* The block has no effect on a step that is not a `REASONING` step, or on a speech-to-speech voice session.

### Choosing the next step

A step runs whenever the flow reaches it. To take one path or another based on a value collected or computed earlier, route from a decision step with `ON_RESULT`. It works on a step without a `CALL`. The first matching branch wins:

```yaml theme={null}
FLOW:
  route_transfer_details:
    REASONING: false
    ON_RESULT:
      - IF: transfer_type == "international"
        THEN: international_details
      - ELSE:
        THEN: domestic_details

  international_details:
    REASONING: false
    GATHER:
      - swift_code: required
        prompt: "What is the SWIFT/BIC code?"
    THEN: validate_details
```

> [!WARNING]
>
> A step-level `WHEN:` does not skip the step. It has no effect, and the compiler reports the warning [`FLOW_STEP_WHEN_IGNORED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#flow_step_when_ignored). Remove it and route with `ON_RESULT`, or use `CHECK` with `ON_FAIL`.

### Attempt limiting

Steps can limit the number of times they execute (useful for retry loops):

```yaml theme={null}
FLOW:
  collect_pin:
    REASONING: false
    MAX_ATTEMPTS: 3
    ON_EXHAUSTED: lockout
    GATHER:
      - pin: required
        prompt: "Enter your PIN."
    THEN: verify_pin
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `MAX_ATTEMPTS` | `number` | No | *none* | Maximum number of times this step can execute |
| `ON_EXHAUSTED` | `string` | No | *none* | Step to transition to after max attempts exhausted |

The runtime counts an attempt in these cases:

* A failed required-input collection.
* An authored `ON_INPUT` retry that returns to the protected step, including a cycle through deterministic helper steps.
* A reasoning customer turn that ends without satisfying `EXIT_WHEN`.

How the count works:

* When the same customer message triggers a same-step `ON_INPUT` retry and then reasoning, the two paths use one attempt in total.
* A customer message routed through `ON_INPUT` and deterministic helper steps counts once when a different reasoning step evaluates it. Automatic reasoning without a customer message does not count.
* The counter is durable across session serialization and belongs to the active agent thread. A successful exit clears the current step's failed-attempt counter.
* `MAX_TURNS` is a separate limit on model and tool cycles inside one invocation.
* For a non-terminal `ON_EXHAUSTED` recovery target, the runtime keeps the final count through the exhaustion transition. It clears the count when you re-enter the protected step to start a new cycle. A self-target starts a fresh cycle after its exhaustion event.
* A terminal `ON_EXHAUSTED` outcome of `COMPLETE` or `ESCALATE` keeps the final count for diagnostics.
* Restoring a parked step whose count is below its limit keeps the interrupted retry budget. Restoration alone does not start a new cycle.

***

## Step actions

### SAY / RESPOND

The `RESPOND:` action sends a message to the user. It supports template interpolation with `{{variable}}` syntax:

```yaml theme={null}
FLOW:
  greeting:
    REASONING: false
    RESPOND: "Hello, {{customer_name}}! Your balance is {{balance}}."
    THEN: next_step
```

Multi-line responses use pipe block syntax:

```yaml theme={null}
FLOW:
  summary:
    REASONING: false
    RESPOND: |
      Here is your transfer summary:
      From: {{source_account}}
      To: {{beneficiary_name}}
      Amount: {{amount}} {{currency}}
    THEN: confirm
```

#### MODEL\_CONTEXT on a response

An optional `MODEL_CONTEXT` sits beside a FLOW step's `RESPOND` (or a `COMPLETE` condition's `RESPOND`) and replaces that response **only in future model context** — it never changes what's actually sent to the user, the stored transcript, or session values:

```yaml theme={null}
FLOW:
  show_products:
    REASONING: false
    RESPOND: "{{products_widget}}"
    MODEL_CONTEXT: "Displayed products {{product_ids}}."
    THEN: next_step
```

This is useful when the delivered response carries a large presentation payload (a widget, a card, a big table) that would otherwise bloat every later model call for no benefit — `MODEL_CONTEXT` lets the model keep a short textual summary of what the customer saw instead. `MODEL_CONTEXT` is a text scalar; a non-text value fails validation ([`MODEL_CONTEXT_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#model_context_invalid)). An explicitly empty value omits the response from later model requests entirely. Omit the property to keep the historical full-response behavior. See also [MODEL\_CONTEXT on a tool result](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#model_context-on-a-tool-result) for the equivalent policy on a tool's own result.

> [!NOTE]
>
> A successfully rendered, non-empty `MODEL_CONTEXT` view is **preserved exactly** through later history compaction, summarization, and automatic conversation windowing — it's never auto-shortened, replaced with a summary, or dropped for being old. It's evaluated once, when the response is produced; later turns reuse that same rendered text rather than re-evaluating the template against newer data. This doesn't raise the model's context window or bypass the usual budget: an authored view may exceed the ordinary per-value/aggregate *soft* budget, but must still fit the aggregate *hard* capacity, or the runtime reports `AUTHORED_MODEL_CONTEXT_CAPACITY_EXCEEDED` rather than silently shrinking it. Keep `MODEL_CONTEXT` to the identifiers, status, and decision facts a later turn actually needs, and fetch further detail through a read tool — a large preserved view repeats in every later prompt, which adds up in prompt size, model cost, and latency. (This guarantee needs a matching Runtime version on every process handling the session; a rollback or a mixed-version deployment can silently lose it.)

### PRESENT

The `PRESENT:` action displays a formatted presentation before collection. It is used alongside `GATHER:` to show the user what has been collected so far:

```yaml theme={null}
FLOW:
  review:
    REASONING: false
    PRESENT: |
      Beneficiary: {{beneficiary_name}}
      Account: {{MASK(beneficiary_account, "last4")}}
      Bank: {{beneficiary_bank_name}}
    GATHER:
      - confirmation: required
    THEN: process
```

### GATHER in flow steps

Within a flow step, `GATHER:` uses a list syntax different from the top-level `GATHER:` section:

```yaml theme={null}
FLOW:
  collect_details:
    REASONING: false
    GATHER:
      - source_account: required
        prompt: "Your account number?"
    THEN: next_step
```

#### Map form (alternate syntax)

Fields can also be written as a map, without the leading `-`. Each lower-case name one level under `GATHER:` starts a field, with the same properties, inline `required`/`optional`/`default=` values, and field-level `VOICE:`/`ASR:`/`DTMF:` blocks as the list form:

```yaml theme={null}
FLOW:
  collect_dates:
    REASONING: false
    GATHER:
      checkin:
        TYPE: date
        REQUIRED: true
        PROMPT: "When do you want to check in?"
      guests: default=2
    THEN: next_step
```

Upper-case keys at that level (`PROMPT`, `STRATEGY`, and other recognized GATHER-block keywords) stay GATHER block properties, not fields. Only a lower-case (or mixed-case) name that is not a recognized GATHER-block keyword is read as a new field header.

#### Inline and bare forms

For fields that need no other properties, write the names on the `GATHER:` line, or as bare list items:

```yaml theme={null}
FLOW:
  collect_name:
    REASONING: false
    GATHER: first_name, last_name
    THEN: next_step

  collect_contact:
    REASONING: false
    GATHER: [email, phone]
    THEN: next_step
```

A bare list item, such as `- email`, is a required field. The inline forms `GATHER: a: required, b: optional` are also accepted. A list item that ends in `default=value` sets `required: false` and a default, and always gives warning `W822`.

#### Inheriting a top-level field

A step field inherits the properties of a top-level `GATHER` field with the same name. The step overrides only the properties it sets. A step field that sets nothing but `required` or `optional`, such as `- notes: optional`, does not change the inherited `required` value. Add another property, such as `prompt`, to override it.

#### Multi-field collection

Collect multiple fields in a single step using the `FIELDS:` sub-block:

```yaml expandable=true theme={null}
FLOW:
  collect_beneficiary:
    REASONING: false
    GATHER:
      FIELDS:
        - beneficiary_name: required
          prompt: "Full legal name on the account."
        - beneficiary_account: required
          prompt: "Account number or IBAN."
        - beneficiary_bank: required
          prompt: "Name of the bank."
        - country: required
          prompt: "Country of the bank."
          default: "US"
          infer: true
      STRATEGY: llm
    CORRECTIONS: true
    COMPLETE_WHEN: beneficiary_name AND beneficiary_account AND beneficiary_bank AND country
    THEN: validate
```

#### Flow gather field properties

Each field in a flow `GATHER:` supports these properties:

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `required` / optional value after name | `boolean` | No | `true` | Whether the field must be collected |
| `prompt` | `string` | No | *none* | Question shown to the user |
| `type` | `string` | No | `"string"` | Data type |
| `default` | `any` | No | *none* | Default value |
| `validation`, `validate` | `string` | No | *none* | Validation expression. Both key names are accepted, here and in a top-level `GATHER`. |
| `description` | `string` | No | *none* | Model-facing meaning of the value, separate from `prompt` |
| `strategy` | `"auto"` , `"ml"` , `"llm"` , `"hybrid"` , `"pattern"` | No | *none* | Extraction strategy for this field. A field value wins over the block `STRATEGY`. |
| `infer` | `boolean` | No | `false` | Fill from earlier customer messages when the step starts to collect |
| `infer_confidence` | `number` | No | `0.8` | Minimum inference confidence |
| `infer_confirm` | `boolean` | No | `true` | Ask the customer to confirm inferred values |
| `extraction_hints` | `string[]` | No | *none* | LLM extraction guidance |
| `range` | `boolean` | No | `false` | Collect as range |
| `list` | `boolean` | No | `false` | Collect as array |
| `activation` | `string` , `{when: string}` | No | *none* | Activation mode |
| `depends_on` | `string[]` | No | *none* | Field dependencies |
| `prompt_mode` | `"ask"` , `"extract_only"` | No | `"ask"` | Prompt usage mode |
| `VOICE` | `object` | No | *none* | Per-field `BARGE_IN` and `STREAMING`. See [Voice delivery for a field](#voice-delivery-for-a-field). |

#### Voice delivery for a field

On KoreVG pipeline voice, a field can carry its own `VOICE` block with `BARGE_IN` and `STREAMING`. The block governs that field's prompt, reprompts and readback. Use it to protect a prompt the caller must hear in full while the rest of the step stays interruptible.

```yaml expandable=true theme={null}
FLOW:
  verify:
    REASONING: false
    RESPOND: "I will now verify you."
    GATHER:
      - otp_code: required
        prompt: "Please say or enter the six digit code we sent you."
        VOICE:
          BARGE_IN: disallow
          STREAMING: false
      - account_number: required
        prompt: "What is your account number?"
        VOICE:
          BARGE_IN: allow
    THEN: COMPLETE
```

* **Precedence.** A field's policy is narrower than the step's `VOICE` block, the agent's `CONVERSATION.listening.barge_in` and the channel setting. An explicit `allow` on a field wins over a wider `disallow`, including a call-wide one.
* **Where it applies.** Only fields of a FLOW step `GATHER:` read the block. A `VOICE` line on a field of a top-level `GATHER:` section gives warning [`W170`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w170).
* **Errors.** An invalid `BARGE_IN` is [`VOICE_INVALID_BARGE_IN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_barge_in). A non-boolean `STREAMING` warns with [`VOICE_INVALID_STREAMING`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_streaming). `LISTENING` is [`VOICE_LISTENING_CALL_LEVEL_ONLY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_listening_call_level_only). Keypad settings belong in the field's `DTMF:` block.
* **Runtime support.** A field's `BARGE_IN` is published with the IR marker `voice_output_policy`. A runtime without the marker refuses the agent at publish, deploy and activation.

> [!NOTE]
>
> Flow gather fields also accept the same additional properties as top-level [GATHER](https://koreai.mintlify.site/agent-platform/abl/reference/gather.md) fields: `entity_ref`, `options`, `message_key`, `satisfied_by`, `validation_process`, `retry_prompt`, `max_retries`, `preferences`, `sensitive`, `sensitive_display`, `mask_config`, `pii_type`, `transient`, `extraction_pattern`, `extraction_group`, and `semantics`. In addition, a flow gather field may carry `rich_content` format variants for its prompt. Both `validation:` and `validate:` are accepted in a flow field. Write `transient` for a field in a top-level `GATHER` only: the runtime does not clear a transient field in a flow step.

A flow step asks only for required fields. Optional fields are captured when the customer volunteers them and are never asked. A step with only optional fields passes on entry. Put `ON_INPUT` branching in the step after the `GATHER` step. A step that has both gives warning `FLOW_ON_INPUT_GATHER_ORDER_AMBIGUITY`. A multi-line `VALIDATE` block is ignored with warning `W174`, and a `VALIDATE` object or list is used literally as a regular expression with warning `W175`.

#### Field-level listening settings (`ASR:`)

An `ASR:` block — a sibling of `VOICE:` on a single field — sets how the bot **listens** while that one field is being asked on a KoreVG voice call. Once the field is no longer being asked, the call's normal listening settings return automatically:

```yaml expandable=true theme={null}
FLOW:
  get_county:
    REASONING: false
    GATHER:
      - county: required
        prompt: "Which county is the dig site in?"
        ASR:
          vocabulary:
            mode: replace
            terms: [Guilford, Mecklenburg, Wake]
          no_input_timeout_ms: 8000
  get_street:
    REASONING: false
    GATHER:
      - street_name: required
        prompt: "What is the street name?"
        ASR:
          provider: deepgram
          model: nova-3
          vocabulary:
            mode: extend
            terms:
              default: [Boulevard]
              en: [{ phrase: Parkway, boost: 40 }]
              es-MX: [Privada]
```

| Key | Meaning |
| :- | :- |
| `provider` | Speech engine for this field (for example `deepgram`, `google`, `azure`) — must already be configured on the project's voice channel. |
| `model` | Recognizer model for the field. Not validated at deploy; a model the engine rejects falls back to the normal settings. |
| `language` | Listening language for this question only — doesn't change the conversation language. |
| `vocabulary.mode` | `replace` (only this field's words), `extend` (the call's words plus this field's, field words kept first under a limit), or `none` (no special words). Without `vocabulary`, the call's words are unchanged. |
| `vocabulary.terms` | A plain list of words for every language, or a map of language tag (or `default`) to a list. Each entry is a string or `{ phrase, boost: 0-100 }`. The list is picked by exact tag, then base language, then `default` — lists are never merged across languages. |
| `no_input_timeout_ms` | Silence wait for this question, `1000`-`60000` ms. Has no effect when no-input handling is off for the channel. |

Rules:

* Keys are strict — an unknown key is a compile error ([`GATHER_ASR_UNKNOWN_KEY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#gather_asr_unknown_key)). Credentials and service IDs never go in ABL.
* At most 500 vocabulary entries per field across every language, each at most 100 characters.
* **One listening-settings field per step.** `ASR:` applies only when its field is asked on its own; a field sharing its step with other required fields gets warning [`GATHER_ASR_SHARED_STEP`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#gather_asr_shared_step) and uses the normal settings when asked together.
* **FLOW steps only.** `ASR:` on a top-level (reasoning) `GATHER` field is preserved but has no effect, with compile warning [`GATHER_ASR_REASONING_UNSUPPORTED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#gather_asr_reasoning_unsupported).
* **Deploy checks.** A `provider` that no voice channel bound to the target environment supports blocks create/promote (`GATHER_ASR_PROVIDER_UNRESOLVED`); restore/rollback warn instead. An unsupported channel (non-KoreVG voice, realtime speech-to-speech), an unsupported language, too many words for the engine, a no-input wait with no-input off, or an uncovered language list are deploy warnings.
* At runtime, anything that can't be applied (an unknown engine, a rejected setting, a gateway that doesn't confirm the change) falls back silently to the call's normal listening settings — the call continues.
* There's no platform switch for this feature; to stop using it, remove the `ASR:` block and redeploy.

##### Session-value vocabulary (`vocabulary.terms` binding)

`vocabulary.terms` can read its words from a session value set earlier in the call, so the recognizer hears the specific names, streets, or codes a tool returned for this caller. Write one language's list (or the whole list) as a single quoted `"{{path}}"` reference:

```yaml expandable=true theme={null}
FLOW:
  lookup_streets:
    REASONING: false
    CALL: list_streets
      WITH:
        county: county
      AS: streetResult
    ON_RESULT:
      - IF: has(streetResult.streets)
        SET:
          street_keyterms = streetResult.streets
        THEN: get_street
      - ELSE:
        THEN: get_street
  get_street:
    REASONING: false
    GATHER:
      - street_name: required
        prompt: "What is the street name?"
        ASR:
          vocabulary:
            mode: replace
            terms:
              en-US: "{{street_keyterms}}"
              default: [Main Street]
    THEN: COMPLETE
```

Rules:

* The value is read each time the field is asked (first prompt, retries, rechecks). A list that changes between turns is used as it is at that moment. It applies only while that field is asked.
* The reference must be exactly one quoted `"{{path}}"`: dotted names with optional `[n]` indexes, at most 8 parts and 128 characters. Surrounding text, two references, filters, an unquoted `{{...}}`, or a reference inside a list are all compile errors ([`GATHER_ASR_TERMS_BINDING_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#gather_asr_terms_binding_invalid)).
* Some values can never be bound ([`GATHER_ASR_TERMS_BINDING_FORBIDDEN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#gather_asr_terms_binding_forbidden)): session identity and runtime values (`session`, `config`, `env`, `history`, `messages`, `tenant_id`, `project_id`, `user_id`, `session_id`, `session_principal_id`), the protected email aliases, any root starting with `_`, and any path through `__proto__`, `prototype`, `constructor`, `_secret`, or `_secrets`. A `user.*` value is personal data and needs `restore_pii: true` (see below).
* The value can be a string (one word) or a list of strings and `{ phrase, boost }` entries. On the Deepgram keyterm path a boost has no effect.
* Each word is checked when read. A word that is missing, empty, longer than 100 characters, contains a comma/semicolon/line break, duplicates an earlier word, holds a redaction placeholder or a held secret value, or holds protected personal data is left out. The question is still asked. A field never fails because of its word list.
* Words already present for a language come first. A language whose reference resolves to nothing stays empty for that question. It does NOT fall back to `default`.
* Limits per field per question: 2,000 entries read, 64 KiB of text read, 500 words total including literal ones. On Deepgram, a list that includes session words is held to 400 estimated tokens (literal-only lists keep 500), and the gateway accepts at most 100 keyterms.
* Only the KoreVG voice pipeline uses these words. Other channels and realtime speech-to-speech calls ignore the reference without reading the value.

> [!TIP]
>
> Keep the list short and spoken-form (20 to 50 words is the range Deepgram recommends). Rank or cut the list in the tool, expand abbreviations, and use the form a caller says ("North Main Street", not "N MAIN ST"). Never put session data in `deepgramOptions.tag`.

##### Personal data in bound words (`restore_pii`)

Values the platform has tokenized as personal data (names, phone numbers, emails) are left out by default. To send the original value to the speech engine, BOTH of these are required:

1. The field sets `vocabulary.restore_pii: true`.
2. The project's PII pattern for that kind of data has an explicit `speech_provider` rule set to Original (PII Protection in Studio). A pattern whose default mode is Original does not count; without the rule the word is left out.

A restored word is sent only to the recognizer, never written to traces or logs, and each restore is recorded in the PII audit log without the value. On Deepgram, a call that sends a restored word also opts the request out of Deepgram's model-improvement program. `restore_pii` on a field with no session-value reference is ignored with a warning.

#### Field-level keypad settings (`DTMF:`)

A `DTMF:` block, a sibling of `ASR:` under a single `GATHER` field in a FLOW step, sets how the bot collects a number the caller types on the phone keypad while that field is being asked on a KoreVG voice call. When the field is no longer being asked, the call's normal keypad settings come back automatically (2 seconds between key presses, finish key `#`, up to 12 digits). A field without `DTMF:` behaves exactly as before. The caller can still answer by speaking; `DTMF:` changes only how typed digits are grouped into one answer:

```yaml theme={null}
FLOW:
  get_mobile:
    REASONING: false
    GATHER:
      - mobile_number: required
        type: string
        prompt: "Please say or enter your 10-digit registered mobile number."
        DTMF: { digits: 1..10, finishOnKey: "#", interDigitTimeoutMs: 5000 }
        VALIDATE: "^[0-9]{10}$"
        RETRY_PROMPT: "That didn't look like a 10-digit number. Please say it or enter it on the keypad again."
        MAX_RETRIES: 3
    THEN: verify_customer
```

The block can also be written over several lines (`DTMF:` followed by indented `digits:`, `finishOnKey:`, `interDigitTimeoutMs:` lines).

| Key | Meaning |
| - | - |
| `digits` | `min..max`, both whole numbers 1-32. The answer finishes as soon as the caller types `max` digits. A pause finishes it only after at least `min` digits. Keep `min` at 1 unless a short entry should end only by the finish key. |
| `finishOnKey` | `"#"`, `"*"`, or `"none"`. Pressing the key finishes the answer at once; the key itself is not part of the answer. `"none"` means no finish key. |
| `interDigitTimeoutMs` | Longest pause between two key presses, 500-30000 ms. A longer pause finishes the answer. |
| `finishKeyAlone` | What happens when the caller presses only the finish key: `no_input` (default), `input`, or `value`. See [Finish key pressed alone](#finish-key-pressed-alone-finishkeyalone). |

Rules:

* Keys are strict: an unknown key, a malformed value, or an out-of-range value is a compile error. `min` above `max` is a compile error. A `DTMF:` block with no settings is a compile error.
* `min` above 1 is a compile warning: a caller who stops early is not finished by the pause.
* **One keypad-settings field per step.** A field with `DTMF:` must be the only field in its step. Split other fields into their own steps.

- `VALIDATE` checks the stored value. A `type: phone` field is stored in international format (for example, `+919876543210`), so `^[0-9]{10}$` never matches it. Use `type: string` to check digits exactly as typed, or write the pattern for the international format.
- `DTMF:` doesn't change validation or retries: use `VALIDATE`, `RETRY_PROMPT`, `MAX_RETRIES` on the same field, plus the agent's `ON_ERROR` handler for `validation_error` with `SUBTYPE: max_retries_exceeded`.
- `DTMF:` collects ordinary data. The typed number reaches the agent, its memory, and the transcript like any GATHER value. For secrets (card numbers, security codes, PINs), use [`SECURE_INPUT`](#secure_input) instead.
- Explicit keypad collections (`SECURE_INPUT`, the `ivr_digit_input` tool, voice surveys) keep their own settings and are unaffected.
- At runtime, settings apply with the field's listening settings (same mechanism as `ASR:`). If they can't be applied (for example, a realtime speech-to-speech channel, or a gateway that doesn't confirm the change), the call keeps its normal keypad settings and continues.

##### Finish key pressed alone (`finishKeyAlone`)

By default, a caller who presses only the finish key, with no digits before it, gives no input. The bot waits and asks again. `finishKeyAlone` changes this on KoreVG voice calls.

```yaml theme={null}
FLOW:
  confirm_mobile:
    REASONING: false
    GATHER:
      - confirm: required
        type: string
        prompt: "Press # to confirm your registered mobile number, or enter a new one."
        DTMF: { digits: 1..10, finishOnKey: "#", finishKeyAlone: value }
    THEN: verify_customer
```

| Value | What a finish key pressed alone does | Where it is allowed |
| - | - | - |
| `no_input` | Counts as no input. This is the default. | Everywhere |
| `input` | Goes to the agent as what the caller pressed. The turn text is the key (`#` or `*`). A FLOW step can branch on it with `ON_INPUT`. | FLOW fields, behavior profiles, agents, and the project |
| `value` | Is stored as the field's answer, so the field holds `#` or `*`. | A FLOW `GATHER` field only |

The key resolves in this order: the field `DTMF:` block, the active behavior profile, the agent (`CONVERSATION.listening.dtmf`), the project (`voiceListening.dtmf.finishKeyAlone`), then `no_input`.

* `value` above a FLOW field is a compile error (`LISTENING_FINISH_KEY_ALONE_VALUE_LEVEL`). The project Runtime Config API returns `400`. On a top-level (reasoning) field it is `GATHER_DTMF_FINISH_KEY_ALONE_VALUE_REASONING`. Any other unknown value is `GATHER_DTMF_FINISH_KEY_ALONE_INVALID`.
* `value` on a field whose type can never hold `#` or `*` (number, date, phone, email, yes or no, list, or range) is a compile error (`GATHER_DTMF_FINISH_KEY_ALONE_VALUE_TYPE`). Allowed values, or a `VALIDATE` pattern, that reject the key give the warning `GATHER_DTMF_FINISH_KEY_ALONE_NEVER_ACCEPTED`.
* `input` or `value` with `finishOnKey: "none"` gives the warning `GATHER_DTMF_FINISH_KEY_ALONE_NO_FINISH_KEY`. The caller cannot press a finish key alone.
* An agent or profile `input` that reaches a FLOW question with no `finishKeyAlone` of its own and no `ON_INPUT` branch gives the warning `GATHER_DTMF_FINISH_KEY_ALONE_INPUT_UNUSED`. The caller hears the question again.
* A finish key pressed by habit after a keypad answer that already ended on its own belongs to that answer. With barge-in on, a key that arrives within 3 seconds and before the next prompt starts is ignored. A repeat of the same key within 150 ms is also ignored.
* `SECURE_INPUT`, the `ivr_digit_input` tool, `ivr_menu`, and voice surveys (where `#` means skip) keep their own handling.
* The trace records whether the key was delivered, ignored, or kept as no input, and the level the setting came from. Typed digits are never logged or traced.
* An agent that sets `finishKeyAlone` is published with the IR feature marker `voice_listening_finish_key`. A runtime that does not support the marker refuses to publish, deploy, or run the agent. Upgrade every runtime before you publish such an agent.

#### GATHER block properties

Alongside `FIELDS:`, a flow `GATHER:` block accepts these block-level properties:

| Property | Type | Description |
| - | - | - |
| `STRATEGY` | `"auto"` , `"ml"` , `"llm"` , `"hybrid"` , `"pattern"` | Collection approach (see below). Also settable per field. |
| `PROMPT` | `string` | A single prompt used to collect the whole block. |
| `MESSAGE_KEY` | `string` | Locale catalog key for the block prompt. |

The `STRATEGY:` value controls the collection approach:

| Value | Description |
| - | - |
| `auto` | Let the platform choose the best available strategy |
| `ml` | Use the ML/NLU entity model |
| `llm` | Use LLM to extract values from natural conversation |
| `pattern` | Use pattern matching and extraction rules |
| `hybrid` | Combine ML and LLM extraction |

#### CORRECTIONS

When `CORRECTIONS: true`, the user can naturally correct previously collected values without restarting the step:

```yaml theme={null}
FLOW:
  collect_info:
    REASONING: false
    GATHER:
      - name: required
      - email: required
    CORRECTIONS: true
    THEN: next_step
```

When a `CORRECTIONS: true` GATHER accepts a changed value, the caller hears a short acknowledgement before the next prompt. It uses two message keys:

* `gather_correction_applied`: default "Got it, I've updated the {{fields}}."
* `gather_correction_dependents_cleared`: default "I may need to ask you again about the {{cleared_fields}}." The runtime sends it when the correction cleared dependent fields that the step asks for again.

Each key resolves like the other [`MESSAGES`](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks#messages) keys: project locale assets, then agent `MESSAGES`, then the English platform default. When the interaction language is not English and no localized text exists, the runtime omits that sentence.

* `{{fields}}` and `{{cleared_fields}}` are the only placeholders. They hold a list of field labels joined for the interaction language. Any other placeholder renders as empty text, so the message never contains a collected value.
* A field label is the `gather_field_label_<field>` message when you author one, for example `gather_field_label_date_of_birth: "birthday"`. Otherwise it is the field name turned into lower-case words (`incident_location` becomes "incident location"), which is not translated.
* A label in agent `MESSAGES` applies in every interaction language. Put per-language labels in the project locale assets.
* Fields with `PROMPT_MODE: extract_only` are never named. The runtime sends each sentence only when its list of labels is not empty.
* The acknowledgement is part of the turn's response and transcript, ahead of the next prompt or the step's closing reply.

#### COMPLETE\_WHEN

The `COMPLETE_WHEN:` condition specifies when the gather step is considered complete:

```yaml theme={null}
FLOW:
  collect_all:
    REASONING: false
    GATHER:
      FIELDS:
        - field_a: required
        - field_b: required
        - field_c: optional
    COMPLETE_WHEN: field_a AND field_b
    THEN: process
```

### CALL...WITH...AS

The `CALL:` action invokes a tool. Use `WITH:` to pass parameters and `AS:` to bind the result to a variable:

```yaml theme={null}
FLOW:
  verify_step:
    REASONING: false
    CALL: verify_account
      WITH:
        account_id: source_account
      AS: acctResult
    RESPOND: "Account verified: {{acctResult.owner_name}}"
    THEN: next_step
```

A key missing from a record reads as `null` inside a `WITH` expression. An argument with no value is left out of the tool input. See [Missing values in CALL arguments](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#missing-values-in-call-arguments). An empty `""` bound to a required tool parameter blocks the call. See [Empty values for required parameters](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#empty-values-for-required-parameters).

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `CALL` | `string` | -- | -- | Tool name to invoke |
| `WITH` | `Record<string, string>` | No | *none* | Key-value parameter mapping |
| `AS` | `string` | No | *none* | Variable name to bind the tool result |

#### WITH parameters

The `WITH:` block maps tool parameter names to values or variable references:

```yaml theme={null}
CALL: calculate_fees
  WITH:
    transfer_type: transfer_type
    amount: amount
    currency: currency
    destination_country: beneficiary_country
  AS: feeResult
```

Values can be:

* Variable references: `amount` (resolves the session variable `amount`)
* Literal strings: `"domestic"`
* Expressions: `COALESCE(reference, "")`
* **Nested objects** — a key with no inline value followed by an indented sub-block becomes a nested object argument, for tools whose schema requires object parameters:

```yaml theme={null}
CALL: ivr_digit_input
  WITH:
    prompt: "Enter your account number"
    noInputConfig:
      timeoutMs: 5000
      maxRetries: 2
    noMatchConfig:
      message: "That didn't match. Please try again."
  AS: digitResult
```

Nesting is preserved by indentation. Scalar leaves keep their raw form and are coerced at runtime (`"30"` → `30`, `"[15, 16]"` → `[15, 16]`).

#### Localized WITH arguments

A `WITH` value can take its text from the project's locale files (`locales/<locale>/<agent>.json` or `locales/<locale>/_shared.json`) with `"{{locale.KEY}}"`, or a bare `locale.KEY`. The text is chosen for the caller's current interaction locale (with the same fallback chain as `MESSAGE_KEY` — for example `hi-IN`, then `hi`), and `{{…}}` placeholders inside the locale text are rendered too:

```yaml theme={null}
FLOW:
  collect_card_number:
    REASONING: false
    CALL: ivr_digit_input
      WITH:
        prompt: "{{locale.CARD_PROMPT}}"
        maxDigits: 19
        endingKeyPress: "#"
        noInputConfig:
          timeout: 30
          maxRetries: 2
          message: "{{locale.CARD_NO_INPUT}}"
      AS: cardNumberResult
    ON_RESULT:
      - IF: cardNumberResult.success == false
        THEN: payment_input_failed
      - ELSE:
          THEN: validate_card_number
```

If a referenced key isn't defined for the caller's locale (and no less-specific locale in the chain provides it), the tool is **not** called — the `CALL` result is `success: false` with `error.code: "LOCALE_KEY_MISSING"`, so the step's failure branch runs and raw `{{locale.KEY}}` text never reaches the tool or the caller. Only authored text is treated as a locale reference; a session value that happens to contain `{{locale.…}}` passes through as plain data. Supported forms are `"{{locale.KEY}}"` (optionally with filters, like `"{{locale.KEY | upper}}"`, and mixed with other text) and a bare `locale.KEY`; an expression such as `locale["KEY"]` or `locale.KEY + "!"` is not supported and the `CALL` is not run.

### PARALLEL

`PARALLEL:` runs several read-only tool calls at the same time in one deterministic FLOW step. Each call binds its own `AS` variable after all calls settle. The step then routes once through `ON_SUCCESS`, `ON_PARTIAL`, or `ON_FAILURE`. Three sequential calls take the sum of their latencies. A parallel block takes the slowest one.

```yaml theme={null}
FLOW:
  fetch_account_data:
    REASONING: false
    PARALLEL:
      - CALL: get_account_info
        WITH:
          account_id: account_id
        AS: account
      - CALL: get_limit_info
        WITH:
          account_id: account_id
        AS: limits
    ON_SUCCESS:
      THEN: answer
    ON_PARTIAL:
      THEN: answer
    ON_FAILURE:
      RESPOND: "I can't get your account details right now."
      THEN: COMPLETE
```

`PARALLEL` is a step key, not a step type. Agents without it compile as before.

#### Forms

The list form holds calls only. The full form holds block options and a `CALLS:` list:

```yaml theme={null}
FLOW:
  fetch:
    REASONING: false
    PARALLEL:
      WAIT: all
      FAIL_FAST: false
      MAX_CONCURRENCY: 5
      TIMEOUT: 30s
      STATUS_AS: lookups
      CALLS:
        - CALL: get_account_info
          WITH:
            account_id: account_id
          AS: account
          REQUIRED: true
        - CALL: get_reward_points
          AFTER: cards
          FOR_EACH: cards.items
          ITEM_AS: card
          WITH:
            card_id: card.id
          AS: rewards
    ON_SUCCESS:
      THEN: answer
    ON_PARTIAL:
      THEN: answer
    ON_FAILURE:
      THEN: offer_agent
```

| Block key | Meaning |
| - | - |
| `WAIT` | `all` (default), `first_success`, `first` (the first call to settle, success or not), or a number of successes. |
| `FAIL_FAST` | `true`: a failed `REQUIRED` call cancels the other calls. Default `false`. |
| `MAX_CONCURRENCY` | 1 to 10. Default 5. |
| `TIMEOUT` | Block deadline. Default 30 s, maximum 120 s. |
| `STATUS_AS` | Session variable that receives the status of every call. |
| `CALLS` | The list of calls. |

| Call key | Meaning |
| - | - |
| `CALL` | Required. The tool to call. |
| `WITH` | Tool arguments. |
| `AS` | Variable that receives the result. |
| `WHEN` | Condition. A call whose condition is false is skipped. |
| `REQUIRED` | `true`: the step fails when this call fails. |
| `TIMEOUT` | Per-call timeout. It covers all retries and cannot outlast the block `TIMEOUT`. |
| `RETRY`, `RETRY_DELAY`, `RETRY_BACKOFF` | Retries (maximum 3) for retryable errors only. Backoff is `fixed`, `linear`, or `exponential`. |
| `SET` | Assignments that run when the call succeeds. `result` is in scope. |
| `DEFAULT` | Value bound to `AS` when the call does not succeed. Default is null. |
| `ERROR_AS` | Variable that receives a safe error object. |
| `FALLBACK` | A second tool, run once after the retries fail, with the same `WITH` inputs. |
| `AFTER` | Name of another call in the block to wait for. This call can then read its `AS` variable. |
| `FOR_EACH`, `ITEM_AS`, `INDEX_AS`, `FILTER`, `MAX_ITEMS`, `KEY_BY` | One call per list item. `ITEM_AS` defaults to `item`. `MAX_ITEMS` defaults to 10, maximum 20. `KEY_BY` binds a map instead of a list. |

Durations are `1500ms`, `2s`, or a bare number of milliseconds. Zero is rejected.

#### How it runs

1. Calls run at the same time and do not write the session while they run. After every call settles (or the `WAIT` target is met, or the block deadline passes), results bind in authored order, the same way as a single `CALL`.
2. A call that succeeds binds its result to `AS`, sets `ERROR_AS` to null, and runs its `SET`. A call that fails or times out binds `DEFAULT` (or null) to `AS` and a safe error object to `ERROR_AS`. A skipped or cancelled call binds `DEFAULT` (or null) and a null `ERROR_AS`.
3. `FOR_EACH` binds a list in item order, or a map when `KEY_BY` is set. A failed item holds `DEFAULT` or null. `FOR_EACH` counts the list's items before `FILTER`. A list longer than `MAX_ITEMS` fails the whole call with `too_many_items`, and nothing is sent.
4. A call reads another call's `AS` variable only when it names that call in `AFTER`. Without `AFTER`, it sees the session as it was before the step.
5. A barge-in or turn cancellation cancels the running calls. Nothing binds, and the step does not route.
6. Calls never prompt the customer. A missing sign-in fails the call with `auth_required`. A constraint that refuses a call fails it with `constraint_blocked`, and nothing is sent. Inside a block, there is no missing-input reask, no `ON_ERROR` handler, and no read-only result cache.

#### Routing

| Result | The step goes to |
| - | - |
| Every call that ran succeeded | `ON_SUCCESS` |
| Some calls failed, and no `REQUIRED` call failed | `ON_PARTIAL`, or `ON_SUCCESS` if there is no `ON_PARTIAL` |
| A `REQUIRED` call failed, or every call that ran failed | `ON_FAILURE` |
| `WAIT: first`, and the first call failed | `ON_FAILURE` |

Skipped calls do not count as failed. A step where every call is skipped goes to `ON_SUCCESS`.

#### Limits

* At most 10 calls and 20 reserved invocations per block. A plain call reserves 1. A `FOR_EACH` reserves its `MAX_ITEMS`.
* The block keeps at most 2 MB of results. An HTTP tool reads at most 2 MB of a response inside `PARALLEL`. A larger response fails the call with `result_too_large`.
* The tool's own HTTP retries are off inside `PARALLEL`. `RETRY` is the only retry.

#### Rules and diagnostics

Only read-only tools are allowed. A tool must be an HTTP `GET`, or declare `effect: read_only`.

| Code | Fires when |
| - | - |
| `PARALLEL_STEP_SHAPE` | `PARALLEL` is in the same step as `CALL`, `GATHER`, `SECURE_INPUT`, `HUMAN_APPROVAL`, or `REASONING: true`, or `ON_PARTIAL` is written without `PARALLEL`. |
| `PARALLEL_TOOL_UNKNOWN` | The tool, or the `FALLBACK` tool, is not declared. |
| `PARALLEL_TOOL_NOT_READ_ONLY` | The tool may write: it is not `effect: read_only` and not an HTTP `GET`. |
| `PARALLEL_TOOL_NOT_ALLOWED` | A confirmation, SearchAI, `result_secrets`, or `secret_access` tool, or a hook other than SET, CLEAR, or LOG. |
| `PARALLEL_NAME_CONFLICT` | Two calls write the same `AS`, `ERROR_AS`, `SET`, or `STATUS_AS` name. |
| `PARALLEL_CROSS_CALL_READ` | A call reads another call's binding without `AFTER`. |
| `PARALLEL_DEPENDENCY_INVALID` | `AFTER` names an unknown call, names itself, or forms a cycle. |
| `PARALLEL_OPTION_CONFLICT` | A list key without `FOR_EACH`, or an option pair that cannot work together. |
| `PARALLEL_LIMIT_EXCEEDED` | Calls, invocations, concurrency, timeout, or retry above the limits. |
| `PARALLEL_EXPRESSION_INVALID` | A `WHEN`, `FILTER`, `KEY_BY`, or `WITH` expression does not parse. |
| `PARALLEL_REQUIRED_WITH_ON_RESULT` (warning) | `REQUIRED` together with `ON_RESULT` routing. |
| `PARALLEL_MAPPING_TARGET_OVERLAP` (warning) | A tool `on_result` mapping writes the same variable as a call binding. |

The parser reports `E580` to `E587` for malformed blocks. A YAML-format agent with a `parallel` or `on_partial` key gets `E587`. The runtime refuses an agent with `PARALLEL` unless it supports the `flow_parallel_call` IR feature (`UNSUPPORTED_AGENT_IR_FEATURE`).

### SET

The `SET:` action assigns values to session variables:

```yaml theme={null}
FLOW:
  init:
    REASONING: false
    SET:
      status = "pending"
      retry_count = 0
      sanctions_clear = false
    THEN: next_step
```

Each assignment uses `variable = expression` syntax. The expression is resolved at execution time and can reference:

* Literal values: `"pending"`, `0`, `true`, `false`
* Variable references: `acctResult.balance`
* Function calls: `FORMAT_CURRENCY(amount, "USD")`, `COALESCE(value, "default")`, `ADD(a, b)`, `SUB(a, b)`, `ROUND(n, decimals)`
* Unique ID generation: `UNIQUE_ID(12)`
* Current timestamp: `NOW()`

An unquoted JSON array or object literal is stored as a structured value. A JSON string's string-typed leaves may contain `{{variable}}` templates — the collection is parsed first, then its string values are rendered, so substituted data is never reinterpreted as JSON:

```yaml theme={null}
SET:
  filters = [{"field":"customer","operator":"in","value":["Public", "{{employer_name}}"]}]
```

This stores an array of objects correctly even when `employer_name` contains quotes or backslashes. Prefer a direct variable reference when constructing a computed collection instead of interpolating one into JSON-shaped text:

```yaml theme={null}
SET:
  filters = [{"field":"customer","operator":"in","value":["Public", employer_name]}]
```

Surround the whole value with quotes when JSON-shaped *text* is intentional — `SET: payload_text = '[{"customer":"{{employer_name}}"}]'` stores a string, not a structured value. A session `TYPE` declaration alone doesn't validate every `SET` write; validate structured arguments at the tool boundary (pass the variable to a typed parameter, such as `filters: object[]`, through `WITH`).

**Tracing a SET.** Every `SET` block emits a `dsl_set` trace event. It lists each variable, the authored expression, the value it produced, and whether the expression could be evaluated. Variables that an agent declares sensitive are masked.

**Assigning the same variable on more than one line.** A step `SET` keeps every line and runs them one by one in written order. A later line reads what an earlier line wrote: `x = 1` then `x = x + 1` gives `2`. The compiler warns for each such variable (`STEP_SET_DUPLICATE_TARGET`). An agent version compiled by an earlier release keeps its earlier result until you publish it again. In that case, only the last line for the variable runs, at the position of the first line, and the trace records a `warning` event with code `set_duplicate_target_legacy_order`.

Branch (`ON_INPUT`, `ON_RESULT`, `ON_SUCCESS`, `ON_FAILURE`), `ON_START`, `DO`, `SUB_INTENTS`, and hook `SET` blocks keep one value per name. When a name is assigned twice, only the last assignment is used, and the parser reports the later line as [`W214`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w214).

**Quoted values in branch blocks.** In `ON_INPUT`, `ON_RESULT`, `ON_SUCCESS` and `ON_FAILURE` branches, in digression `DO` blocks, and in handoff `ON_RETURN` and return handlers, the parser removes the quotes from a `SET` value. The quotes decide how the value is read:

* Quoted text with spaces or punctuation, such as `transfer_stage: "AI Pre-call Stage"`, is stored as written. Validation does not report its words as variables.
* A quoted bare name or dotted path, such as `transfer_reason: "USER_REQUESTED_FOR_AGENT_TRANSFER"`, is read as the variable of that name when one exists. It is stored as text only when no such variable exists. The compiler warns with [`SET_QUOTED_VALUE_READ_AS_PATH`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#set_quoted_value_read_as_path).
* `{{name}}` placeholders inside the quoted text are still checked as variable reads.
* When the same assignment (same name, same value) is written both quoted and unquoted in one block, the two cannot be told apart after the quotes are removed. Validation treats both as a variable read.

A step-level `SET` keeps the quotes, so it always stores the text. Use it when a value must always be text.

**Literal `SET` value mode.** Literal mode stores a quoted value in these branch blocks as written, the same way a step-level `SET` does. It reads no variable and gives no warning. It is a project setting, `setValueMode`. A project runs in the legacy mode described above unless the setting is `literal`. In 1.10.0 the setting has no Studio control or settings API route. Each published version keeps the mode it was compiled with. A change applies from the next publish.

**Placeholders inside a formula.** A `SET` value that contains a `{{name}}` placeholder is never evaluated as an expression. The platform fills in the placeholders and stores the whole value as text. For example, `gate = LOWER(TRIM(TO_STRING("{{flag}}"))) == "true"` stores the text `LOWER(TRIM(TO_STRING("false"))) == "true"`. `IF gate` is then true, because the text is not empty. The compiler warns on every `SET` surface (`SET_PLACEHOLDER_IN_EXPRESSION`). To compute the value, name the variable without braces: `gate = LOWER(TRIM(TO_STRING(flag))) == "true"`. To store text, put the whole value in quotes: `label = "flag is {{flag}}"`.

The check reads only the syntax of the value. It reports a value with a placeholder when the value has a function call, a comparison, `&&`, `||`, `!`, a ternary, an index, or arithmetic where one side is a literal or a computed value (`{{count}} + 1`). It does not report a lone placeholder, a quoted value, a JSON object or array, prose, markdown, a URL, or arithmetic between names and placeholders only (`{{amount}} * {{rate}}`, `ref-{{id}}`). Text that joins a number and a placeholder, such as `2026-{{month}}`, is reported. Quote it to keep it as text. Values over 4,096 characters are not checked.

> [!WARNING]
>
> **Behavior change.** A computed `SET` value that cannot be evaluated no longer stores its own formula text. The variable gets no value, and the trace records a `warning` event with code `set_expression_not_evaluated`. Set `EXECUTION: set_expression_failure: keep_text` to keep the old behavior. See [When a SET value cannot be evaluated](https://koreai.mintlify.site/agent-platform/abl/reference/expressions-and-functions.md#when-a-set-value-cannot-be-evaluated).

### CHECK

The `CHECK:` action evaluates a condition. If the condition is false, execution transitions to the `ON_FAIL:` step:

```yaml theme={null}
FLOW:
  check_limits:
    REASONING: false
    CHECK: amount <= available_balance AND ADD(daily_used, amount) <= daily_limit
    ON_FAIL: over_limit
    THEN: proceed
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `CHECK` | `string` | -- | -- | Condition expression to evaluate |
| `ON_FAIL` | `string` | No | *none* | Step to go to if the condition is false |

The runtime evaluates `CHECK` when the step is entered. It runs after the step's `CLEAR`, `SET`, `LOG`, and `DO`, and before its `GATHER` and `CALL`. `CHECK` tests values that already exist when the step starts.

* A step `SET` applies before `CHECK`, so it also applies when `CHECK` fails. An attempt counter that `CHECK` reads relies on this. To assign a value only on success, put the `SET` inside an `ON_RESULT` branch.
* `CHECK` cannot read the step's own `GATHER` answer or `CALL` result. To decide on them in the same step, use `ON_RESULT`, which runs after `GATHER` and `CALL`.

### CLEAR

The `CLEAR:` action removes variables from the session context:

```yaml theme={null}
FLOW:
  reset_beneficiary:
    REASONING: false
    CLEAR: [beneficiary_name, beneficiary_account, beneficiary_id]
    THEN: collect_beneficiary
```

### TRANSFORM

The `TRANSFORM:` action filters, maps, sorts, and limits an array from the session context:

```yaml theme={null}
FLOW:
  filter_results:
    REASONING: false
    TRANSFORM:
      SOURCE: search_results
      AS: hotel
      INTO: filtered_hotels
      FILTER: "hotel.rating >= 4"
      MAP:
        name: hotel.name
        price: hotel.price_per_night
        rating: hotel.rating
      SORT_BY: price asc
      LIMIT: 5
    THEN: show_results
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `SOURCE` | `string` | Yes | -- | Dot-path to the source array |
| `AS` | `string` | Yes | -- | Loop variable name |
| `INTO` | `string` | Yes | -- | Output variable name |
| `FILTER` | `string` | No | *none* | Condition expression using the loop variable |
| `MAP` | `Record<string, string>` | No | *none* | Field mapping expressions |
| `SORT_BY` | `string` | No | *none* | Sort field and direction (`asc` or `desc`) |
| `LIMIT` | `number` | No | *none* | Maximum number of items in the output |

### LOG

The `LOG:` action emits a trace-only diagnostic (not shown to the user). Use the inline or block form:

```yaml theme={null}
FLOW:
  audit:
    REASONING: false
    LOG: "Entering audit step"
    # or, with a level:
    # LOG:
    #   MESSAGE: "Balance below threshold"
    #   LEVEL: warn          # debug | info | warn | error
    THEN: next_step
```

### AWAIT\_ATTACHMENT

The `AWAIT_ATTACHMENT:` action pauses the step until the user uploads a file.

```yaml theme={null}
FLOW:
  collect_id_doc:
    REASONING: false
    AWAIT_ATTACHMENT:
      NAME: id_document
      PROMPT: "Please upload a photo of your ID."
      CATEGORY: image        # image | document | audio | video
      REQUIRED: true
      TIMEOUT: 120
      ON_TIMEOUT: manual_review
    THEN: verify_id
```

| Property | Type | Description |
| - | - | - |
| `NAME` | `string` | Variable the uploaded attachment is stored under. |
| `PROMPT` | `string` | Message asking the user to upload. |
| `CATEGORY` | `string` | `image`, `document`, `audio`, or `video`. |
| `REQUIRED` | `boolean` | Whether the upload is mandatory. |
| `TIMEOUT` | `number` | Seconds to wait for the upload. |
| `ON_TIMEOUT` | `string` | Step to transition to if the upload times out. |

### SECURE\_INPUT

The `SECURE_INPUT:` action pauses the step to collect one or more **sensitive** values — a card number, CVV, or similar — via DTMF and/or speech, and delivers them **directly to one tool**, without the raw values ever passing through the LLM, transcript, session state, logs, call recordings, or traces: speech recognition is suppressed and recording is paused while the caller enters them, and the values are wiped from memory once the delivery call returns. It's the PCI-safe alternative to `GATHER` for data that must never reach the model.

```yaml theme={null}
FLOW:
  collect_card:
    REASONING: false
    SECURE_INPUT:
      MODE: [dtmf]                          # dtmf | speech, one or both
      FIELDS:
        - card_number:
            PROMPT: { en: "Please enter your 16-digit card number." }
            COLLECT: { digits: 13..19, finishOnKey: "#" }
            VALIDATE: [ luhn ]
        - cvv:
            PROMPT: { en: "And the 3-digit security code." }
            COLLECT: { digits: 3..4 }
      MAX_ATTEMPTS: 3
      CANCEL: { dtmf_key: "*" }
      CALL charge_card WITH: { pan: "{{secure.card_number}}", cvv: "{{secure.cvv}}" }
        AS: payment_result
        RESULT_FIELDS: [Status, TransactionIdentifier]
        SUCCESS_WHEN: { Status: "Success" }
      ON_SUCCESS: confirm
      ON_TIMEOUT: retry_by_agent
      ON_CANCEL: retry_by_agent
      ON_FAIL: human_agent
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "Your payment is complete. Reference: {{payment_result.TransactionIdentifier}}."
```

| Property | Type | Description |
| - | - | - |
| `MODE` | `("dtmf" \| "speech")[]` | Which collection channel(s) are accepted. Required; at least one. A spoken answer is read as a string of digits. Each spoken group gives its own digits, and the groups are put side by side: `eleven one two five` and `one one one twenty five` both give `11125`, and `oh nine twenty seven` gives `0927`. A whole number with `hundred` or `thousand` keeps its value: `eleven thousand one hundred twenty five` gives `11125`. Words that are not numbers are dropped, so a spoken `yes` gives no digits. |
| `FIELDS` | list | One or more fields to collect, in order. Each is a `- <name>:` entry with `PROMPT`, `COLLECT`, and optional `VALIDATE`. |
| `MAX_ATTEMPTS` | `number` | Failed collection attempts allowed before `ON_FAIL` (default 3). |
| `CANCEL` | `object` | Cancellation trigger: `dtmf_key` and/or `keywords` (a keyword must be spoken as its own word). |
| `CALL <tool> WITH: {...}` | — | The **delivery** call — the single tool invoked with the collected values. Only the inline-object `WITH:` form is supported. Reference a collected field as a whole-value placeholder `{{secure.<name>}}`. |
| `AS` | `string` | Session variable that receives the delivery response. Requires `RESULT_FIELDS`. |
| `RESULT_FIELDS` | `string[]` (with `AS`) | Top-level response fields that may be bound to `AS`; nothing else in the response is ever read. Exact top-level keys only — nested paths aren't supported. |
| `SUCCESS_WHEN` | `object` | `{ Field: "value" }` or `{ Field: [value1, value2] }` — which delivery responses count as success. See below. |
| `PROGRESS_PROMPT` | `string` or `object` | Hold line spoken while the delivery `CALL` runs. See [Hold line while a CALL runs](#hold-line-while-a-call-runs). |
| `ON_SUCCESS` | `string` | Step to transition to after successful collection and delivery. |
| `ON_TIMEOUT` | `string` | Step to transition to if collection times out. |
| `ON_CANCEL` | `string` | Step to transition to if the caller cancels. |
| `ON_FAIL` | `string` | Step to transition to if validation runs out of attempts, delivery fails, or `SUCCESS_WHEN` doesn't match. |

`AS`, `RESULT_FIELDS`, and `SUCCESS_WHEN` may be written indented under the `CALL` line or beside it; `AS: <name>` may also end the `CALL` line itself.

> [!WARNING]
>
> Every outcome route (`ON_SUCCESS`, `ON_TIMEOUT`, `ON_CANCEL`, `ON_FAIL`) takes a **step name only** — a `RESPOND` or any other block indented under a route isn't part of `SECURE_INPUT`; the parser reports the ignored line ([`W208`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w208)) and an empty route is a compile error ([`SECURE_INPUT_EMPTY_OUTCOME_ROUTE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_empty_outcome_route)). Put the response in the step the route names, as in the `confirm` step above.

**Success.** Without `SUCCESS_WHEN`, any 2xx delivery response takes `ON_SUCCESS`; a non-2xx status, a network failure, a timeout, or an unreadable body takes `ON_FAIL`. With `SUCCESS_WHEN`, a 2xx response must also match every listed field (compared as text, no case folding) or the step takes `ON_FAIL` — use this when an API can report a decline inside an HTTP 200. A delivery that timed out after the request was sent also takes `ON_FAIL`, even though the charge may have gone through — don't retry payment from that step.

**Reading the response.** `AS` binds only the `RESULT_FIELDS` the response contains, as top-level scalar values. A field is dropped (never bound) when its value contains any collected value's digits, contains a valid card number, or is an object or list — the step's trace names the bound/dropped fields, never their values. The bound fields are then ordinary session values for later steps, as `{{payment_result.Status}}` above.

#### Field properties

| Property | Type | Description |
| - | - | - |
| `PROMPT` | `{ <locale>: string }` or `{ template: string }` | Locale-keyed prompt text, or a reference to a named template. At least one non-empty entry is required. A locale reference such as `"{{locale.KEY}}"` also works. |
| `COLLECT` | `object` | `digits: N..M` (min/max digit count), `finishOnKey`, `interDigitTimeoutMs`, `asrTimeoutMs` (spoken-path silence window). |
| `VALIDATE` | list | Validation rules: a bare rule name (`luhn`), an inline object (`{ length: 4..4 }`, `{ date_mmYY: "not_past" }`), or a delegated `CALL <tool> WITH: {...}` rule. |
| `PROGRESS_PROMPT` | `string` or `object` | Hold line spoken while this field's `VALIDATE` `CALL` runs. |
| `NOT_SECRET` | `true/false` | Declares the field value readable. By default, all fields in a `SECURE_INPUT` step are secret. Set to `true` to allow the field value to be stored using `SAVE_AS` and accessed by subsequent steps, tools, traces, and reports. Use this option only for values that may be read, such as a billing ZIP code or a one-key consent. A `SECURE_INPUT` step must include at least one secret field. |
| `SAVE_AS` | `string` | Session variable that receives the `NOT_SECRET` value once the field is accepted. |
| `MODE` | `("dtmf" \| "speech")[]` | `NOT_SECRET` fields only. The input this field accepts. Without it, the field uses the step `MODE`. |
| `RECORD` | `true/false` | `NOT_SECRET` fields only. `true` keeps call recording on while this field is asked and answered, and shows the caller's answer in the transcript. |
| `SPEECH_AS` | `"digits" \| "text"` | `NOT_SECRET` fields only. How a spoken answer is read: `digits` (default) or `text` (the caller's words). |

A failed check asks for the field again, up to `MAX_ATTEMPTS`. A `CALL` validation rule passes only when the tool returns `valid: true`, and may reference the field being checked plus any fields collected before it. A field accepts only `PROMPT`, `COLLECT`, `VALIDATE`, `PROGRESS_PROMPT`, `NOT_SECRET`, `SAVE_AS`, `MODE`, `RECORD`, and `SPEECH_AS`. Anything else is ignored with a warning ([`W210`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w210)).

References inside the delivery `WITH:` block must be a **whole-value** placeholder — `pan: "{{secure.card_number}}"` is valid; embedding it in a larger string (`pan: "card:{{secure.card_number}}"`) or referencing an undeclared field is a compile error.

> [!WARNING]
>
> Every collected value lives only in a local secure buffer for the duration of the gate and is **zeroized on every exit path** (success, timeout, cancel, or failure) — it is never written to session state, so it cannot be referenced by `{{ }}` outside the delivery/validation calls, and it never appears in a trace, span, or log.

#### Hold line while a CALL runs

`PROGRESS_PROMPT` gives the caller something to hear while a secure `CALL` waits for its answer. On the block, the runtime speaks it during the delivery `CALL`. On a field, it speaks it during that field's `VALIDATE` `CALL`s. Built-in checks such as `luhn` finish at once and never speak it. The line plays with barge-in off, nothing is collected while it plays, and recording stays paused.

```yaml theme={null}
collect_card:
  SECURE_INPUT:
    # ...
    PROGRESS_PROMPT:
      TEXT: "{{locale.PAYMENT_PROCESSING}}"
      AFTER: 0s
      REPEAT_EVERY: 10s
      REPEAT_TEXT: { en: "Still working on it, thank you for holding.", es: "Sigo trabajando, gracias por esperar." }
```

| Property | Description |
| - | - |
| `TEXT` | Required. The line to speak, in the same forms as a field `PROMPT`: a language map or a template such as `"{{locale.KEY}}"`. |
| `AFTER` | Wait before the first line, `0s` to `60s` (`2s` or `1500ms`). Default `0s` on the block and `2s` on a field, so a quick check stays silent. |
| `REPEAT_EVERY` | Speak again while the `CALL` is still running, `5s` to `60s`. Without it, the line plays once. |
| `REPEAT_TEXT` | Line for each repeat, in the same forms as `TEXT`. Default: `TEXT`. |

`PROGRESS_PROMPT: "{{locale.PAYMENT_PROCESSING}}"` on one line is the text alone. The line is chosen for the caller's language the same way as a field `PROMPT`.

* A repeat never starts before the previous line has finished. The runtime attempts at most 12 lines during one `CALL`.
* A field with several `VALIDATE` `CALL`s speaks its line for each one that runs long enough.
* With the block default `AFTER: 0s`, the line always plays and the reply waits for it to finish (up to about 4 seconds). For a fast payment API, use `AFTER: 2s`.
* Hold lines resolve when the step starts, so a value saved during the step with `SAVE_AS` is not available to them.
* When the `CALL` returns, the step lets the last line finish before it speaks the next prompt or reply.
* A hold line that cannot be resolved does not fail the step. The runtime skips it and the trace records `secure_input_progress_unresolved`. On the block, the project's tool-call filler line plays instead.
* `TEXT` and `REPEAT_TEXT` can use session values and locale entries, but never `{{secure.*}}`.

#### Readable values (`NOT_SECRET`)

A value the agent needs later, such as a billing ZIP code or a one-key consent, can be collected in the same step and saved for the agent. Mark the field `NOT_SECRET: true` and name the session variable with `SAVE_AS`. Any field can be declared readable, and a step can hold any number of readable fields beside its secret ones:

```yaml theme={null}
- postal_code:
    PROMPT: "{{locale.BILLING_ZIP_PROMPT}}"
    COLLECT: { digits: 5..5, finishOnKey: "#" }
    VALIDATE: [ { regex: "^[0-9]{5}$" } ]
    NOT_SECRET: true
    SAVE_AS: billing_zip
```

The caller types the value with recording paused, like every other field. When it passes its checks, the runtime writes it to `billing_zip` as text and keeps a leading zero. From then on it is an ordinary session value. Later steps, reports, and tools read `{{billing_zip}}`. It is not part of the step's secure values, so a response field that echoes it is kept.

* The runtime clears each `SAVE_AS` variable when the step starts, so a value from an earlier run is never used. If it cannot clear the variable, the step takes `ON_FAIL` before it asks anything.
* The declaration is yours. The platform keeps no list of value kinds, field names, or digit counts that may be readable. The compiler rejects `NOT_SECRET` without `SAVE_AS` (or `SAVE_AS` without it) and `NOT_SECRET` with `READ_ONCE`. A `NOT_SECRET` field checked with `luhn` or `date_mmYY` is accepted with a warning ([`SECURE_INPUT_NOT_SECRET_CARD_DATA`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_not_secret_card_data)), because the card number or expiry would be saved where later steps, tools, and reports can read it.
* The runtime applies the same rules again. If they are broken, the step takes `ON_FAIL` before it asks anything.
* Only the field's own `VALIDATE` `CALL` can read `{{secure.<field>}}` for a `NOT_SECRET` field. Every later `CALL` reads the `SAVE_AS` variable.
* The step keeps at least one secret field, and the delivery sends at least one of them.

#### Voice and recording for readable values

A secret field is always collected with the step `MODE` and with call recording paused. Its Conversation row shows only the outcome (`Secure keypad entry: completed`). A `NOT_SECRET` field can change this with `MODE`, `RECORD`, and `SPEECH_AS`:

```yaml theme={null}
SECURE_INPUT:
  MODE: [dtmf]
  FIELDS:
    - card_number:
        PROMPT: { en: "Enter your card number, then press pound." }
        COLLECT: { digits: 13..19, finishOnKey: "#" }
        VALIDATE: [ luhn ]
    - consent:
        PROMPT: { en: "I'll charge {{amount}} to this card. Say yes or press 1 to confirm." }
        COLLECT: { digits: 1..1 }
        NOT_SECRET: true
        SAVE_AS: payment_consent
        MODE: [dtmf, speech]
        RECORD: true
        SPEECH_AS: text
        VALIDATE: [ { regex: "^(1|yes|yeah)( |$)" } ]
  CALL charge_card WITH: { pan: "{{secure.card_number}}", consent: "{{payment_consent}}" }
  ON_SUCCESS: payment_done
  ON_FAIL: payment_declined
```

* `MODE` lets the caller speak this field while the card fields stay keypad-only.
* `RECORD: true` resumes call recording before the field is asked. The Conversation row shows the answer (`Spoken entry: yes` or `Keypad entry: 1`). Before the next field without `RECORD`, recording is paused again. The gateway must confirm the pause. If it does not, that field is never asked and the step takes `ON_FAIL`. If the gateway does not confirm the resume, the `RECORD` field is still asked, at worst unrecorded.
* A step pauses and resumes recording each time it moves between a recorded field and an unrecorded one. Put readable fields first or last.
* `SPEECH_AS: text` keeps the caller's words instead of reading them as digits, so a `regex` can check them. The platform does not interpret the words. Your `VALIDATE` pattern decides what counts as yes. A failed check asks again with `RETRY_PROMPT`.

> [!WARNING]
>
> The caller can say anything while a `RECORD` field is asked. A card number spoken there is recorded and shown. Ask only for values that may be recorded. `MODE`, `RECORD`, or `SPEECH_AS` on a secret field is a compile error ([`SECURE_INPUT_FIELD_VOICE_ON_SECRET`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_field_voice_on_secret)), and the runtime ignores them there.

| Diagnostic | Fires when |
| - | - |
| [`SECURE_INPUT_INVALID_MODE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_invalid_mode) | `MODE` is missing, empty, or contains a value other than `dtmf`/`speech`. |
| [`SECURE_INPUT_MISSING_DELIVER_TOOL`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_missing_deliver_tool) | No delivery `CALL`. |
| [`SECURE_INPUT_MISSING_PROMPT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_missing_prompt) | No `FIELDS` are declared, or a field's `PROMPT` has neither a locale entry nor a `template` reference. |
| [`SECURE_EMBEDDED_PLACEHOLDER`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_embedded_placeholder) | A `{{secure.*}}` reference is part of a longer argument string instead of the whole value. |
| [`SECURE_UNKNOWN_FIELD`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_unknown_field) | A `{{secure.*}}` reference names a field the step doesn't collect. |
| `SECURE_INPUT_EMPTY_OUTCOME_ROUTE` | An outcome route (`ON_SUCCESS`/`ON_FAIL`/`ON_TIMEOUT`/`ON_CANCEL`) is written without a step name. |
| [`SECURE_INPUT_INVALID_RESULT_CONTRACT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_invalid_result_contract) | `AS` that isn't a plain variable name, `AS` without `RESULT_FIELDS` (or the reverse), a nested or repeated field name, an empty `SUCCESS_WHEN`, or a `SUCCESS_WHEN` field with no value. |
| [`RESERVED_VARIABLE_NAME`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#reserved_variable_name) / [`IMMUTABLE_SYSTEM_IDENTIFIER`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#immutable_system_identifier) | `AS` names a reserved or system-owned variable such as `session_id`. |
| [`SECURE_INPUT_INVALID_PROGRESS_PROMPT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_invalid_progress_prompt) | `PROGRESS_PROMPT` without `TEXT`, `AFTER` over 60 seconds, or `REPEAT_EVERY` outside 5 to 60 seconds. A `{{secure.*}}` in `TEXT` or `REPEAT_TEXT` reports [`SECURE_INPUT_PROMPT_SECURE_REFERENCE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_prompt_secure_reference). |
| [`SECURE_INPUT_PROGRESS_PROMPT_UNUSED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_progress_prompt_unused) (warning) | A field `PROGRESS_PROMPT` on a field without a `VALIDATE` `CALL`. |
| [`SECURE_INPUT_INVALID_NOT_SECRET`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_invalid_not_secret) | `NOT_SECRET` used outside the rules above, or `{{secure.<field>}}` of a `NOT_SECRET` field used outside its own `VALIDATE` `CALL`. |
| [`SECURE_INPUT_INVALID_SAVE_AS`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secure_input_invalid_save_as) | `SAVE_AS` is not a variable name, or it has the same name as `AS`, `SAFE_DETAILS_AS`, or another field's `SAVE_AS`. |
| `SECURE_INPUT_NOT_SECRET_CARD_DATA` (warning) | A `NOT_SECRET` field is checked with `luhn` or `date_mmYY`. The card number or expiry is saved readable. |
| `SECURE_INPUT_FIELD_VOICE_ON_SECRET` | `MODE`, `RECORD`, or `SPEECH_AS` on a field without `NOT_SECRET`. |
| `SECURE_INPUT_INVALID_FIELD_MODE` | A field `MODE` that is empty or names a channel other than `dtmf` or `speech`. |
| `SECURE_INPUT_INVALID_SPEECH_AS` | `SPEECH_AS` other than `digits` or `text`. |
| `SECURE_INPUT_SPEECH_AS_UNUSED` (warning) | `SPEECH_AS` on a field that neither its own `MODE` nor the step `MODE` lets the caller speak. |
| `W208` / `W210` | A line inside the block, or a field property, that `SECURE_INPUT` doesn't read — it's ignored. |
| [`W212`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w212) / [`W213`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w213) | A `PROGRESS_PROMPT` line other than `TEXT`, `AFTER`, `REPEAT_EVERY`, or `REPEAT_TEXT`, or a duration that is not `<n>s` or `<n>ms`. The runtime ignores it. |
| [`W211`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w211) | `RESULT_FIELDS` or `SUCCESS_WHEN` written across several lines; write them inline. |

### MESSAGE\_KEY and BEHAVIOR

Two additional step-level properties:

* **`MESSAGE_KEY:`** — a locale catalog key used to localize the step's `RESPOND:` message.
* **`BEHAVIOR:`** — free-form guidance text appended to the step's reasoning goal (a convenience alias that folds into `GOAL`).

### RESOLVE\_SIP\_DESTINATION

`RESOLVE_SIP_DESTINATION:` is a step action that computes a dynamic SIP transfer authority (VDN/host/port) **before** a `call_transfer` step runs. It runs a *feeder* — a workflow tool or a session memory key — matches the candidate against the `approved_authorities` allow-list declared on the `call_transfer` tool's `sipTransferId` parameter, and commits the approved authority to a trusted server-side routing channel that the transfer then reads. The model never sees or sets the destination.

```yaml theme={null}
FLOW:
  resolve_destination:
    REASONING: false
    RESOLVE_SIP_DESTINATION:
      FROM_WORKFLOW: "lookup_vdn_by_region_language"   # or: FROM_MEMORY: routing_decision
      TIMEOUT_MS: 1500
    THEN: transfer_step

  transfer_step:
    REASONING: false
    CALL: call_transfer(callTransferType: "sip")
    THEN: COMPLETE
```

| Sub-key | Type | Description |
| - | - | - |
| `FROM_WORKFLOW` | `string` | Name of a workflow tool invoked as the destination feeder. |
| `FROM_MEMORY` | `string` | Session memory key to read as the feeder (use instead of `FROM_WORKFLOW`). |
| `TIMEOUT_MS` | `number` | Hard timeout for the feeder, in milliseconds. |

The feeder's result supplies the `{{route.vdn}}` / `{{route.ip}}` / `{{route.port}}` values for the `sipTransferId` `template`. The two-zone template and the `approved_authorities` allow-list are declared on the tool parameter — see [Dynamic destinations](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#dynamic-destinations) in the tools reference.

***

## Branching and control flow

### THEN / ON\_FAIL

The most basic branching: `THEN:` specifies the next step on success, and `ON_FAIL:` specifies the step on failure:

```yaml theme={null}
FLOW:
  check_status:
    REASONING: false
    CHECK: account_status == "active"
    ON_FAIL: inactive_account
    THEN: proceed
```

`ON_FAIL:` also accepts a structured block for recovery flows — `COLLECT:` (fields to re-collect),
`GOTO:` (step), `RETRY: true`, `RESPOND:`, and `THEN:`:

```yaml theme={null}
FLOW:
  validate_details:
    REASONING: false
    CHECK: routing_number_valid == true
    ON_FAIL:
      RESPOND: "That routing number looks off — let's try again."
      COLLECT: [routing_number]
      GOTO: collect_routing
```

### ON\_RESULT

`ON_RESULT:` provides multi-way branching based on the result of a `CALL:` action. Each branch has an `IF:` condition, optional actions, and a `THEN:` transition:

```yaml expandable=true theme={null}
FLOW:
  verify_step:
    REASONING: false
    CALL: verify_account
      WITH:
        account_id: source_account
      AS: acctResult
    ON_RESULT:
      - IF: acctResult.status == "active"
        SET:
          customer_name = acctResult.owner_name
          balance = acctResult.available_balance
        RESPOND: "Account verified. Hello, {{customer_name}}."
        THEN: next_step
      - IF: acctResult.status == "frozen"
        RESPOND: "Your account is frozen. Please contact your branch."
        THEN: end
      - ELSE:
        RESPOND: "Account not found. Please check the number."
        THEN: collect_account
```

#### ON\_RESULT branch properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `IF` | `string` | No | -- | Condition expression. Omit for `ELSE` branch. |
| `RESPOND` | `string` | No | *none* | Message to display |
| `SET` | `Record<string, string>` | No | *none* | Variable assignments |
| `CALL` | `string` | No | *none* | Optional nested tool call |
| `THEN` | `string` | Yes | -- | Next step |

The `ELSE` branch (a branch with no `IF` condition) matches when no other condition is true.

Write an explicit `THEN` target on every authored branch. A branch without one does not survive the compiler round trip. For older compiled artifacts that have no branch target, the runtime keeps compatibility: a matched branch applies its actions and waits at the current step. It does not fall through to the enclosing step's response or continuation. Do not author branches without `THEN`.

An `ON_RESULT` response is an authored assistant message.

* If the `THEN` target asks another question, the branch response comes before that question in the turn's output. Each response keeps its own presentation and history entry, so advancing to a `GATHER` does not replace the earlier answer.
* A matched branch keeps its own continuation. It does not run the enclosing step's default response or continuation.
* Branch response text uses the configured output guardrails and PII protection. Structured display text is protected before delivery and history, including values found by asynchronous PII recognizers. Action values remain reversible vault tokens. Without a vault they keep their existing round-trip value.
* For payload blocks nested directly under an inline branch `RESPOND`, write `VOICE` first, then `FORMATS` (or `RICH_CONTENT`), then `ACTIONS`. The voice configuration belongs to that response, including when it comes before another step's prompt.

### ON\_SUCCESS / ON\_FAIL

An alternative to `ON_RESULT:` for simpler success/failure branching:

```yaml theme={null}
FLOW:
  call_api:
    REASONING: false
    CALL: submit_request
      WITH:
        data: request_data
      AS: result
    ON_SUCCESS:
      RESPOND: "Request submitted: {{result.id}}"
      THEN: done
    ON_FAIL:
      RESPOND: "Request failed. Please try again."
      THEN: retry_step
```

Both `ON_SUCCESS:` and `ON_FAIL:` support conditional branches:

```yaml expandable=true theme={null}
FLOW:
  process:
    REASONING: false
    CALL: process_order
      AS: orderResult
    ON_SUCCESS:
      - IF: orderResult.express == true
        RESPOND: "Express order confirmed!"
        THEN: express_fulfillment
      - ELSE:
        RESPOND: "Order confirmed."
        THEN: standard_fulfillment
    ON_FAIL:
      - IF: orderResult.error == "out_of_stock"
        RESPOND: "Item is out of stock."
        THEN: suggest_alternatives
      - ELSE:
        RESPOND: "An error occurred."
        THEN: error_handling
```

### ON\_INPUT

`ON_INPUT:` provides branching based on user input, typically used after a `GATHER:` action:

```yaml theme={null}
FLOW:
  confirm:
    REASONING: false
    GATHER:
      - confirmation: required
    ON_INPUT:
      - IF: input.contains("yes") OR input.contains("confirm")
        THEN: execute
      - IF: input.contains("no") OR input.contains("cancel")
        RESPOND: "Cancelled."
        THEN: cleanup
      - ELSE:
        RESPOND: "Please type 'yes' to confirm or 'no' to cancel."
        THEN: confirm
```

> [!WARNING]
>
> A step that has only `ON_INPUT` branches — no `RESPOND`/prompt and no default (`ELSE`) branch — traps any unmatched input on the same step forever. The compiler warns ([`FLOW_PROMPTLESS_ON_INPUT_UNMATCHED_TRAP`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#flow_promptless_on_input_unmatched_trap)): add a default `ELSE` route or an authored prompt unless the wait is intentional.

`ON_INPUT` and `ON_RESULT` conditions also bind `turn_input`. It holds the caller message of the current turn, the same value `RESPOND` renders as `{{input}}`. `input` holds the message the step owns. When a transition in the same turn enters the step, `input` is empty and `turn_input` keeps the caller message.

Each caller message is routed by one step. A promptless `ON_INPUT` gate routes the message that arrives at it. It does not route a message that an earlier step of the same turn already routed on. A gate entered by a branch `THEN` waits with no reply, and the caller's next message is routed there. `turn_input` in the gate's conditions does not change this, because its `ON_INPUT` branches are not evaluated in that turn.

To route on the same message in a second step, use `ON_RESULT` and read `turn_input`:

```yaml theme={null}
FLOW:
  triage:
    REASONING: false
    ON_INPUT:
      - IF: input contains "cancel"
        THEN: cancel_visit
      - ELSE:
        THEN: prefill_specialty

  prefill_specialty:
    REASONING: false
    ON_RESULT:
      - IF: turn_input contains "dermatology"
        SET: requested_specialty = "dermatology"
        THEN: ask_location
      - ELSE:
        THEN: ask_specialty
```

To wait for a new answer instead, `RESPOND` with the question on the branch or on a step before the gate. The compiler warns ([`FLOW_ON_INPUT_GATE_AFTER_CONSUMED_INPUT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#flow_on_input_gate_after_consumed_input)) when an `ON_INPUT` branch, or the `THEN` or `ON_RESULT` branch of a `GATHER` step, reaches a promptless `ON_INPUT` gate with nothing shown on the way. A `RESPOND` on the branch or on a step in between ends the warning for that route. Routes through a step with `DO` actions or `REASONING: true`, and a flow entered by a handoff or delegate, are not checked. The waiting `flow_step_exit` trace event carries `reason: input_consumed_by_previous_step`, the `consumingStep` that used the message, and the `enteredFromStep` the waiting step was entered from.

### Digressions

Digressions are intent-based escapes that can interrupt the current step. They match user intent patterns and respond accordingly:

```yaml expandable=true theme={null}
FLOW:
  collect_details:
    REASONING: false
    GATHER:
      - account: required

    DIGRESSIONS:
      - INTENT: "what is swift"
        RESPOND: "A SWIFT code is an 8 or 11 character code identifying a bank internationally."
        RESUME: true
      - INTENT: "cancel"
        RESPOND: "Transaction cancelled."
        GOTO: cleanup
      - INTENT: "speak to agent"
        RESPOND: "Connecting you with a specialist."
        DELEGATE: Live_Agent
```

#### Digression properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `INTENT` | `string` | Yes | -- | Intent pattern to match |
| `KEYWORDS` | `string[]` | No | *none* | Explicit keywords for matching |
| `CONDITION` | `string` | No | *none* | Additional condition to check |
| `RESPOND` | `string` | No | *none* | Response message |
| `MESSAGE_KEY` | `string` | No | *none* | Locale catalog key for the response |
| `SET` | `Record<string,string>` | No | *none* | Variable assignments (within the `DO:` block) |
| `RESUME` | `boolean` | No | `false` | Return to the current step after handling |
| `GOTO` | `string` | No | *none* | Transition to a specific step |
| `HANDOFF` | `string` | No | *none* | Hand off to another agent (supports `RETURN:` / `ON_RETURN:`) |
| `DELEGATE` | `string` | No | *none* | Delegate to another agent (requires `RETURN: true`) |
| `CALL` | `string` | No | *none* | Tool to invoke |
| `CLEAR` | `string[]` | No | *none* | Variables to clear |

When `RESUME: true`, the user returns to the interrupted step after the digression response. When `GOTO:` is specified, the flow transitions to that step instead. `RESUME`, `GOTO`, and `HANDOFF` are terminal.

> [!NOTE]
>
> For multiple ordered actions, use the canonical `DO:` block instead of flat keys. Each list item is
> an action (`RESPOND`, `SET`, `CLEAR`, `CALL`, `HANDOFF`, `DELEGATE`, `GOTO`, `RESUME`), and
> `HANDOFF`/`DELEGATE` may carry `RETURN:` and `ON_RETURN:` (with `MAP:`). Mixing flat keys with a
> `DO:` block is discouraged.
>
> ```yaml theme={null}
> DIGRESSIONS:
>   - INTENT: "check balance"
>     DO:
>       - RESPOND: "Let me pull that up."
>       - HANDOFF: Account_Info
>         RETURN: true
>       - RESUME: true
> ```

### Global digressions

Digressions declared at the flow level (under `global_digressions:`) are available at every step:

```yaml theme={null}
FLOW:
  global_digressions:
    - INTENT: "cancel"
      RESPOND: "Transaction cancelled."
      GOTO: cleanup

    - INTENT: "help"
      RESPOND: "I can help with account inquiries, transfers, and balance checks."
      RESUME: true

    - INTENT: "speak to agent"
      RESPOND: "Connecting you with a live agent."
      DELEGATE: Live_Agent_Transfer
```

### Sub-intents

Sub-intents are scoped intents valid only within a specific step. They handle step-specific user requests like corrections or clarifications:

```yaml expandable=true theme={null}
FLOW:
  collect_beneficiary:
    REASONING: false
    GATHER:
      FIELDS:
        - name: required
        - account: required
        - bank: required

    SUB_INTENTS:
      - INTENT: "change name"
        CLEAR: [name]
        RESPOND: "What is the correct name?"
      - INTENT: "change account"
        CLEAR: [account]
        RESPOND: "What is the correct account number?"
      - INTENT: "change bank"
        CLEAR: [bank, routing_code]
        RESPOND: "What is the correct bank name?"
```

#### Sub-intent properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `INTENT` | `string` | Yes | -- | Intent pattern to match |
| `RESPOND` | `string` | No | *none* | Response message |
| `MESSAGE_KEY` | `string` | No | *none* | Locale catalog key for the response |
| `CLEAR` | `string[]` | No | *none* | Variables to clear (triggers re-collection) |
| `SET` | `Record<string, string>` | No | *none* | Variables to set |
| `CALL` | `string` | No | *none* | Tool to invoke |
| `RESUME` | `boolean` | No | `true` | Stay in the current step |

***

## Interactive actions

Flow steps can present interactive UI elements (buttons, selects, inputs) to the user. These are attached to `RESPOND:` messages and handled with `ON_ACTION:` callbacks.

### Action elements

Interactive actions are defined in an `ACTIONS:` block within a step:

```yaml expandable=true theme={null}
FLOW:
  choose_option:
    REASONING: false
    RESPOND: "How would you like to proceed?"
    ACTIONS:
      - id: "option_transfer"
        type: button
        label: "Wire Transfer"
        value: "wire"
      - id: "option_ach"
        type: button
        label: "ACH Transfer"
        value: "ach"
      - id: "option_check"
        type: button
        label: "Send a Check"
        value: "check"
    ON_ACTION:
      - ACTION: "option_transfer"
        SET:
          transfer_method = "wire"
        THEN: wire_flow
      - ACTION: "option_ach"
        SET:
          transfer_method = "ach"
        THEN: ach_flow
      - ACTION: "option_check"
        SET:
          transfer_method = "check"
        THEN: check_flow
```

### Element types

#### Buttons

```yaml theme={null}
ACTIONS:
  - id: "confirm_btn"
    type: button
    label: "Confirm"
    value: "confirmed"
```

#### Select (dropdown)

```yaml theme={null}
ACTIONS:
  - id: "currency_select"
    type: select
    label: "Select currency"
    options:
      - id: "usd"
        label: "US Dollar"
        description: "United States Dollar"
      - id: "eur"
        label: "Euro"
        description: "European Union Euro"
      - id: "gbp"
        label: "British Pound"
```

#### Input fields

```yaml theme={null}
ACTIONS:
  - id: "amount_input"
    type: input
    label: "Enter amount"
    inputType: number
    placeholder: "0.00"
    required: true
```

### Action element properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `id` | `string` | Yes | -- | Unique identifier for the action element |
| `type` | `"button"` , `"select"` , `"input"` | Yes | -- | Element type |
| `label` | `string` | Yes | -- | Display label |
| `value` | `string` | No | *none* | Hidden value sent when the element is interacted with |
| `description` | `string` | No | *none* | Subtitle or helper text |
| `options` | `{id, label, description?}[]` | No | *none* | Options for `select` type |
| `inputType` | `"text"` , `"number"` , `"date"` , `"time"` , `"email"` | No | `"text"` | Input field type (for `input` type) |
| `placeholder` | `string` | No | *none* | Placeholder text (for `input` type) |
| `required` | `boolean` | No | `false` | Whether the input is required (for `input` type) |

### Form submission

When a step contains `input` type elements, you can configure a form submission button:

```yaml theme={null}
ACTIONS:
  - id: "name_input"
    type: input
    label: "Your name"
    inputType: text
    required: true
  - id: "email_input"
    type: input
    label: "Your email"
    inputType: email
    required: true
  SUBMIT_LABEL: "Submit"
  SUBMIT_ID: "form_submit"
```

The `ACTIONS:` block also accepts an optional `RENDER_ID:` to give the whole action set a stable
identifier for rendering/telemetry.

To place inputs, buttons, and text side by side, use `ROW`, `SUBMIT`, and `TEXT` items. See [Form layout](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md#form-layout).

### ON\_ACTION callbacks

The `ON_ACTION:` block defines handlers for user interactions with action elements:

```yaml theme={null}
ON_ACTION:
  - ACTION: "confirm_btn"
    RESPOND: "Confirmed! Processing your request."
    SET:
      confirmed = true
    THEN: process_step
  - ACTION: "cancel_btn"
    RESPOND: "Cancelled."
    THEN: cleanup
```

#### ON\_ACTION handler properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `ACTION` | `string` | Yes | -- | The `id` of the action element that triggered this handler |
| `CONDITION` | `string` | No | *none* | Optional value-based condition |
| `RESPOND` | `string` | No | *none* | Response message |
| `SET` | `Record<string, string>` | No | *none* | Variable assignments |
| `CLEAR` | `string[]` | No | *none* | Variables to clear |
| `CALL` | `string` | No | *none* | Tool to invoke (requires `AS`) |
| `LOG` | `string` | No | *none* | Trace-only diagnostic |
| `HANDOFF` | `string` | No | *none* | Hand off to another agent |
| `DELEGATE` | `string` | No | *none* | Delegate to another agent (`RETURN:`/`ON_RETURN:` supported) |
| `COMPLETE` | `boolean` | No | *none* | Terminal — mark the flow complete |
| `THEN` / `GOTO` / `TRANSITION` | `string` | No | *none* | Step to transition to (three interchangeable keywords) |

> [!NOTE]
>
> For multiple ordered actions in one handler, use a canonical `DO:` block whose list items are
> actions (`SET`, `CLEAR`, `LOG`, `RESPOND`, `CALL`, `GOTO`/`TRANSITION`/`THEN`, `HANDOFF`,
> `DELEGATE`, `COMPLETE`).

### Rich content

Steps can include rich content in multiple formats alongside `RESPOND:` messages. The runtime selects the appropriate format based on the channel. The block keyword is `RICH_CONTENT:` (canonical) or `FORMATS:` (original spelling, still accepted); the `.agent.yaml` format accepts `rich_content` or `formats` the same way.

```yaml theme={null}
FLOW:
  show_summary:
    REASONING: false
    RESPOND: "Here is your transfer summary."
    FORMATS:
      MARKDOWN: |
        ## Wire Transfer Summary
        | Field | Value |
        |-------|-------|
        | From | {{source_account}} |
        | To | {{beneficiary_name}} |
        | Amount | {{amount}} {{currency}} |
      ADAPTIVE_CARD: |
        {"type": "AdaptiveCard", "body": [...]}
```

#### Rich content format properties

The runtime recognizes these format keys. In addition to the messaging formats, several structured
template types are available (see [Rich content](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md) for their schemas):

| Format | Description |
| - | - |
| `MARKDOWN` | Formatted markdown text |
| `ADAPTIVE_CARD` | Microsoft Adaptive Cards JSON |
| `HTML` | HTML content |
| `SLACK` | Slack Block Kit JSON |
| `AG_UI` | AG-UI / CopilotKit event JSON |
| `WHATSAPP` | WhatsApp interactive message JSON |
| `CAROUSEL` | Scrollable cards (title/subtitle/image/buttons); can also be authored as a standalone block after `RESPOND:` |
| `QUICK_REPLIES` | Quick-reply chips |
| `LIST` | Vertical list of items |
| `IMAGE` | Image with caption/alt |
| `VIDEO` | Video with caption/alt |
| `AUDIO` | Audio with caption/alt |
| `FILE` | File attachment |
| `KPI` | KPI metric tile |
| `TABLE` | Columns + rows |
| `CHART` | Bar/line/pie chart |
| `FORM` | Form fields + submit |
| `PROGRESS` | Progress bar/circle |
| `FEEDBACK` | Thumbs/stars/scale feedback |

### Voice configuration

Steps can include voice-specific overrides for text-to-speech engines:

```yaml theme={null}
FLOW:
  greeting:
    REASONING: false
    RESPOND: "Welcome to wire transfer services."
    VOICE:
      SSML: |
        <speak>
          Welcome to <emphasis>wire transfer</emphasis> services.
        </speak>
      INSTRUCTIONS: "Speak in a warm, professional tone."
      PLAIN_TEXT: "Welcome to wire transfer services."
```

| Property | Type | Description |
| - | - | - |
| `SSML` | `string` | W3C SSML markup for TTS engines |
| `INSTRUCTIONS` | `string` | Natural language voice style instructions |
| `PLAIN_TEXT` | `string` | Voice-optimized plaintext (fallback for all engines) |
| `BARGE_IN` | `"allow"` \| `"disallow"` | Whether the caller may interrupt (barge in on) this spoken output. |
| `STREAMING` | `boolean` | TTS delivery mode for this spoken output. Omitted defaults to `true` (streaming). |
| `END_OF_SPEECH_TURN_TYPE` | `string` | Expected shape of the caller's next answer, used to pick an end-of-speech (pause) timeout. See [Per-turn endpointing](#per-turn-endpointing). |
| `END_OF_SPEECH_TIMEOUT_MS` | `number` | Explicit end-of-speech timeout in milliseconds, overriding the preset. |
| `TURN_DETECTION` | `object` | Gateway turn detection: `enabled` and an optional `eou_threshold` (0.3-0.9). See [Gateway turn detection](#gateway-turn-detection). |

#### Per-turn endpointing

`END_OF_SPEECH_TURN_TYPE` is a small, deliberately-closed vocabulary describing what kind of answer the caller is expected to give next — the runtime resolves it to a concrete end-of-speech (silence/pause) timeout for the active speech recognizer, so authors don't have to guess a millisecond value per turn:

| Value | Use for |
| - | - |
| `simple_confirmation` | A yes/no or short acknowledgement. |
| `structured_value` | A structured value like an account number or date. |
| `open_ended_question` | An open-ended question expecting a longer, free-form answer. |
| `complex_explanation` | A caller explanation that may take a while to finish. |
| `anything_else` | Anything not covered above. |

It can be set at any VOICE scope — agent-wide under `EXECUTION.voice`, on a behavior profile, on a flow step, or per `RESPOND` — with the narrowest scope winning, same as `BARGE_IN`/`STREAMING`:

```yaml theme={null}
FLOW:
  collect_value:
    REASONING: false
    VOICE:
      END_OF_SPEECH_TURN_TYPE: structured_value
      END_OF_SPEECH_TIMEOUT_MS: 900
    RESPOND: "Please provide the value."
      VOICE:
        END_OF_SPEECH_TURN_TYPE: open_ended_question   # per-RESPOND override
        END_OF_SPEECH_TIMEOUT_MS: 1400
```

`END_OF_SPEECH_TIMEOUT_MS` overrides the preset's timeout with an explicit millisecond value when set alongside (or instead of) `END_OF_SPEECH_TURN_TYPE`.

> [!NOTE]
>
> Per-turn endpointing applies to the platform's own speech-recognition pipeline. It does not affect TTS streaming, and is ignored on native realtime/speech-to-speech voice models where the provider owns turn detection. Omit it to fall back to the agent's conversation-level pause configuration.

#### Scoped barge-in

`barge_in` (values `allow` / `disallow`) sets whether the caller can interrupt a specific spoken output — for example, forcing a compliance disclosure to finish. It may be authored at three scopes, from broadest to narrowest, with the narrower winning:

```yaml theme={null}
FLOW:
  notice:
    REASONING: false
    BARGE_IN: disallow            # step-wide: applies to this step's outputs
    RESPOND: "This required notice must play in full."
      VOICE:
        BARGE_IN: allow           # per-RESPOND override for this output
```

The same keys are allowed in a nested `VOICE:` block under every reply a step can produce: `ON_SUCCESS`, `ON_FAILURE`, `ON_RESULT` and `ON_INPUT` branches, `SUB_INTENTS`, `DIGRESSIONS` and `ON_ACTION` `DO` actions. They're also allowed on a GATHER field ([Voice delivery for a field](#voice-delivery-for-a-field)) and in the step's `ON_NO_INPUT`.

**Precedence.** From narrowest to widest: the output's own `VOICE`, its template, its GATHER field, the tool reply policy, the step, the agent's `CONVERSATION.listening.barge_in`, then the channel setting. An absent value inherits the next layer. An explicit `allow` wins over a wider `disallow`, including a call-wide one.

It can also be set on a named template's `VOICE:` block. Placing `BARGE_IN` in a behavior-profile `VOICE` block, a channel-override `VOICE` block, a free-standing `ON_START` or branch `VOICE` block, or YAML `execution.voice` is rejected ([`VOICE_BARGE_IN_ILLEGAL_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_barge_in_illegal_placement)). In ABL `EXECUTION.voice` and `MESSAGES`, `BARGE_IN` and `STREAMING` are ignored with warning [`VOICE_DELIVERY_KEY_IGNORED_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_delivery_key_ignored_placement). `STREAMING` in the older placements compiles with [`VOICE_STREAMING_LEGACY_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_streaming_legacy_placement). In a constraint `ON_FAIL`, any voice line warns with [`CONSTRAINT_ON_FAIL_VOICE_ILLEGAL_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#constraint_on_fail_voice_illegal_placement). An invalid value is [`VOICE_INVALID_BARGE_IN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_barge_in).

> [!NOTE]
>
> This scoped, per-output policy is distinct from the agent-wide barge-in behavior authored under `CONVERSATION` → `listening`. Use scoped `barge_in` to protect (or open up) individual utterances.

#### Scoped streaming

`streaming` (`true` / `false`) sets the TTS delivery mode for a specific spoken output — whether audio starts playing as soon as the first tokens are ready (streaming, the default) or the runtime waits for the complete response before speaking it (non-streaming). It follows the same authoring scopes as `barge_in`: step-wide, per-`RESPOND`, or on a named template's `VOICE:` block, with the narrower scope winning.

```yaml theme={null}
FLOW:
  read_confirmation_code:
    REASONING: false
    STREAMING: false               # step-wide: wait for the full utterance before speaking it
    RESPOND: "Your confirmation code is {{confirmation_code}}."
      VOICE:
        STREAMING: false           # equivalent per-RESPOND override
```

Omitting `streaming` inherits the next layer. At the end of the chain the default is the producing agent's model streaming setting, which streams unless the agent sets it to false.

* **Derived turn-taking.** When the call's listening mode is derived as `turn_taking` (barge-in off and no explicit mode), output is buffered, and an authored `STREAMING: true` does not change that.
* **Connection Streaming switch.** When the channel connection's Streaming switch is Off, ordinary output is buffered in every mode, including output that authors `STREAMING: true`. Bring-your-own streaming-only speech vendors ignore the switch.
* **Vendor limits.** The effective value is the requested value limited by the speech vendor and delivery path. Regular speech providers play all `turn_taking` output buffered.
* **Secure input.** Secure-input prompts and progress speech can stream even when the connection Streaming switch is Off.

#### Step-level no-input (caller silence)

A FLOW step can carry its own caller-silence policy in its own `VOICE:` block, as `ON_NO_INPUT`. It takes the same keys as `CONVERSATION.listening.on_no_input` (agent/project-wide) and applies on KoreVG pipeline voice while that step is the one waiting on the caller:

```yaml theme={null}
CONVERSATION:
  listening:
    on_no_input:
      enabled: true
      mode: static
      timeout_ms: 5000
      max_retries: 3
      messages:
        - text: "Are you still there?"
        - text: "Hello?"

FLOW:
  ask_account:
    REASONING: false
    RESPOND: "What's your account number?"
    GATHER:
      - account_number: required
    VOICE:
      ON_NO_INPUT:
        timeout_ms: 10000
        messages:
          - text: "Could you tell me your account number, {{memo_name}}?"
    THEN: complete
```

* **Owner.** When the silence timer starts, the step currently waiting owns the window. The block applies only to that step; after `COMPLETE`/`ESCALATE`, or on a step with no block, the agent/project policy applies as usual.
* **Merging.** Fields merge one at a time over the project and agent policy — a step can override just `timeout_ms` and inherit everything else. `max_retries`, `relaxed_interval_ms`, `on_exhausted`, and `exhausted_message` all follow the same rule, and `enabled: true` on a step turns silence handling on for that step even when the agent has it off.
* **Messages.** Step messages don't *replace* the agent-level list — each silence plays agent message N followed by step message N as one utterance ("Are you still there? Could you tell me your account number, Sam?"). Once the step's own list is used up, the agent message plays alone (or the platform default, if the agent has none), so a step block never ends the call sooner than the agent alone would.
* **Retry count.** Restarts when the caller speaks, and when a different step (or the same step entered again) takes ownership of the window.
* **Variables.** `{{var}}` placeholders render in agent messages, step messages, and `exhausted_message`. A step message with a missing variable is skipped; an agent or exhausted message with a missing variable falls back to the platform default text.
* **Delivery.** `barge_in` (`allow` or `disallow`) and `streaming` (`true` or `false`) in `ON_NO_INPUT` apply to the step's reprompts and its exhausted message. A reprompt resolves the `ON_NO_INPUT` value, then the step's own `VOICE: BARGE_IN` or `STREAMING`, then the turn default. A step that authors either key is published with the IR marker `voice_no_input_policy`. A runtime without the marker refuses the agent.

> [!WARNING]
>
> `ON_NO_INPUT` is only allowed directly in a FLOW step's own `VOICE:` block. Placed under a GATHER field, `RESPOND`, a branch, a handler, or a response format, it's a compile error ([`VOICE_NO_INPUT_ILLEGAL_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_no_input_illegal_placement)). The YAML format uses a step-level `on_no_input:` key.

#### Gateway turn detection

`TURN_DETECTION` turns KoreVG gateway turn detection on or off for a level and sets its patience. With it on, the voice gateway decides when the caller finished speaking (voice activity, acoustic/text end-of-turn models, speech-provider finals) instead of the speech provider's silence timer.

It can be set at any VOICE scope: a concrete `RESPOND`'s `VOICE` block, a flow-step `VOICE` block, a GATHER field `VOICE` block, a behavior-profile `VOICE` block, or `EXECUTION.voice`:

```yaml theme={null}
EXECUTION:
  voice:
    turn_detection:
      enabled: true
      eou_threshold: 0.6

FLOW:
  ask_account:
    REASONING: false
    VOICE:
      turn_detection: { enabled: false }
    GATHER:
      - account_number:
          TYPE: string
          PROMPT: "What is your account number?"
```

| Key | Type | Values | Description |
| - | - | - | - |
| `enabled` | `boolean` | `true`, `false` | Required. `false` turns it off at this level, even when the channel has it on. |
| `eou_threshold` | `number` | `0.3`-`0.9` in steps of 0.1 | Patience: `0.3` answers fastest; `0.8` (Dictation) waits through long pauses like card numbers; `0.9` (Slow dictation) waits longest, for letter-by-letter spelling and long reference numbers. Omitted: falls through to the next level's value, else `0.5`. |

Precedence, most specific first: the response (or step, or field) that asks the caller something, the active behavior profile, `EXECUTION.voice`, the voice channel's own turn-detection setting, off. A response/step value applies to the caller's answer to it and holds while the step re-asks (retries); the next answered response with no key falls back up the chain. On a `REASONING: true` step (model writes the replies), the step's own `turn_detection` applies to every caller turn while the conversation stays in that step (only `turn_detection` is taken from that step's VOICE, nothing else).

An invalid value is a compile error ([`VOICE_INVALID_TURN_DETECTION`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_turn_detection)) and is never applied. A KoreVG gateway without the Dictation/Slow dictation profile uses its most patient profile instead (`0.9` falls to `0.8`, or `0.7` if `0.8` is also missing).

> [!NOTE]
>
> Gateway turn detection applies to KoreVG pipeline calls only, never realtime (speech-to-speech), other voice transports, or the PCI `SECURE_INPUT` gather. While turn detection is on, the gateway ignores the end-of-speech timeout, so a block that turns it on AND also sets `END_OF_SPEECH_TURN_TYPE` or `END_OF_SPEECH_TIMEOUT_MS` gets a compile warning [`VOICE_TURN_DETECTION_WITH_END_OF_SPEECH`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_turn_detection_with_end_of_speech).

***

## Step-level error handling

Steps can define local error handlers that override agent-level `ON_ERROR:` handlers:

```yaml expandable=true theme={null}
FLOW:
  call_external:
    REASONING: false
    CALL: external_api
      WITH:
        query: user_query
      AS: apiResult
    ON_ERROR:
      tool_error:
        RESPOND: "The service is responding slowly. Retrying..."
        SUBTYPE: tool_timeout
        RETRY: 2
        RETRY_DELAY: 1000
        RETRY_BACKOFF: exponential
        RETRY_MAX_DELAY: 8000
        THEN: CONTINUE
      validation_error:
        RESPOND: "An error occurred. Let me try a different approach."
        THEN: RETRY_STEP
```

The error type (the handler's key) is matched against a **fixed, canonical set** —
`default`, `llm_error`, `tool_error`, `routing_error`, `validation_error`, `timeout_error`, and
`unknown_error`. A key outside this set (for example the older `tool_timeout`, `invalid_input`, or
`api_error`) is flagged at compile time ([`ON_ERROR_HANDLER_TYPE_DRIFT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_error_handler_type_drift)) and never matches at
runtime — see [Error types](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#error-types) for the
full table and the deprecated-name mapping. Narrow a handler with `SUBTYPE`/`SUBTYPES`. Known
values: `rate_limit`, `auth_failure`, `network_error`, `tool_timeout` for `tool_error`, and
`timeout`, `content_filter`, `rate_limited`, `context_exceeded`, `api_error` for `llm_error`.

### List form and map form

Write a step's handlers as `- TYPE:` list items, or keyed by type like agent-level handlers. Both forms are equivalent:

```yaml expandable=true theme={null}
FLOW:
  # List form
  answer_billing:
    REASONING: true
    GOAL: "Answer the billing question"
    ON_ERROR:
      - TYPE: llm_error
        SUBTYPE: timeout
        RESPOND: "Sorry, that took too long. Could you ask again?"
        RETRY: 1
        RETRY_DELAY: 1000
        RETRY_BACKOFF: fixed
        THEN: RETRY_STEP
      - TYPE: llm_error
        SUBTYPES: [content_filter, api_error]
        SET: needs_human = true
        RESPOND: "Let me pass this to a colleague."
        THEN: BACKTRACK
        BACKTRACK_TO: handover
    THEN: wrap_up
```

A type can repeat. Handlers match subtype first, so the `timeout` entry wins for a timeout and the second `llm_error` entry catches the listed subtypes.

* A step handler takes `SUBTYPE` or `SUBTYPES`, a one-line `RESPOND`, any number of `SET: name = expression` lines (applied before `RESPOND` is rendered), `RETRY`, `RETRY_DELAY`, `RETRY_BACKOFF`, `THEN`, `BACKTRACK_TO`, and `HANDOFF_TARGET`.
* `VOICE`, `FORMATS`, multi-line responses, and `TEMPLATE(name)` references work on agent-level handlers only.
* **Which handler runs.** The step's handlers are checked first, then the agent's, then the agent's default handler. Within each, a subtype match wins over a type match, which wins over `DEFAULT`. A matching step handler replaces the agent-level handler for that step, including its `RESPOND`. When no handler matches a model error, a declared `unknown_error` handler is used.
* **Where step handlers apply.** They cover a `REASONING: true` step's own model calls, its scripted `CALL:`, and its other step-owned errors. An error from a tool the model calls, and a `validation_error` after a field's `MAX_RETRIES`, use the agent-level handlers only.

### When a reasoning step's model call fails

A model error in a `REASONING: true` step (`llm_error`: a timeout, a content filter, a rate limit, and other model failures) first runs the handler's `RETRY`, if any. If the call still fails, `THEN` decides what happens on that turn:

| `THEN` | On the failed turn | With `EXIT_WHEN` |
| - | - | - |
| `BACKTRACK` | The handler's `RESPOND` is sent, then `BACKTRACK_TO` runs in the same turn and its reply follows. Naming the failing step itself acts like `CONTINUE`. | Ignored: the step is left. |
| `COMPLETE` | The handler's `RESPOND` is sent and the flow completes. The completion's own reply, if any, follows. | Ignored: the step is left. |
| `RETRY_STEP` | The handler's line is the reply. The conversation stays in the step and the next message runs it again. Counts toward `MAX_ATTEMPTS`, then `ON_EXHAUSTED` applies. | Not evaluated on the failed turn. |
| `CONTINUE` | The handler's line is the reply. Without `EXIT_WHEN` the step advances to its `THEN`. | Not met (the usual case): the step waits and runs again on the next message. Met: `THEN` runs in the same turn. |
| `HANDOFF` | The handoff target takes over. The handler's `RESPOND`, if any, is the reply. | Ignored. |
| `ESCALATE` | The escalation routine runs. The handler's line, or "Escalating to a human agent.", is the reply. | Ignored. |

* **Without a `RESPOND`.** `BACKTRACK` and `COMPLETE` send no error line: the target step, or the completion, speaks. `CONTINUE`, `RETRY_STEP`, and a `BACKTRACK` naming the failing step send the platform fallback line below. `HANDOFF` lets the target answer.
* **`RETRY` versus `RETRY_STEP`.** `RETRY: N` repeats the failed model call up to `N` more times in the same turn. Only a model timeout, a rate limit, and an unavailable provider are retried. A retry is not attempted once the failed attempt has streamed part of its reply. `RETRY_STEP` waits for the customer's next message.
* **Model time limit.** A call times out when the step's `EXECUTION: llm_timeout` (else the agent's) runs out, capped by the server limit and the turn's remaining time. A caller cancellation is not a timeout and runs no handler.

#### Platform fallback lines

When a handler has no `RESPOND` and needs one, the customer sees the agent's message for the error's subtype:

| Message key | Sent for | Default text (English) |
| - | - | - |
| `error_llm_timeout` | `llm_error` / `timeout` | "I apologize for the delay. Could you please repeat your request?" |
| `error_llm_content_filter` | `llm_error` / `content_filter` | "An error occurred. Please try again." |
| `error_llm_rate_limited` | `llm_error` / `rate_limited` | "An error occurred. Please try again." |
| `error_llm_context_exceeded` | `llm_error` / `context_exceeded` | "An error occurred. Please try again." |
| `error_llm_api_error` | `llm_error` / `api_error` | "An error occurred. Please try again." |
| `error_default` | Any other error | "An error occurred. Please try again." |

Replace a line for one agent in `MESSAGES:`, or per language in `locales/<locale>/<agent>.json` (one agent) or `locales/<locale>/_shared.json` (all agents). A locale file wins over `MESSAGES`, which wins over the default.

```yaml theme={null}
MESSAGES:
  error_llm_timeout: "One moment, please. Could you say that again?"
```

#### Step ON\_ERROR handler properties

| Property | Type | Description |
| - | - | - |
| `SUBTYPE` | `string` | Narrow the handler to a specific error subtype. |
| `SUBTYPES` | `string[]` | Narrow the handler to any of several error subtypes. |
| `SET` | `string` | `name = expression`. Repeatable. Applied before `RESPOND` is rendered. |
| `RESPOND` | `string` | One-line message to show when the error fires. |
| `RETRY` | `number` | Retry attempts before giving up. |
| `RETRY_DELAY` | `number` | Delay (ms) between retries. |
| `RETRY_BACKOFF` | `string` | Backoff strategy: `fixed`, `exponential`, or `linear`. |
| `RETRY_MAX_DELAY` | `number` | Maximum delay (ms) between retries. |
| `BACKTRACK_TO` | `string` | Step to backtrack to (used with `THEN: BACKTRACK`). |
| `HANDOFF_TARGET` | `string` | Target agent (used with `THEN: HANDOFF`). |
| `THEN` | `string` | Next action: `CONTINUE`, `COMPLETE`, `ESCALATE`, `BACKTRACK`, `RETRY_STEP`, or `HANDOFF`. A step name is **not** a valid value here — a flow step's own `THEN:` navigates to a step, but an `ON_ERROR` handler's `THEN:` takes only one of these six actions. |

## Complete example

```yaml expandable=true theme={null}
AGENT: Simple_Order
VERSION: "1.0.0"

GOAL: "Help customers place orders."

PERSONA: "Friendly order assistant."

TOOLS:
  check_inventory(product_id: string) -> {available: boolean, quantity: number}
    description: "Check product availability"
    type: http
    endpoint: "/api/inventory/check"
    method: GET

  place_order(product_id: string, quantity: number) -> {order_id: string, total: number}
    description: "Place an order"
    type: http
    endpoint: "/api/orders"
    method: POST

FLOW:
  entry_point: welcome

  steps:
    - welcome
    - collect_product
    - check_stock
    - out_of_stock
    - collect_quantity
    - confirm
    - place
    - done

  global_digressions:
    - INTENT: "cancel"
      RESPOND: "Order cancelled."
      GOTO: done

  welcome:
    REASONING: false
    RESPOND: "Welcome! What product are you looking for?"
    THEN: collect_product

  collect_product:
    REASONING: false
    GATHER:
      - product_id: required
        prompt: "What is the product ID?"
    THEN: check_stock

  check_stock:
    REASONING: false
    CALL: check_inventory
      WITH:
        product_id: product_id
      AS: stockResult
    ON_RESULT:
      - IF: stockResult.available == true
        SET:
          stock_quantity = stockResult.quantity
        RESPOND: "Great news! We have {{stock_quantity}} in stock."
        THEN: collect_quantity
      - ELSE:
        THEN: out_of_stock

  out_of_stock:
    REASONING: false
    RESPOND: "Sorry, that product is currently out of stock."
    THEN: done

  collect_quantity:
    REASONING: false
    GATHER:
      - quantity: required
        type: number
        prompt: "How many would you like to order?"
    CHECK: quantity <= stock_quantity
    ON_FAIL: collect_quantity
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "You'd like to order {{quantity}} of {{product_id}}. Confirm?"
    ACTIONS:
      - id: "yes"
        type: button
        label: "Confirm"
      - id: "no"
        type: button
        label: "Cancel"
    ON_ACTION:
      - ACTION: "yes"
        THEN: place
      - ACTION: "no"
        RESPOND: "Order cancelled."
        THEN: done

  place:
    REASONING: false
    CALL: place_order
      WITH:
        product_id: product_id
        quantity: quantity
      AS: orderResult
    ON_SUCCESS:
      RESPOND: "Order placed! Order ID: {{orderResult.order_id}}, Total: {{orderResult.total}}"
      THEN: done
    ON_FAIL:
      RESPOND: "Failed to place order. Please try again later."
      THEN: done

  done:
    REASONING: false
    RESPOND: "Thank you for using our service!"
```

***

**Related articles:**

* [Language overview](https://koreai.mintlify.site/agent-platform/abl/reference/language-overview.md) -- syntax rules and auto-detection
* [Tools](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md) -- tool definitions used by `CALL` actions
* [GATHER](https://koreai.mintlify.site/agent-platform/abl/reference/gather.md) -- top-level gather field definitions
* [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md) -- GOAL used by `REASONING: true` steps, `max_flow_iterations` and model settings


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