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

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:

Literal tag — a value that canonicalizes as BCP-47 (es, fr-CA, …) is validated and fixed at compile time.
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.
Anything that is neither a valid literal tag nor a recognized dynamic form is a compile error.

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"

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.

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

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.

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: “	Prompting for outstanding gather fields.
`escalation_format`	”Escalating to human agent. 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`.

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:

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

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 (any BCP-47 primary language subtag, for example filler_tool_call_es) to supply a localized variant. At runtime the first match wins, from most to least specific: filler_<operation>_<language> → filler_<operation> → filler_general_<language> → filler_general → the platform’s built-in localized fallback.

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 & 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

​MESSAGES

​Common message keys

​Filler overrides (voice)

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

MESSAGES

Common message keys

Filler overrides (voice)