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

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.

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:

ON_START:
  CALL: find_member_by_ani
    WITH:
      callerAni: ani_national
    WHEN: ani_national != ""

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

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.

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

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:

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>	Hands off through the normal handoff lifecycle — the target’s declared WHEN, RETURN, CONTEXT, EXPERIENCE_MODE, ON_RETURN, and ON_FAILURE all apply as usual. 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:

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:

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

DELEGATE and any other action in an ON_START list is dropped with a warning (W380-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). The start-time handoff is local only: a route WHEN that only a model could judge (natural language, intent.*) is never satisfied at start, and a remote (A2A) target is always refused.

Diagnostic	Severity	Catches
ON_START_HANDOFF_ACTIVATED / 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	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	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 start type:

• Eager start (no customer message yet — Web SDK/web-debug connect, pipeline voice answer, an identified agent-assist welcome): the welcome is delivered, then the child starts on its own with no synthetic customer message and speaks its own opener. Order: entry agent’s before_agent output, the welcome, the handoff announcement (if the experience mode speaks one), the child’s before_agent output, the child’s own first output. A RETURN: true child stays active after that unanswered opener; ordinary return rules apply from the customer’s first real message on.
• Lazy start (the first customer 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 in the dsl_on_start_handoff trace (executed, blocked, failed, call_failed, superseded_by_tool_hook, skipped_mode) with a reason and identifiers only — never customer data. 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.

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

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.

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.

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:

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.

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. Fix the condition, or remove WHEN: if the response really is meant to run unconditionally.

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

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:

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_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.
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.
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.
SUBTYPE	string	No	—	Error subtype for fine-grained matching (step-level handlers accept only the singular form).
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).

---

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.
tool_confirmation_request	”Please confirm before I go ahead. Shall I proceed?”	A tool needs the customer’s approval. Supports {{action_suffix}} and {{details}}. See Confirmation.
tool_confirmation_duplicate_effect	”I already completed this earlier in our conversation. Would you like me to do it again?”	A tool that already ran is about to run again. Supports {{action_suffix}}.

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

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.

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 — voice and rich content in handler responses