> ## 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-specific overrides for the response. See [Rich Content](/agent-platform/abl-reference/rich-content-and-expressions).                             |
| `RICH_CONTENT` | `object`                | No       | --      | Rich content format variants (the `.agent.abl` keyword is `FORMATS:`). See [Rich Content](/agent-platform/abl-reference/rich-content-and-expressions). |
| `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.

### 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?"
```

## HOOKS

The `HOOKS:` block defines actions that run at four lifecycle points. Unlike `ON_START`, hooks fire repeatedly throughout the session.

### Syntax

```yaml 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).                 |

### 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-specific overrides.                                                                           |
| `RICH_CONTENT` | `object`                | No       | --      | Rich content format variants.                                                                       |
| `ACTIONS`      | `object`                | No       | --      | Interactive actions.                                                                                |
| `critical`     | `boolean`               | No       | `false` | If `true`, a hook failure aborts the turn; otherwise the failure is logged and execution continues. |

### 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 theme={null}
ON_ERROR:
  tool_timeout:
    RESPOND: "That system is responding slowly. Let me retry."
    RETRY: 2
    THEN: CONTINUE

  tool_error:
    RESPOND: "I hit an error accessing that service. Let me try again."
    RETRY: 1
    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 a **free-form label matched by name** — it is not validated
against a fixed enum. A handler fires only when the runtime raises an error of that exact type.
Commonly used types include:

| Error type         | When it occurs                            |
| ------------------ | ----------------------------------------- |
| `tool_timeout`     | A tool call exceeds its timeout.          |
| `tool_error`       | A tool call returns an error.             |
| `invalid_input`    | User input cannot be parsed.              |
| `validation_error` | Gathered/extracted data fails validation. |
| `api_error`        | An external API call fails.               |
| `unknown_error`    | An unexpected error occurred.             |

Use `subtypes` (or the `SUBTYPE:` singular alias) to match more finely within a type.

#### 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
  api_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.                                                  |
| `subtypes`        | `string[]`              | No       | --      | Error subtypes for fine-grained matching (for example. `[rate_limit, model_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.                                   |
| `ESCALATE`   | Trigger human escalation.                                                                   |
| `HANDOFF`    | Transfer to a specified agent (for example. `HANDOFF Live_Agent`, or via `HANDOFF_TARGET`). |
| `COMPLETE`   | End the conversation.                                                                       |
| `RETRY_STEP` | Re-run the current flow step from the beginning.                                            |
| `BACKTRACK`  | Return to a previous step specified by `BACKTRACK_TO`.                                      |

### Step-level error handlers

Error handlers can be overridden at the step level within a flow. Step-level handlers take precedence over agent-level handlers for the same error type.

```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.                       |
| `subtypes`        | `string[]` | No       | --      | Error subtypes for fine-grained matching.  |
| `RESPOND`         | `string`   | No       | --      | Message to the user.                       |
| `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, matching on error type and optional subtypes.
2. **Agent-level handlers** (`ON_ERROR:` block) are checked if no step-level handler matches.
3. If no handler matches, the runtime uses the default error message from the `MESSAGES:` block (`error_default`).

## Related pages

* [Memory & Constraints](/agent-platform/abl-reference/memory-and-constraints) -- variables initialized in ON\_START and hooks
* [Multi-Agent & Supervisor](/agent-platform/abl-reference/multi-agent-and-supervisor) -- ESCALATE and HANDOFF used in THEN actions
* [Rich Content & Expressions](/agent-platform/abl-reference/rich-content-and-expressions) -- voice and rich content in handler responses