> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

1. **The channel** — The agent must be configured with one of the supported channels:
   * Genesys Bot Connector
   * Genesys Audio Connector
   * Phone with SIP
2. **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.
3. **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](https://developer.watson-orchestrate.ibm.com/tools/flows/transfer_end_node.md#configuring-a-transfer-end-node) before importing the escalation flow. For information about building the escalation workflow, see [Transfer End node](https://developer.watson-orchestrate.ibm.com/tools/flows/transfer_end_node.md).

## Import order

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

```bash theme={null}
./import-all.sh
```

## The `escalation` block

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

```yaml YAML theme={null}
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

**escalation** `object`

Configures live-agent escalation for the agent.

**properties**

**enabled** `boolean` *required*

Turns escalation on or off. Defaults to `false`.

**escalation\_tool** `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.

**conditions** `list[object]` *required*

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

**properties**

**name** `string` *required*

A human-readable label for the condition.

**escalation\_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.

**condition\_id** `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 (`-`).

**escalation\_prompt\_override** `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](#customizing-the-escalation-prompt).

**status** `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 BASH theme={null}
orchestrate agents escalation-prompt --name <agent-name>
```

**command flags**

**--name / -n** `string` *required*

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

**--default** `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:

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

```yaml YAML theme={null}
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:

```bash theme={null}
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 YAML theme={null}
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
```

## Related resources

* [Transfer End node](https://developer.watson-orchestrate.ibm.com/tools/flows/transfer_end_node.md) — how to build the escalation workflow
* [Authoring native agents](https://developer.watson-orchestrate.ibm.com/agents/build_agent.md)
* [Providing access to context variables](https://developer.watson-orchestrate.ibm.com/agents/build_agent.md#providing-access-to-context-variables)