Lifecycle and Hooks - Kore.ai Docs

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

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.
`RICH_CONTENT`	`object`	No	—	Rich content format variants (the `.agent.abl` keyword is `FORMATS:`). See Rich Content.
`ACTIONS`	`object`	No	—	Interactive actions attached to the response.
`BRANCHES`	`object[]`	No	—	Conditional greeting branches (`IF`/`ELSE`). See Conditional greeting.

Template references in ON_START

You can reference named templates in the RESPOND value:

ON_START:
  RESPOND: TEMPLATE(welcome)

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

ON_START with tool call

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.

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

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

HOOKS:
  after_turn:
    CALL: log_wire_audit_event()

Example: turn timing

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

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:

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_MAX_DELAY`	`number`	No	—	Maximum delay between retries in milliseconds.
`THEN`	`string`	No	—	Action after retries are exhausted. See 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.

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

Step-level handlers are checked first, matching on error type and optional subtypes.
Agent-level handlers (ON_ERROR: block) are checked if no step-level handler matches.
If no handler matches, the runtime uses the default error message from the MESSAGES: block (error_default).

Memory & Constraints — variables initialized in ON_START and hooks
Multi-Agent & Supervisor — ESCALATE and HANDOFF used in THEN actions
Rich Content & Expressions — voice and rich content in handler responses

​Overview

​ON_START handler

​Syntax

​ON_START properties

​Template references in ON_START

​ON_START with tool call

​Conditional greeting

​HOOKS

​Syntax

​Hook points

​Hook action properties

​Example: audit logging hook

​Example: turn timing

​ON_ERROR handlers

​Syntax

​Error types

​Inline shorthand

​Error handler properties

​Retry strategies

​Then actions

​Step-level error handlers

​Step-level error handler properties

​Error handler resolution order

​Related pages

Overview

ON_START handler

Syntax

ON_START properties

Template references in ON_START

ON_START with tool call

Conditional greeting

HOOKS

Syntax

Hook points

Hook action properties

Example: audit logging hook

Example: turn timing

ON_ERROR handlers

Syntax

Error types

Inline shorthand

Error handler properties

Retry strategies

Then actions

Step-level error handlers

Step-level error handler properties

Error handler resolution order

Related pages