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

# Lifecycle and hooks

ABL provides lifecycle handlers and hooks that execute at specific points in an agent's execution cycle. These allow you to initialize state, run side effects, and handle errors without embedding that logic in the main conversation flow.

## Overview

| Handler | When it fires |
| - | - |
| `ON_START` | Once per session, before any user input. |
| `HOOKS` | At defined lifecycle points (before/after agent, turn). |
| `ON_ERROR` | When a specific error type occurs during execution. |

## ON\_START handler

The `ON_START` handler executes once when a new session initializes, before the agent processes any user input. Use it for greeting messages, initial tool calls, and variable initialization.

### Syntax

```yaml theme={null}
ON_START:
  SET:
    session_initialized = true
    transfer_status = "pending"
    retry_count = 0
  CALL: check_returning_user()
  RESPOND: |
    Welcome to Wire Transfer Services. I can help you send
    a domestic or international wire transfer.
    Which account would you like to send from?
```

### ON\_START properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `SET` | `Record<string,string>` | No | -- | Variable assignments executed at session start. |
| `CALL` | `string` | No | -- | Tool to call during initialization (supports `WITH:`/`AS:`). |
| `DELEGATE` | `string` | No | -- | Agent to delegate to during initialization. |
| `RESPOND` | `string` | No | -- | Greeting or welcome message sent to the user. |
| `MESSAGE_KEY` | `string` | No | -- | Locale catalog key used to localize the greeting. |
| `VOICE` | `object` | No | -- | Voice overrides for the response, including `BARGE_IN` and `STREAMING`. See [Voice delivery for lifecycle replies](#voice-delivery-for-lifecycle-replies) and [Rich content](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md). |
| `RICH_CONTENT` | `object` | No | -- | Rich content format variants (the `.agent.abl` keyword is `FORMATS:`). See [Rich content](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md). |
| `ACTIONS` | `object` | No | -- | Interactive actions attached to the response. |
| `BRANCHES` | `object[]` | No | -- | Conditional greeting branches (`IF`/`ELSE`). See [Conditional greeting](#conditional-greeting). |

### Template references in ON\_START

You can reference named templates in the RESPOND value:

```yaml theme={null}
ON_START:
  RESPOND: TEMPLATE(welcome)
```

This renders the template named `welcome` from the agent's `TEMPLATES:` block.

### ON\_START with tool call

```yaml theme={null}
ON_START:
  CALL: check_cut_off_times(transfer_type = "all")
  SET:
    sanctions_clear = false
    fraud_score = 0
  RESPOND: "Welcome. Let me check today's processing windows."
```

The tool call executes first, and its result is available in the session context when the RESPOND message is rendered.

### Guarding a CALL with WHEN

An `ON_START` or hook `CALL` can carry an indented `WHEN:` guard so it only runs when the condition holds:

```yaml theme={null}
ON_START:
  CALL: find_member_by_ani
    WITH:
      callerAni: ani_national
    WHEN: ani_national != ""

HOOKS:
  before_agent:
    CALL: load_profile
      WHEN: member_id != ""
```

> [!WARNING]
>
> The `WHEN:` must be indented **under**`CALL:`, not written as its sibling at the same indent. A sibling `WHEN:` is not read — the call runs unconditionally, and the parser warns [`W496`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w496).

The same rules apply in `HOOKS`. A false or unevaluable guard skips only the tool invocation. The following `SET` and `RESPOND` actions still run. The compiler rejects invalid CEL syntax. In YAML, the guard is `call_spec.when`. In compiled IR, it is `call_when`. A guard does not bypass the tool's ordinary authority, timeout, confirmation, or effect contracts.

### Conditional greeting

Use a `BRANCHES:` block to vary the greeting based on session context. Each branch is an `IF`
(or `CONDITION`) with a fallback `ELSE`, and can carry `RESPOND`, `MESSAGE_KEY`, `VOICE`, rich
content, and `ACTIONS`.

```yaml theme={null}
ON_START:
  CALL: check_returning_user()
  BRANCHES:
    - IF: user.is_returning == true
      RESPOND: "Welcome back, {{user.name}}!"
    - ELSE:
      RESPOND: "Welcome! How can I help you today?"
```

### ON\_START language resolution

A reasoning agent with no FLOW can resolve the caller's language from a startup `SET`/`CALL` and apply it before the welcome renders:

```yaml theme={null}
AGENT: Welcome_Agent
GOAL: "Help the caller"
TOOLS:
  resolve_runtime_context_v1() -> object
    description: "Resolve the caller language and greeting"
ON_START:
  CALL: resolve_runtime_context_v1
    AS: runtime_context
  SET_INTERACTION_LANGUAGE: "{{runtime_context.spoken_language}}"
  RESPOND: "{{runtime_context.greeting_text}}"
```

The tool needs an execution binding in the project. Top-level language directives resolve after top-level `SET`/`CALL` and before branch selection; a `BRANCHES` `DO:` list (below) can set the language too. On **Gemini Live** specifically, `ON_START` already runs before the initial provider setup, so the first connection uses this language in legacy, `runtime_guarded`, and `runtime_owned` orchestration modes — the channel must have the language configured in its own supported-language policy, or an unresolved/unsupported value is rejected without changing the policy default.

### Start-time HANDOFF

A `BRANCHES:` entry (or a bare top-level `HANDOFF:`) can hand the session to another declared local agent at start, before the first customer message is even understood. A branch's `DO:` list runs these actions in order, by default *after* the welcome renders:

| Action | Effect |
| - | - |
| `SET:` | Assigns session values. |
| `SET_INTERACTION_LANGUAGE:` / `CLEAR_INTERACTION_LANGUAGE:` | Sets or clears the voice language, same as elsewhere. |
| `CALL:` | Calls a tool (`WITH:`/`AS:`, as in a FLOW step `DO:`). A failed call stops the list. |
| `HANDOFF: <Agent>` | Names a target already declared in the agent's top-level `HANDOFF:` block — it carries no inline options of its own. The named target's declared `WHEN`, `EXPECT_RETURN` (the primary keyword; the older `RETURN` is still accepted as a back-compat alias — see [Return expectations](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#return-expectations)), `CONTEXT`, `EXPERIENCE_MODE`, `ON_RETURN`, and `ON_FAILURE` all apply through the normal handoff lifecycle. At most one handoff per list. |

If the list sets the interaction language, the prefix through the last language directive (before any `HANDOFF`) runs *before* the welcome renders instead, and the rest after:

```yaml theme={null}
SUPERVISOR: Router
GOAL: "Route customers by the page they came from"

TOOLS:
  get_welcome(page: string) -> object
    description: "The welcome for the page the customer came from"

HANDOFF:
  - TO: Product_Search
    RETURN: true
    CONTEXT:
      pass: [page_name, welcome]
  - TO: Order_Agent
    RETURN: false

ON_START:
  CALL: get_welcome
    WITH:
      page: page_name
    AS: welcome
  BRANCHES:
    - IF: page_name == "beauty_hub_screen"
      RESPOND: "{{welcome.text}}"
      DO:
        - SET: entry_source = "app"
        - HANDOFF: Product_Search
    - ELSE:
      RESPOND: "Hi, how can I help?"
```

A top-level `HANDOFF: <Agent>` (bare, bulleted, or the sole entry of a top-level `DO:`) runs only when **no branch matched** — a matched branch with no `DO:` list never falls back to it. With no branches at all, a bare `HANDOFF:` is instead decided by that declared route's own `WHEN` (and `ENABLED_WHEN`), checked once at session start:

```yaml theme={null}
SUPERVISOR: Router
GOAL: "Send customers who came from the sales page to Sales"

HANDOFF:
  - TO: Sales
    WHEN: page_name == "sales"
    RETURN: false

ON_START:
  RESPOND: "Welcome."
  HANDOFF: Sales
```

> [!WARNING]
>
> `DELEGATE` and any other action in an `ON_START` list is dropped with a warning ([`W380`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w380)-[`W388`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w388)) — it is never run from here. A handoff target that isn't a declared local `HANDOFF` entry is a compile error ([`ON_START_HANDOFF_TARGET_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_start_handoff_target_invalid)). The start-time handoff is local only: a remote (A2A) target is always refused. A route `WHEN` that only a model could judge (natural language, `intent.*`) is never satisfied by the **top-level**`ON_START: HANDOFF:` (it has no branch `IF:`, so its route `WHEN` must be met from start data alone). A `BRANCHES:` entry is different: once its `IF:` selects the handoff, a route `WHEN` the start data genuinely can't decide no longer blocks it — only a `WHEN` the start data *can* evaluate is applied, and a false one still blocks.

| Diagnostic | Severity | Catches |
| - | - | - |
| [`ON_START_HANDOFF_ACTIVATED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_start_handoff_activated) / [`ON_START_BRANCH_DO_ACTIVATED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_start_branch_do_activated) | warning (informational) | Confirms a top-level `HANDOFF`, or a branch's `DO:` list, really does run at session start — a reminder, not a mistake. |
| [`ON_START_HANDOFF_UNREACHABLE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_start_handoff_unreachable) | warning | A top-level `HANDOFF:` is dead code because an `ELSE` branch always matches first, so the fallback handoff can never run. |
| [`ON_START_DELEGATE_WITH_HANDOFF`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#on_start_delegate_with_handoff) | warning | `ON_START` configures both a top-level `DELEGATE:` and a handoff — when the handoff runs, the child owns the session and the delegate is never returned. Keep one or the other. |

**How it runs, by channel and start type:**

| Channels | Start type | What the customer experiences |
| - | - | - |
| Pipeline Voice; Web SDK / Web Debug (without an `initialMessage`); an identified agent-assist session with a welcome | Eager | The welcome plays, then the child is handed the session and waits — it does not speak its own opener. |
| HTTP Chat; LiveKit; Web SDK with `initialMessage` | Lazy | No welcome. The customer's first message is forwarded straight to the child. |
| Realtime speech-to-speech | Realtime | `SET`/`CALL` in the list still run, but the handoff itself never does — the entry agent keeps the session. |

* **Eager start** (no user message yet — Web SDK/web-debug connect, pipeline voice answer, an identified agent-assist welcome): the welcome is delivered and the child is activated **without running** — its `before_agent` hook runs, but neither a FLOW child's entry step nor a reasoning child's model runs before the user says anything. The user's first message is then forwarded to the child exactly as on a lazy start: a FLOW entry step with an extraction contract (`extraction_hints`, `options`, or a non-string `type`) takes its value from that message, a plain field asks its own question instead, and an `ON_INPUT` on the entry step takes the message as its input; a reasoning child answers it as its first request. Output order: the entry agent's `before_agent` output, the welcome, the handoff announcement (when `EXPERIENCE_MODE` speaks one), the child's `before_agent` output — the child's own opener is no longer part of this list, because the child hasn't run yet. A child that has answered no request yet stays active even if it returns (`RETURN: true`); ordinary return rules apply from the user's first message on. A child that hands the very first message straight back (for example an off-topic question) ends there instead of parking, so a later route to it starts the child fresh. A start with no welcome and no child `before_agent` output sends nothing — on pipeline voice the caller hears only the welcome (if any) and the child stays silent until the caller speaks.
* **Lazy start** (the first user message starts the session — HTTP chat, LiveKit, SDK `initialMessage`): the welcome is **not** delivered, and that first message is forwarded to the child once — after the entry agent's input guardrails/constraints (and, for a FLOW entry, its `before_turn` hook) — taking precedence over the entry agent's own first-turn routing.
* **Realtime speech-to-speech** sessions run the list's `SET`/`CALL` but never the handoff itself; the entry agent keeps the session.

Every outcome is recorded internally as a `dsl_on_start_handoff` trace event (`executed`, `blocked`, `failed`, `call_failed`, `superseded_by_tool_hook`, `skipped_mode`) with a reason and identifiers only — never customer data. This event isn't one of Studio's labeled Traces Explorer cards (unlike, say, a mid-conversation "Agent Handoff" or "Handoff Check" card) — look for it through a session trace export or the debug API if you need to confirm why a start-time handoff did or didn't run. When the handoff doesn't run: a route `WHEN` simply not met shows nothing, not even `ON_FAILURE` text; a refused or failed handoff (a handoff guardrail, an unloaded target) shows only what the route's `ON_FAILURE` authors (`RESPOND` shows its text; `CONTINUE`, or no `ON_FAILURE`, shows nothing — never a generic failure message) — except `ESCALATE`, which escalates the session instead of keeping it with the entry agent; a target an `ENABLED_WHEN` switched off follows the normal authored-route rule (use `ON_FAILURE: CONTINUE` to keep the start silent).

After the start, the route behaves as an ordinary handoff — `RETURN`, `CONTEXT`, and `ON_RETURN` apply as usual — and the child never runs its own `ON_START` (which fires once per session, for the entry agent only). A route `WHEN` that reads start data stays true for the rest of the session, so a later turn can still route back to that agent after it returns. If the handoff should really happen only at start, put the condition on a branch `IF:` and leave the route's own `WHEN` unset, or clear the triggering value on return. Pairing with `ENABLED_WHEN` cleared on return (`ENABLED_WHEN: promo_open == true` with `ON_RETURN: set: promo_open = false`) also stops the model from choosing that agent on later turns.

> [!NOTE]
>
> Caller data asserted by the browser (public-key SDK init) is **not verified**. When a start-time routing decision matters, mint the caller data on your own server through the customer bootstrap endpoint rather than trusting a client-asserted value in a branch `IF:` or route `WHEN`.

## HOOKS

The `HOOKS:` block defines actions that run at four lifecycle points, plus `on_no_input_exhausted` when voice silence retries run out and `on_caller_hold_limit` when a caller hold reaches its limit. Unlike `ON_START`, hooks fire repeatedly throughout the session.

### Syntax

```yaml expandable=true theme={null}
HOOKS:
  before_agent:
    SET:
      agent_start_time = NOW()
    CALL: load_user_preferences()

  after_agent:
    CALL: save_session_summary()

  before_turn:
    SET:
      turn_start_time = NOW()

  after_turn:
    CALL: log_audit_event()
    SET:
      turn_count = ADD(turn_count, 1)
```

### Hook points

| Hook | When it fires |
| - | - |
| `before_agent` | Once when the agent is first activated (before it processes its first message). |
| `after_agent` | Once when the agent completes or is deactivated. |
| `before_turn` | Before each user message is processed. |
| `after_turn` | After each turn completes (after the agent's response is sent). |
| `on_no_input_exhausted` | When voice silence retries run out and `on_exhausted` is `hook`. See [on\_no\_input\_exhausted](#on_no_input_exhausted). |
| `on_caller_hold_limit` | When a caller hold reaches its limit and the limit action is `hook`. See [on\_caller\_hold\_limit](#on_caller_hold_limit). |

### on\_no\_input\_exhausted

On pipeline voice, `on_exhausted: hook` runs the agent's `on_no_input_exhausted` hook when silence retries run out. Use it to act on exhausted silence from an agent with no FLOW. It also works on a FLOW agent.

```yaml theme={null}
AGENT: Card_Support
GOAL: "Help the caller with a card"

CONVERSATION:
  listening:
    on_no_input:
      on_exhausted: hook
      exhausted_message: "I still couldn't hear you."

TOOLS:
  record_silence(reason: string) -> object
    description: "Record a silent call"

HANDOFF:
  - TO: Transfer_Desk
    CONTEXT:
      pass: [transfer_reason]
    RETURN: false

HOOKS:
  on_no_input_exhausted:
    CALL: record_silence
      WITH:
        reason: "caller_silent"
    SET: transfer_reason = "Caller went silent"
    HANDOFF: Transfer_Desk
```

* **Order:** the authored `exhausted_message`, then `CALL`, then `SET`, then `HANDOFF`.
* **Turn behavior:** the hook is the same route turn as a flow target, so it adds no caller row. Caller speech before the turn starts cancels it. Speech while it runs keeps the call open once it finishes, unless the hook handed off.
* **After the hook:** with a `HANDOFF`, the target starts on its own with no caller message. With no `HANDOFF`, the call ends.
* **Failed handoff:** a `HANDOFF` that fails follows its `ON_FAILURE`. When `ON_FAILURE` speaks or escalates, the call stays open and the next exhausted silence ends it. Otherwise the call ends. A transfer started by the hook's tool keeps the call.
* **Failed `CALL`:** it does not stop the actions after it, unless the hook sets `CRITICAL: true`.
* **What the hook can hold:** `CALL`, `SET`, `HANDOFF`, and `CRITICAL`. The runtime reads `HANDOFF` in this hook only, and ignores it elsewhere with a warning. Values set here reach the target through the entry's `CONTEXT.pass`.
* **No `RESPOND`:** the call can end straight after the hook, so the compiler refuses `RESPOND`, `WHEN` replies, and rich content here. Put the words in `exhausted_message`.
* **Slow tools:** the caller hears nothing while `CALL` runs, for up to the hook timeout of 10 seconds unless the tool sets its own.
* **The word `hook`:** it runs the hook when the agent has one. A step named `hook` on an agent with no such hook stays a step target. An agent with neither fails to compile.
* **Where to set it:** on a step or an agent, as for a flow target, and only in ABL. Studio keeps the value on save and has no form for the hook. A behavior profile takes action words only.
* **Other channels:** on realtime voice and Twilio, `hook` acts as `custom`. The hook does not run, and a `voice_no_input_route_unsupported` trace records it.
* **Compile errors:** [`NO_INPUT_TARGET_NO_HOOK`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#no_input_target_no_hook) for `hook` on an agent with no hook and no step of that name, [`NO_INPUT_HOOK_RESPOND_UNSUPPORTED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#no_input_hook_respond_unsupported) for a reply in the hook, and [`INVALID_HANDOFF_TARGET`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#invalid_handoff_target) for a `HANDOFF` to an agent with no `HANDOFF` entry.

### on\_caller\_hold\_limit

On a KoreVG voice call, the gateway can signal that the caller put the agent on hold. The project's caller hold setting limits how long a hold can last. When a hold reaches the limit and the limit action is `hook`, the Runtime runs the active agent's `on_caller_hold_limit` hook. This works on pipeline and realtime voice. The caller is still on hold, so the hook says nothing.

#### Turn caller hold on

Caller hold is a project setting. In Studio, go to **Settings → Runtime Config → Caller hold**. The API name is the `callerHold` section of the project runtime config. Project export and import carry it.

| Setting | Values | Default |
| - | - | - |
| Handle caller hold | On or off | On for a new project. Off for a project created before caller hold existed, or imported without the setting, until a project admin turns it on. |
| Maximum time on hold | The longest single hold, from 0:30 to 60:00 (minutes:seconds) | 10:00 |
| Maximum total hold time per call | All holds in the call added together, from 1:00 to 240:00. It must be at least the maximum time on hold. | 30:00 |
| When the limit is reached | **End the call**; **Transfer to the configured human target** (the SIP or phone number target from the project's Agent Transfer settings); or **Run the agent's on\_caller\_hold\_limit hook** | End the call |

While the caller is on hold, the agent stays silent and stops listening. When the caller comes back, the agent listens again. A reply that the hold interrupted is kept for the next turn when possible.

* **Transfer needs a target.** The chosen target must be set in Agent Transfer, as a valid SIP URI or an E.164 phone number. Studio refuses to save the setting without it.
* **Import.** If an imported project transfers on the limit but the target is missing or not valid, caller hold comes in turned off and the import warns `CALLER_HOLD_TRANSFER_TARGET_MISSING`. Add the target, then turn caller hold on. The Runtime looks for the target in the imported project settings first, when the export has them. Otherwise it uses the project's current Agent Transfer settings.
* **Scope.** The setting applies only to holds that the phone network signals on KoreVG voice calls, and only when the KoreVG gateway supports caller hold. Otherwise the call behaves as before. While caller hold is on, the trace of each such call records `voice_caller_hold_unsupported` when the call starts.

#### Write the hook

```yaml theme={null}
AGENT: Card_Support
GOAL: "Help the caller with a card"

TOOLS:
  record_abandoned_hold(hold_seconds: number) -> object
    description: "Note that the caller stayed on hold past the limit"

HANDOFF:
  - TO: Transfer_Desk
    CONTEXT:
      pass: [transfer_reason]
    RETURN: false

HOOKS:
  on_caller_hold_limit:
    CALL: record_abandoned_hold
      WITH:
        hold_seconds: session.callerHold.durationSeconds
    SET: transfer_reason = "Caller stayed on hold past the limit"
    HANDOFF: Transfer_Desk
```

* **What the hook can hold:** `CALL`, `SET`, `HANDOFF`, and `CRITICAL`, the same as `on_no_input_exhausted`. The Runtime reads `HANDOFF` only in these two hooks, and ignores it elsewhere with a warning. Values set here reach the target through the entry's `CONTEXT.pass`.
* **No `RESPOND`:** the caller is on hold and the call can end straight after the hook. The compiler refuses `RESPOND`, `WHEN` replies, and rich content with `CALLER_HOLD_HOOK_RESPOND_UNSUPPORTED`. A `HANDOFF` to an agent with no `HANDOFF` entry gives [`INVALID_HANDOFF_TARGET`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#invalid_handoff_target).
* **Order:** `CALL`, then `SET`, then `HANDOFF`. All of them run in the time the gateway allows before it hangs up. A failed `CALL` does not stop the actions after it, unless the hook sets `CRITICAL: true`.
* **After the hook:** with a `HANDOFF`, the target starts on its own with no caller message, and the call stays on hold. A transfer started by the hook's tool keeps the call. With no `HANDOFF`, or with a `HANDOFF` that fails, the call ends. An agent with no such hook also ends the call.
* **YAML:** the hook is `hooks.on_caller_hold_limit` with `call`, `call_spec`, `set`, `handoff` and `critical`.

#### Caller hold values

The Runtime sets `session.callerHold`. The values are read-only, and an agent declares nothing to read them. They exist only for the turn or hook shown, and are cleared after it.

| Value | First turn after the caller resumes | While `on_caller_hold_limit` runs |
| - | - | - |
| `session.callerHold.resumed` | `true` | -- |
| `session.callerHold.durationSeconds` | Length of the hold that just ended | Length of the current hold |
| `session.callerHold.cumulativeSeconds` | Total time on hold in this call | Total time on hold in this call |
| `session.callerHold.holdCount` | Number of holds in this call | -- |
| `session.callerHold.pendingReply` | `true` when a reply the caller had not heard is delivered on this turn | `true` when a reply is waiting for the caller |
| `session.callerHold.holdId` | -- | Identifier of the current hold |
| `session.callerHold.sequence` | -- | Event sequence number of the limit |
| `session.callerHold.direction` | -- | `inbound` or `outbound` |
| `session.callerHold.mode` | -- | `pipeline` or `realtime` |
| `session.callerHold.toolCallInProgress` | -- | `true` when a tool call was running at the limit |

To thank the caller for waiting, guard a `before_turn` reply with `pendingReply`. The line then does not replace or repeat a kept reply. This works on pipeline voice. A realtime speech-to-speech provider runs no per-turn hook.

```yaml theme={null}
HOOKS:
  before_turn:
    WHEN: session.callerHold.resumed == true AND session.callerHold.pendingReply == false
      RESPOND: "Thanks for waiting. Where were we?"
```

### Hook action properties

Each hook supports the same set of action properties:

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `SET` | `Record<string,string>` | No | -- | Variable assignments. |
| `CALL` | `string` | No | -- | Tool to call (supports `WITH:`/`AS:`). |
| `RESPOND` | `string` | No | -- | Message to send (uncommon in hooks, but supported). |
| `VOICE` | `object` | No | -- | Voice overrides, including `BARGE_IN` and `STREAMING`. See [Voice delivery for lifecycle replies](#voice-delivery-for-lifecycle-replies). |
| `RICH_CONTENT` | `object` | No | -- | Rich content format variants. |
| `ACTIONS` | `object` | No | -- | Interactive actions. |
| `SET_INTERACTION_LANGUAGE` | `string` | No | -- | Set the authoritative session interaction language — a literal BCP-47 tag (for example `es`, `es-ES`, `fr-CA`) or a dynamic value that resolves to one at runtime. Subsequent actions and turns use it. |
| `CLEAR_INTERACTION_LANGUAGE` | `boolean` | No | -- | Remove the interaction-language override, reverting to automatic detection. Takes no value. |
| `critical` | `boolean` | No | `false` | If `true`, a hook failure aborts the turn; otherwise the failure is logged and execution continues. |

A hook `RESPOND` renders like a step `RESPOND`, after `CALL` and `SET`. `{{variable}}` placeholders read session values, and a placeholder with no value renders empty, so a raw `{{...}}` never reaches the caller. A line that renders entirely empty sends no text. The hook's `RICH_CONTENT`, `VOICE`, `ACTIONS`, and `RENDERABLES` are still delivered.

`SET_INTERACTION_LANGUAGE` and `CLEAR_INTERACTION_LANGUAGE` are action-list actions — like `SET` and `CLEAR`, they can appear in any action list (`ON_START`, `HOOKS`, `ON_ACTION` handlers). Use them to pin the language the agent responds in — for example, after detecting a caller's preferred language or reading it from a profile.

The value is classified when the agent is compiled:

1. **Literal tag** — a value that canonicalizes as BCP-47 (`es`, `fr-CA`, …) is validated and fixed at compile time.
2. **Dynamic value** — anything else that looks like a session-variable path (`user.preferred_language`), a `{{template}}`, or a `${dotted.path}` expression is resolved at runtime, using the same value resolution as an ordinary `SET`.
3. Anything that is neither a valid literal tag nor a recognized dynamic form is a compile error.

```yaml theme={null}
HOOKS:
  before_turn:
    # Dynamic — resolved from session state each time the hook runs
    - SET_INTERACTION_LANGUAGE: "{{user.preferred_language}}"
    # Equivalent dotted-path and ${...} forms are also accepted:
    # - SET_INTERACTION_LANGUAGE: user.preferred_language
    # - SET_INTERACTION_LANGUAGE: "${user.preferred_language}"

ON_START:
  # Literal — validated once at compile time
  - SET_INTERACTION_LANGUAGE: "es-MX"
```

> [!NOTE]
>
> A dynamic value is resolved and re-validated at **runtime**: if it doesn't resolve to a canonical BCP-47 tag, or resolves to a language the voice channel isn't configured to support, the override is not applied and the session keeps its current language.

### WHEN / RESPOND branches

A hook can respond conditionally: a `WHEN: <condition>` with an indented `RESPOND: "<text>"` is a **respond branch**. Branches are checked in declaration order, after the hook's own `CALL` and `SET` run, and the first branch whose condition holds wins:

```yaml theme={null}
HOOKS:
  before_turn:
    WHEN: email_verified && !zip_supplied
      RESPOND: "Thanks. What is the ZIP code on the account?"
    WHEN: account_locked == true
      RESPOND: "This account is locked. I'll connect you with support."
```

* In a **reasoning agent's `before_turn` hook**, a matched branch's text becomes the turn's reply and the model is not called for that turn. Input guardrails and escalation triggers still run first and can still intervene.
* In **other hooks** (`before_agent`, `after_agent`, `after_turn`), a matched branch's text is sent as a message at that point in the lifecycle.
* A `WHEN` that can't be evaluated does not hold — evaluation falls through to the next branch (or to an unconditional `RESPOND`, if present).
* A branch can sit next to an unconditional `RESPOND:` in the same hook; the branches are the conditional alternative, evaluated independently.

> [!WARNING]
>
> A hook's `WHEN` must be valid CEL. An invalid `WHEN` (including old plain-English text left over from before this feature) is demoted to an unconditional `RESPOND` for backward compatibility, and the compiler warns [`HOOK_WHEN_BRANCH_INVALID_CEL`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_when_branch_invalid_cel). Fix the condition, or remove `WHEN:` if the response really is meant to run unconditionally.

### Conditional interaction-language actions (before\_turn)

A `before_turn` hook can switch the session's interaction language for the turn's reply, its filler, and (on KoreVG pipeline voice) the TTS voice, conditionally based on a `WHEN:` guard. A `WHEN:` whose indented body is `SET_INTERACTION_LANGUAGE:` or `CLEAR_INTERACTION_LANGUAGE` is a **language branch**. This is the same `WHEN:` mechanism as a [respond branch](#when--respond-branches), but with a language action instead of `RESPOND:`. A language directive written at hook level with no `WHEN:` is a catch-all.

```yaml theme={null}
HOOKS:
  before_turn:
    WHEN: session.languageDetection.status == "detected" AND session.languageDetection.confidence >= 0.85
      SET_INTERACTION_LANGUAGE: session.languageDetection.language
    WHEN: session.languageDetection.language == "en"
      CLEAR_INTERACTION_LANGUAGE
    WHEN: session.languageDetection.status == "low_confidence" AND session.languageDetection.textLength >= 12
      RESPOND: "Shall we continue in {{session.languageDetection.candidate}}?"
    SET_INTERACTION_LANGUAGE: "hi-IN"
```

**Rules:**

* A value that is a BCP 47 tag (quoted or not) is a compile-time literal, canonicalized (`"es-mx"` becomes `es-MX`). A value path or `{{template}}` is resolved at runtime, like a hook `SET` value; a result that is not a language the channel supports is refused (with a trace) and the language stays as it was. Any other value is a compile error ([`E394`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#e394) in `.abl`, [`E396`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#e396) in YAML).
* `CLEAR_INTERACTION_LANGUAGE` takes no value ([`E395`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#e395)). A trailing colon is fine.
* One `WHEN:` body holds exactly one action: a `RESPOND:` (a reply branch) or one language action. Both in one body, or two language actions, drop the whole branch with [`HOOK_WHEN_BODY_MULTIPLE_ACTIONS`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_when_body_multiple_actions). Write two separate `WHEN:` branches instead.
* Language branches are tried in order. The first whose `WHEN:` holds wins, so the catch-all (no `WHEN:`) belongs last. One placed earlier warns with [`HOOK_LANGUAGE_CATCH_ALL_NOT_LAST`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_catch_all_not_last).
* This grammar is **`before_turn` only**. The same directives under a `WHEN:` in any other hook are a compile error ([`HOOK_LANGUAGE_ACTION_NOT_BEFORE_TURN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_action_not_before_turn) from the parser; [`HOOK_LANGUAGE_ACTION_UNSUPPORTED_HOOK`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_action_unsupported_hook) if a language action reaches compilation attached to a different hook by another path).
* A `WHEN:` that is not valid CEL drops that action with the compiler warning [`HOOK_LANGUAGE_WHEN_INVALID_CEL`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_when_invalid_cel). Unlike a respond branch, it never becomes unconditional.
* YAML form: the hook carries `interaction_language_actions`, a list of entries with an optional `when` and exactly one of `set_interaction_language`, `set_interaction_language_expression`, or `clear_interaction_language: true`. Anything else is [`HOOK_LANGUAGE_ENTRY_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_entry_invalid).

**Timing.** The runtime evaluates language actions in an early pass, before the filler and before the model call, against the session as it stood at the start of the turn (including `session.languageDetection`). The hook's own `CALL` and `SET` run later in the turn, so a language guard never sees values the hook itself just set. It sees what the previous turn left. The chosen language becomes the session's interaction language and holds until another action changes or clears it.

**Gating.** Language actions take effect only when the project's language-detection setting is on (a project-level Studio setting, not declared in ABL), on chat and on pipeline voice. On a call with per-language voice profiles, the filler and the reply switch to the new language's voice in the same turn when that language has a TTS profile. For a language with no TTS profile, or for `CLEAR_INTERACTION_LANGUAGE`, the filler keeps the previous language and voice and the reply follows the new language. Omitting the project setting while authoring this grammar produces a compiler reminder ([`HOOK_LANGUAGE_ACTIONS_REQUIRE_SETTING`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_language_actions_require_setting)). Realtime speech-to-speech sessions never run them: their language is fixed by the provider session.

#### session.languageDetection shape

The `session.languageDetection` object holds the latest detection result.

| Field | Type | Description |
| - | - | - |
| `status` | `string` | One of `detected`, `low_confidence`, `no_language`, `failed`, `unavailable`, `skipped`. |
| `language` | `string` | BCP 47 tag. Present only when `status` is `detected`. |
| `confidence` | `number` | 0 to 1. |
| `candidate` | `string` | The best guess. Present when `status` is `low_confidence`. |
| `ranked` | `array` | The detection service's languages, best first, at most five. Each entry has `language`, `confidence` and `script`. Filled when `status` is `detected` or `low_confidence`. Empty otherwise. |
| `script` | `string` | The detected script. |
| `textLength` | `number` | Characters sent for detection, after redaction. |
| `reason` | `string \| null` | Why the status is what it is, or `null`. |

The project's language-detection setting can configure an allowed-languages list and a minimum message length (default 12 characters). A message in a language outside the allowed list comes back `no_language` with `reason: "not_allowed"`, so an unsupported language is never offered as `candidate`. A message shorter than the minimum comes back `low_confidence` with `reason: "too_short"` and its guess as `candidate`, whatever the confidence: a single short word like "Ciao" can still score 1.0. Scripts used by only one supported language (Korean, Japanese, Thai, Greek, Hebrew, and most Indic scripts) are exempt from the minimum-length rule. The session's current interaction language is sent as a hint to the detection service, improving accuracy on short or romanized input.

`ranked` lets a guard read the score of a runner-up language even when another language leads. For example: `session.languageDetection.ranked[1].language == "en"`. A language outside the allowed-languages list never appears in `ranked`.

**Confidence floor.** A confidence below 0.5 is never `detected`, because the confidence threshold in the setting cannot go below 0.5. The detection service deliberately answers some turns at 0.49, so they stay below that floor:

* a number with one widely shared word or a currency word, such as `11,000 pesos`;
* a turn made only of known names;
* a short turn of common words, such as `ok` or `agent`, when the session has no language yet.

The label of such a guess can change between service releases. A guard that switches on a `low_confidence` `candidate` must also require enough text and a high enough confidence. If it does not, the caller can see a language switch on a turn that carries no language.

**Language hint.** The hint is the session's authored interaction language, for example one set by `SET_INTERACTION_LANGUAGE`. A session with no authored language sends no hint. A project cannot switch the hint off. On a short message (four words or fewer), the hint gives that language a small bonus when the message already holds evidence for it. It breaks close calls. It does not override clear evidence for another language. Frequent English words do not count as evidence for a non-English hint, so a caller who switches back to English is detected as English.

#### Recipe: avoid language flapping

Short or code-mixed turns (Hinglish, for example) can flip between two detected languages turn to turn. Applying every `detected` result makes the reply, filler, and voice change each turn. Switch only on two consecutive matching detections of useful length. The hook `SET` records this turn's detection for the next turn's guard:

```yaml theme={null}
HOOKS:
  before_turn:
    WHEN: session.languageDetection.status == "detected" AND session.languageDetection.confidence >= 0.85 AND session.languageDetection.textLength >= 12 AND session.languageDetection.language == last_detected_language
      SET_INTERACTION_LANGUAGE: session.languageDetection.language
    WHEN: session.languageDetection.status == "low_confidence" AND session.languageDetection.textLength >= 12
      RESPOND: "Shall we continue in {{session.languageDetection.candidate}}?"
    SET:
      last_detected_language: "{{session.languageDetection.language}}"
```

#### Recipe: FLOW agent with language switching

A FLOW agent takes the same `before_turn` actions. They run before the turn's step. A model-written reply (a `REASONING: true` step) and fillers follow the chosen language. A fixed `RESPOND:` in a `REASONING: false` step is delivered as written and is never auto-translated. Localize it with `{{locale.KEY}}` from the project's locale files: the language setters refresh the locale catalog in the same turn, so the step renders the text for the new language.

In this example the English branch comes first (the first matching `WHEN:` wins), so a confident English message clears back to the default language while any other confident detection switches:

```yaml expandable=true theme={null}
HOOKS:
  before_turn:
    WHEN: session.languageDetection.status == "detected" AND session.languageDetection.confidence >= 0.85 AND session.languageDetection.language == "en"
      CLEAR_INTERACTION_LANGUAGE
    WHEN: session.languageDetection.status == "detected" AND session.languageDetection.confidence >= 0.85 AND session.languageDetection.textLength >= 12
      SET_INTERACTION_LANGUAGE: session.languageDetection.language

FLOW:
  ask_order:
    REASONING: false
    RESPOND: "{{locale.ASK_ORDER_NUMBER}}"
    THEN: answer

  answer:
    REASONING: true
    GOAL: "Tell the customer the status of their order in one or two sentences."
```

### Voice delivery for lifecycle replies

On KoreVG pipeline voice, a lifecycle reply can carry a nested `VOICE` block with `BARGE_IN` and `STREAMING` under its `RESPOND`.

```yaml expandable=true theme={null}
AGENT: Hook_Voice
GOAL: "Greet and route callers"
HOOKS:
  before_turn:
    WHEN: needs_zip == true
      RESPOND: "Before we continue, what is your zip code?"
        VOICE:
          BARGE_IN: allow
  after_turn:
    RESPOND: "Anything else I can help with?"
      VOICE:
        BARGE_IN: allow
        STREAMING: true
```

* **Legal homes.** An `ON_START` reply and its branches, a hook `RESPOND`, a hook `WHEN` reply branch, an `ON_ERROR` handler, and a tool's `on_result.do` or `on_error.do` reply.
* **When it applies.** The reply applies its own policy before its first audio. The previous policy returns afterwards. A reply that sets no keys runs under the FLOW step or turn default.
* **Agent types.** Reasoning and FLOW agents both honor a hook reply's `VOICE`. Realtime speech-to-speech is unchanged.
* **Never spoken.** An `after_agent` `RESPOND` goes to the transcript only, so its `VOICE` keys have no audible effect.
* **Block-form reply.** After `RESPOND: |` in a `WHEN:` branch, a nested line reads as reply text. Put `VOICE` level with `RESPOND` instead.
* **Ignored placement.** A `VOICE` block beside a one-line `RESPOND`, or in a hook branch with no `RESPOND`, warns with [`HOOK_VOICE_NOT_UNDER_RESPOND`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#hook_voice_not_under_respond) and is ignored.
* **Free-standing blocks.** A free-standing `ON_START` or branch `VOICE` block rejects `BARGE_IN` with [`VOICE_BARGE_IN_ILLEGAL_PLACEMENT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_barge_in_illegal_placement). Nest the block under the `RESPOND`.
* **Runtime support.** A hook `WHEN` branch's `VOICE` block is published with the IR marker `voice_output_policy`. A runtime without the marker refuses the agent.

Values and precedence are in [Scoped barge-in](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#scoped-barge-in).

### Example: audit logging hook

```yaml theme={null}
HOOKS:
  after_turn:
    CALL: log_wire_audit_event()
```

### Example: turn timing

```yaml theme={null}
HOOKS:
  before_turn:
    SET:
      turn_start_time = NOW()
  after_turn:
    SET:
      turn_duration_ms = SUB(NOW_MS(), turn_start_time_ms)
```

## ON\_ERROR handlers

The `ON_ERROR:` block defines how the agent responds to specific error types. Each handler matches an error type and specifies a response, optional retry logic, and a follow-up action.

### Syntax

```yaml expandable=true theme={null}
ON_ERROR:
  tool_error:
    RESPOND: "That system is responding slowly. Let me retry."
    SUBTYPE: tool_timeout
    RETRY: 2
    THEN: CONTINUE

  validation_error:
    RESPOND: "That value doesn't look right. Could you double-check?"
    THEN: CONTINUE

  llm_error:
    RESPOND: "I'm having trouble processing your request."
    RETRY: 1
    RETRY_BACKOFF: exponential
    RETRY_MAX_DELAY: 10000
    THEN: ESCALATE
```

### Error types

The error `type` (the handler's key) is matched against a **fixed, canonical set** — a handler whose
key is not one of these 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)) because it can
never match at runtime:

| Error type | When it occurs |
| - | - |
| `default` | Fallback handler used when no other type matches. |
| `llm_error` | The LLM call fails or errors. |
| `tool_error` | A tool call fails. Narrow it with `SUBTYPE`/`SUBTYPES` — known subtypes include `rate_limit`, `auth_failure`, `network_error`, and `tool_timeout`. |
| `routing_error` | Handoff/delegation/routing resolution fails. |
| `validation_error` | Gathered/extracted data fails validation. |
| `timeout_error` | A non-tool operation (for example the overall turn) times out. |
| `unknown_error` | An unexpected error occurred. |

> [!WARNING]
>
> Three names from older examples are **not** valid handler types and are silently rewritten as warnings, never matched at runtime: `tool_timeout` (use `tool_error` with `SUBTYPE: tool_timeout`), `invalid_input` (use `validation_error`), and `api_error` (use `tool_error` with an appropriate `SUBTYPE`, for example `network_error`).

Use `SUBTYPE` (single value) or `SUBTYPES` (array) to match more finely within a type — both keys are case-insensitive but conventionally written uppercase.

#### Inline shorthand

For a handler that only takes a terminal action, use the single-line form `error_name: ACTION`:

```yaml theme={null}
ON_ERROR:
  unknown_error: ESCALATE
  tool_error: HANDOFF Live_Agent
```

### Error handler properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `RESPOND` | `string` | No | -- | Message sent to the user when this error occurs. |
| `VOICE` | `object` | No | -- | Voice-specific overrides for the response. |
| `RICH_CONTENT` | `object` | No | -- | Rich content format variants. |
| `ACTIONS` | `object` | No | -- | Interactive actions. |
| `SET` | `Record<string,string>` | No | -- | Variable assignments applied when this error is handled. |
| `RETRY` | `number` | No | -- | Number of retry attempts before executing `THEN`. |
| `RETRY_DELAY` | `number` | No | -- | Delay in milliseconds between retries. |
| `RETRY_BACKOFF` | `string` | No | -- | Backoff strategy for retries. See [Retry strategies](#retry-strategies). |
| `RETRY_MAX_DELAY` | `number` | No | -- | Maximum delay between retries in milliseconds. |
| `THEN` | `string` | No | -- | Action after retries are exhausted. See [Then actions](#then-actions). |
| `HANDOFF_TARGET` | `string` | No | -- | Explicit target agent for `THEN: HANDOFF` (alternative to `HANDOFF <agent>`). |
| `BACKTRACK_TO` | `string` | No | -- | Target step for `backtrack` action. |
| `SUBTYPE` / `SUBTYPES` | `string` / `string[]` | No | -- | Error subtype(s) for fine-grained matching within `tool_error` (for example `SUBTYPE: tool_timeout` or `SUBTYPES: [rate_limit, network_error]`). |

### Retry strategies

| Strategy | Behavior |
| - | - |
| `fixed` | Wait the same `RETRY_DELAY` between each attempt. |
| `exponential` | Double the delay after each attempt, up to `RETRY_MAX_DELAY`. |
| `linear` | Increase the delay by `RETRY_DELAY` after each attempt, up to `RETRY_MAX_DELAY`. |

### Then actions

| Action | Behavior |
| - | - |
| `CONTINUE` | Continue the conversation, skipping the failed operation. In a reasoning step the handler's line is the reply, and an unmet `EXIT_WHEN` keeps the step. |
| `ESCALATE` | Trigger human escalation. On a FLOW step `CALL`, the step takes the flow's `ESCALATE` terminal after the handler's retries, so authored `ESCALATE` routing applies. |
| `HANDOFF` | Transfer to a specified agent (for example. `HANDOFF Live_Agent`, or via `HANDOFF_TARGET`). |
| `COMPLETE` | End the conversation. In a reasoning step the handler's line leads the completion. |
| `RETRY_STEP` | Re-run the current flow step from the beginning. After a reasoning step's model failure, the next message re-runs the step. |
| `BACKTRACK` | Go to the flow step named by `BACKTRACK_TO` (required). In a reasoning step that step answers in the same turn. |

### Step-level error handlers

Error handlers can be overridden at the step level within a flow. A matching step-level handler replaces the agent-level handler for that step, including its `RESPOND`. Write them as `- TYPE:` items or keyed by type, like agent-level handlers. Both forms compile to the same handlers.

```yaml theme={null}
FLOW:
  steps:
    execute_payment:
      CALL: process_payment
      ON_ERROR:
        - TYPE: tool_error
          RESPOND: "Payment processing failed. Retrying..."
          RETRY: 3
          RETRY_BACKOFF: exponential
          THEN: HANDOFF Payment_Support
```

#### Step-level error handler properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `TYPE` | `string` | Yes | -- | Error type to match. |
| `SUBTYPE` | `string` | No | -- | One error subtype to match. |
| `SUBTYPES` | `string[]` | No | -- | Error subtypes for fine-grained matching. |
| `RESPOND` | `string` | No | -- | Message to the user (one line). |
| `SET` | `string` | No | -- | `name = expression`. Repeatable. |
| `RETRY` | `number` | No | -- | Retry count. |
| `RETRY_DELAY` | `number` | No | -- | Delay between retries (ms). |
| `RETRY_BACKOFF` | `string` | No | -- | Backoff strategy. |
| `RETRY_MAX_DELAY` | `number` | No | -- | Maximum retry delay (ms). |
| `THEN` | `string` | No | -- | Action after retries are exhausted. |
| `HANDOFF_TARGET` | `string` | No | -- | Explicit target agent for `THEN: HANDOFF`. |
| `BACKTRACK_TO` | `string` | No | -- | Target step for backtrack. |

## Error handler resolution order

1. **Step-level handlers** are checked first: a subtype match, then a type match, then a `DEFAULT` entry.
2. **Agent-level handlers** (`ON_ERROR:` block) are checked the same way if no step-level handler matches.
3. **The agent's default handler** applies if neither matches. When no handler matches a model error, a declared `unknown_error` handler is used.
4. A `CONTINUE` or `RETRY_STEP` handler without `RESPOND` sends the platform fallback line for the error (`error_llm_<subtype>`, else `error_default`). `MESSAGES:` or the project's locale files can replace it. A `BACKTRACK` to another step, or a `COMPLETE`, without `RESPOND` sends none.

Inside a `REASONING: true` step, an error from a tool the model calls, and a `validation_error` after `MAX_RETRIES`, use the agent-level handlers only. For every action, its `EXIT_WHEN` behavior, and the fallback lines, see [Flow: when a reasoning step's model call fails](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#when-a-reasoning-steps-model-call-fails).

***

## MESSAGES

The top-level `MESSAGES:` block overrides the default system messages the runtime uses for errors,
constraint violations, gathering, handoffs, escalation, completion, and voice/telephony prompts. Any
key you don't set keeps its built-in default, and the templates support `{{}}` interpolation.

```yaml theme={null}
MESSAGES:
  error_default: "Sorry, something went wrong. Please try again or type HELP."
  constraint_blocked: "I'm not able to help with that request."
  gather_prompt: "I need a few details: {{fields}}"
  escalation_format: "Connecting you to a specialist. Reason: {{reason}}"
  conversation_complete: "Thanks for chatting!"
```

### Common message keys

| Key | Default (abridged) | Used when… |
| - | - | - |
| `error_default` | "An error occurred. Please try again." | An error occurs and no `ON_ERROR` handler matches. |
| `constraint_blocked` | "I cannot proceed with that request." | A `CONSTRAINT` blocks the turn. |
| `gather_prompt` | "Please provide: {{fields}}" | Prompting for outstanding gather fields. |
| `escalation_format` | "Escalating to human agent. Reason: {{reason}}" | Formatting an escalation notice. |
| `conversation_complete` | "This conversation has been completed." | A conversation reaches `COMPLETE`. |
| `invalid_handoff` | "Unable to transfer to the requested agent." | A `HANDOFF` target can't be resolved. |
| `self_handoff` | "Cannot hand off to self." | An agent hands off to itself. |
| `tool_fallback_desc` | "Execute the requested operation." | A tool has no `description`. |
| `gather_correction_applied` | "Got it, I've updated the {{fields}}." | A `CORRECTIONS: true` GATHER accepts a changed value. See [CORRECTIONS](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#corrections). |
| `gather_correction_dependents_cleared` | "I may need to ask you again about the {{cleared_fields}}." | A correction cleared dependent fields that the step asks for again. |
| `tool_confirmation_request` | "Please confirm before I go ahead{{action_suffix}}.{{details}} Shall I proceed?" | A tool needs the customer's approval. Supports `{{action_suffix}}` and `{{details}}`. See [Confirmation](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#what-the-customer-is-asked). |

\[!NOTE] On the **Genesys Bot Connector** specifically, setting `escalation_format: ""` (an explicit empty string, not omitting the key) suppresses the whole reply — text, buttons, and citations — on a *successful* terminal escalation; the configured escalation intent is still sent, so the customer's session still escalates, it just gets no message. Omitting the key keeps the normal message behavior, and any nonempty value behaves as before. This only changes what the Bot Connector sends outward — it doesn't affect the internal execution transcript, ongoing (non-terminal) replies, an unsuccessful escalation, or any other channel.
\| `tool_confirmation_duplicate_effect` | "I already completed this earlier in our conversation{{action_suffix}}. Would you like me to do it again?" | A tool that already ran is about to run again. Supports `{{action_suffix}}`. |

> [!NOTE]
>
> `MESSAGES:` accepts **any** message key, not only the ones above — including error-subtype
> messages (`error_tool_timeout`, `error_llm_error`, `error_validation`, …), multi-intent UX prompts
> (`multi_intent_disambiguate_header`, `multi_intent_queued_notice`, …), handoff/routing messages
> (`handoff_message`, `handoff_message_voice`, `routing_message`), voice prompts (`voice_repeat`,
> `voice_nomatch`, `voice_noinput`, …), and the `greeting` / `out_of_scope` messages. Set only the
> keys you want to override.

### Filler overrides (voice)

On a voice channel, the runtime speaks a short filler phrase (for example "One moment.") to avoid dead air while a tool call, reasoning step, handoff, delegation, extraction, or constraint check runs. `MESSAGES:` lets you override these with deterministic, author-controlled text using `filler_<operation>` keys:

```yaml theme={null}
MESSAGES:
  filler_general: "One moment, please."
  filler_tool_call: "Let me look that up for you."
  filler_reasoning: "Let me think about that."
  filler_handoff: "Connecting you now."
  filler_delegation: "Checking with a specialist."
  filler_extraction: "Let me pull those details."
  filler_constraint_check: "Verifying that for you."
  filler_tool_call_fr: "Je vérifie cela pour vous."
  filler_tool_call_fr-CA: "Un instant, je regarde ça pour vous."
```

| Key | Spoken while… |
| - | - |
| `filler_general` | No more specific operation filler applies (the fallback). |
| `filler_tool_call` | A tool call is in flight. |
| `filler_reasoning` | A reasoning step is running. |
| `filler_handoff` | A `HANDOFF` is in progress. |
| `filler_delegation` | A `DELEGATE` is in progress. |
| `filler_extraction` | The agent is extracting/gathering structured data. |
| `filler_constraint_check` | A `CONSTRAINT` is being evaluated. |

Add a `_<language>` suffix to supply a localized variant — either a bare BCP-47 primary subtag (`filler_tool_call_fr`) or a full region tag (`filler_tool_call_fr-CA`). At runtime the first match wins, checking the region tag before the bare subtag, and the operation-specific key before the general fallback:

`filler_<operation>_<region-tag>` → `filler_<operation>_<language>` → `filler_<operation>` → `filler_general_<region-tag>` → `filler_general_<language>` → `filler_general` → the platform's built-in localized fallback.

> [!NOTE]
>
> A key with a region tag (`filler_tool_call_fr-CA`) contains a hyphen — write it unquoted as a plain `key: value` line; both the `.agent.abl` and `.agent.yaml` formats parse the hyphen correctly.

> [!WARNING]
>
> Filler overrides are **static, deterministic text** — unlike other `MESSAGES:` keys, they do **not** support `{{}}` interpolation. User input is never substituted into a filler, by design.

***

**Related articles:**

* [Memory and constraints](https://koreai.mintlify.site/agent-platform/abl/reference/memory-and-constraints.md) -- variables initialized in ON\_START and hooks
* [Multi-agent and supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md) -- ESCALATE and HANDOFF used in THEN actions
* [Rich content](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md) -- voice and rich content in handler responses


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