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.
`DELEGATE`	`string`	No	—	Agent to delegate to during initialization.
`RESPOND`	`string`	No	—	Greeting or welcome message sent to the user.
`VOICE`	`object`	No	—	Voice-specific overrides for the response. See Rich Content.
`RICH_CONTENT`	`object`	No	—	Rich content format variants. See Rich Content.
`ACTIONS`	`object`	No	—	Interactive actions attached to the response.

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.

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

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

Error type	When it occurs
`tool_timeout`	A tool call exceeds its timeout.
`tool_error`	A tool call returns an error.
`validation_error`	User input fails validation.
`llm_error`	The LLM call fails (rate limit, model error, etc.).
`routing_failure`	The Supervisor cannot route a message.
`agent_unavailable`	A target agent for handoff or delegate is unavailable.
`timeout`	A general timeout (session idle, async operation).

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.
`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.
`BACKTRACK_TO`	`string`	No	—	Target step for `backtrack` action.
`subtypes`	`string[]`	No	—	Error subtypes for fine-grained matching (e.g., `[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 (e.g., `HANDOFF Live_Agent`).
`COMPLETE`	End the conversation.
`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.
`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

Documentation Index

​Overview

​ON_START handler

​Syntax

​ON_START properties

​Template references in ON_START

​ON_START with tool call

​HOOKS

​Syntax

​Hook points

​Hook action properties

​Example: audit logging hook

​Example: turn timing

​ON_ERROR handlers

​Syntax

​Error types

​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

HOOKS

Syntax

Hook points

Hook action properties

Example: audit logging hook

Example: turn timing

ON_ERROR handlers

Syntax

Error types

Error handler properties

Retry strategies

Then actions

Step-level error handlers

Step-level error handler properties

Error handler resolution order

Related pages