Live-agent escalation

Configure a native agent to hand off the conversation to a live agent when one of its escalation conditions is met. The agent calls a designated escalation workflow, which determines the transfer channel and the messages shown to the customer. This feature is currently supported for Phone channels (Genesys Audio Connector and SIP) and the textual channel Genesys Bot Connector.

How it works

Live-agent escalation is a three-part pattern:

The channel — The agent must be configured with one of the supported channels:
- Genesys Bot Connector
- Genesys Audio Connector
- Phone with SIP
The agent is configured with an escalation block that declares the conditions under which a transfer is required, for example the customer explicitly asking for a human, or the agent detecting frustration.
The escalation workflow is a flow marked as a customer care escalation workflow. It verifies the channel, shows the appropriate message to the customer, and triggers the handoff via a Transfer End node.

When a condition is met, the agent invokes the escalation workflow and passes the condition_id and the current channel_type as input. The workflow then drives the transfer. Configure the Transfer End node before importing the escalation flow. For information about building the escalation workflow, see Transfer End node.

Import order

Import the escalation workflow before the agent, because the agent references the workflow by name.

./import-all.sh

The `escalation` block

Add an escalation block to the agent YAML to enable escalation:

YAML

escalation:
  enabled: true
  escalation_tool: customer_care_escalation_flow
  conditions:
    - name: Human requested
      escalation_condition: The customer explicitly asks to talk to a human or a live agent.
      condition_id: human_request
    - name: Customer frustrated
      escalation_condition: The agent detects that the customer is frustrated.
      condition_id: frustration

Field reference

object

Configures live-agent escalation for the agent.

Hide properties

boolean

required

Turns escalation on or off. Defaults to false.

string

required

Name of the escalation workflow — a flow marked with is_customercare_escalation=True. If this workflow is not already listed in the agent’s tools, it is added automatically on import.

list[object]

required

One or more conditions that trigger escalation. Each entry has the following fields:

Hide properties

string

required

A human-readable label for the condition.

string

required

A natural-language description of when this condition applies. The agent evaluates this description against the conversation to decide whether to escalate.

string

required

A machine-readable identifier passed to the escalation workflow as input. Must be unique across all conditions and use only letters, digits, underscores (_), and hyphens (-).

string

A prompt that replaces the escalation prompt that watsonx Orchestrate composes from conditions. The agent uses the text exactly as you write it. To return to the composed prompt, remove this field and import the agent again. For more information, see Customizing the escalation prompt.

string

Read-only. The server reports the state of the escalation configuration. The ADK ignores this field when you import an agent. Possible values:

disabled: Escalation is turned off.
ready: Escalation is turned on and the escalation workflow is available.
tool_missing: Escalation is turned on, but the escalation workflow can’t be found.
not_configured: Escalation is turned on, but no escalation workflow is set.

Customizing the escalation prompt

When escalation is turned on, watsonx Orchestrate adds an escalation prompt to the agent. By default, it composes the prompt from the escalation_condition descriptions in your conditions. To see the prompt that an agent uses, run:

BASH

orchestrate agents escalation-prompt --name <agent-name>

Show command flags

string

required

The name of the native agent. Escalation is supported only for native agents.

boolean

Show the prompt that is composed from the escalation conditions, even when escalation_prompt_override is set.

Without --default, the command shows the effective prompt and states whether it comes from an override or is composed from the conditions. The command prints the prompt as plain text so that you can copy it unchanged. To customize the prompt:

Run orchestrate agents escalation-prompt --name <agent-name> --default and copy the prompt.
Edit the text and paste it into the escalation_prompt_override field of the agent YAML.
Import the agent again.

YAML

escalation:
  enabled: true
  escalation_tool: customer_care_escalation_flow
  escalation_prompt_override: |
    <your edited escalation prompt>
  conditions:
    - name: Human requested
      escalation_condition: The customer explicitly asks to talk to a human or a live agent.
      condition_id: human_request

If the prompt isn’t available for the agent, the command logs a warning that includes the reason.

Side effects of enabling escalation

Enabling escalation automatically applies the following changes to the agent:

context_access_enabled is set to true.
channel is added to context_variables.

This means the agent’s instructions can reference {channel.channel_type} to adapt behaviour based on the current channel.

Supported agent styles

Escalation is supported only for the following agent styles: default, react, react_intrinsic, and react_core. Importing an agent with escalation enabled on any other style returns an error.

Visibility of escalation workflows

Escalation workflows are hidden from the standard tools list. To include them in the listing, pass the --include-escalation flag:

orchestrate tools list --include-escalation

YAML as source of truth

The agent YAML is the authoritative source for escalation configuration. Re-importing a YAML file that does not contain an escalation block removes escalation from the agent, including any escalation configuration that was applied through the UI.

Complete agent example

YAML

spec_version: v1
kind: native
name: customer_care_agent
llm: groq/openai/gpt-oss-120b
style: react_core
description: |
  A customer care agent that handles support requests and can transfer
  users to a live agent when needed.
instructions: |
  Help the customer with their support request.
  You can reference the current channel as {channel.channel_type}.
tools:
  - some_support_tool
escalation:
  enabled: true
  escalation_tool: customer_care_escalation_flow
  conditions:
    - name: Human requested
      escalation_condition: The customer explicitly asks to talk to a human or a live agent.
      condition_id: human_request
    - name: Customer frustrated
      escalation_condition: The agent detects that the customer is frustrated.
      condition_id: frustration

Transfer End node — how to build the escalation workflow
Authoring native agents
Providing access to context variables

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

How it works

Import order

The `escalation` block

Field reference

Customizing the escalation prompt

Side effects of enabling escalation

Supported agent styles

Visibility of escalation workflows

YAML as source of truth

Complete agent example

​How it works

​Import order

​The escalation block

​Field reference

​Customizing the escalation prompt

​Side effects of enabling escalation

​Supported agent styles

​Visibility of escalation workflows

​YAML as source of truth

​Complete agent example

​Related resources

How it works

Import order

The `escalation` block

Field reference

Customizing the escalation prompt

Side effects of enabling escalation

Supported agent styles

Visibility of escalation workflows

YAML as source of truth

Complete agent example

Related resources