> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Escalation to human agent from an agent

Use `ESCALATE` when an agent cannot safely or confidently continue execution and requires human intervention. Escalation transfers the conversation to a human operator or handling system, ensuring continuity while preventing incorrect or risky automated responses.

Unlike agent-to-agent routing (`HANDOFF` / `DELEGATE`), escalation is specifically designed for human involvement and should not be modeled as a handoff to a human agent.

## When to use escalation

Typical scenarios include:

* User frustration
* Customer complaints
* Policy validation requirements
* System failures
* Repeated routing failures
* High-risk or high-value operations

## How escalation works

1. Agent evaluates escalation triggers.
2. When a trigger condition is met:
   * A new task is created in the Inbox for a human agent to review and proceed.
   * Agent execution is suspended.
   * A transfer payload is constructed from:
     * `context_for_human`
     * `routing.metadata`
     * any provider-specific routing fields.
3. The payload is sent to the configured human agent provider.
4. A human agent reviews and completes the task.
5. After the human interaction completes, the configured `on_human_complete` actions determine whether the workflow resumes, hands off to another agent, or completes.

Configure Escalation using the following fields.

* **Triggers**: Each trigger defines a condition under which the flow escalates to a human, along with metadata used to prioritize and route the escalation.
* **Context for Human**: Lets the flow designer specify which context variables are passed to the human agent when a conversation is escalated.
* **On Human Complete**: Defines handler actions the agent should take after a human agent resolves the escalated issue (for example, resuming the flow, updating variables).
* **Routing**: Routing controls where an escalated conversation is delivered and how it is presented once it reaches a human agent desktop.
  * **Voice Settings**: Voice Settings govern how the active call leg is handed off when the escalation routes over a voice channel. It is only relevant for voice interactions.

    | **Field** | **Description** |
    | - | - |
    | **Move the Call Leg** | Determines how the call is handed to the agent desktop. **Relay to agent desk** keeps the caller on the current leg and proxies the call to the agent desktop. **SIP** or **PSTN** moves the call itself while keeping the destination project-configured. The **Transfer Method** and **SIP Headers** settings apply only when **SIP** or **PSTN** is selected. |
    | **Transfer Method** | Specifies the call transfer mechanism used when the call leg is moved using **SIP** or **PSTN**. |
    | **SIP Headers** | Defines custom SIP headers to attach to transferred or relayed calls. Headers can be added one at a time using the **+ Add Header** option. |

## DSL configuration

```yaml expandable=true theme={null}
ESCALATE:
  triggers:
    - WHEN: intent = transfer to customer support
      REASON: "requested"
      PRIORITY: medium
  context_for_human:
    - customer_id
    - summary
  routing:
    connection: "152f48d0-290e-4293-87e9-d8d9138ad58d"
    routing:
      queue: queue_name
      skills:
        - skill1
        - skill2
      priority: 1
      metadata:
        sentiment_score: "{{sentiment_score}}"
        attempt_count: "{{retry_count}}"
        customer_tier: "{{customer.tier}}"

  on_human_complete:
    - IF human.resolved == true: COMPLETE
```

## Trigger properties

| Property | Type | Required | Description |
| - | - | - | - |
| WHEN | string | Yes | Condition that triggers escalation. |
| REASON | string | Yes | Human-readable reason for the escalation. |
| PRIORITY | string | Yes | Priority level: low, medium, high, or critical. |
| TAGS | string\[] | No | Tags for routing and categorization in the human agent queue. |

## Priority levels

| Level | Use case |
| - | - |
| low | Non-urgent requests (for example. general feedback). |
| medium | Standard requests (for example. user requests human assistance). |
| high | Urgent issues (for example. repeated failures, outages). |
| critical | Immediate attention required (for example. compliance violations, fraud). |

## Context for human

The `context_for_human` block defines what data is sent to the human agent. This ensures the human agent has full context without asking the user to repeat information.

```yaml theme={null}
context_for_human:
  - customer_id
  - customer_name
  - amount
  - conversation_history
```

### Structured context

```yaml theme={null}
context_for_human:
  - NAME: case_summary
    TEMPLATE: "Customer {{customer_name}} requesting wire of {{amount}} {{currency}}"
    INCLUDE: [fraud_score, sanctions_match_score]
```

## Routing configuration

Controls how escalation is routed to the human system.

| Property | Type | Required | Description |
| - | - | - | - |
| id | string | No | Optional label for authoring/observability. Defaults to `entry_<index>` if omitted. |
| when | string | No | Used for conditional routing. [Learn More](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#conditional-routing-entries). |
| queue | string | No | Target queue in the human agent system. You can use expressions to define dynamic values for the queues. |
| skills | string\[] | No | Required skills for the human agent. |
| priority | number | No | Numeric routing priority for the queue entry. |
| metadata | object | No | Key value pairs for passing metadata to the receiving agent. |
| voice | - | No | Optional block controlling how the voice call is handed off at the SIP/transport layer when escalating on a voice channel |
| voice.transfer\_method | - | No | SIP signaling method used to transfer the call: `invite`, `refer`, or `bye`. |
| voice.call\_transfer\_type | - | No | Whether to move the call over `sip` or `pstn`. Omit to infer from project configuration. The target is always project-owned — this selects a transport, not a destination. |
| voice.sip\_headers | - | No | Key-value map of custom SIP headers to forward on the transfer to the receiving SBC or contact center. |

> [!NOTE]
>
> * Use `context_for_human` for passing existing session variables to agents.
> * Use `routing.metadata` for additional information like computed values, routing hints, summaries, that improves the human agent's context or routing abilities.
> * During agent transfer, `ESCALATE.routing.metadata` is passed to the external agents as sip headers in case of voice interactions and as session level tags in chat.

### Metadata propagation

During an escalation, metadata is propagated differently depending on the channel:

* **Voice channels(SIP)**: Metadata configured in the ESCALATE block is automatically converted into SIP headers and sent to the receiving voice platform during the transfer. You can also use routing.voice.sip\_headers to define additional custom SIP headers or override the header mapping when needed.
* **Digital channels**: Metadata is forwarded to the receiving desktop or contact-center platform as key-value pairs through the provider's handoff API or WebSocket connection. The exact format depends on the integration and the capabilities of the receiving platform.

## Post-completion behavior

Defines what happens after the human agent completes the task.

```yaml theme={null}
on_human_complete:
  - IF human.resolved == true: COMPLETE
  - IF human.needs_agent == true: HANDOFF to specified_agent
  - IF human.needs_followup == true: CONTINUE
```

| Action | Behavior |
| - | - |
| COMPLETE | End the workflow |
| HANDOFF | Transfer back to an agent |
| CONTINUE | Resume the current agent |

## Examples

### Escalation from supervisor

```yaml expandable=true theme={null}
SUPERVISOR: Customer_Service_Hub
VERSION: "2.0"
GOAL: "Route customers to the right specialist"

PERSONA: |
  Professional customer service coordinator. Routes requests
  efficiently and preserves context across agent transfers.

ESCALATE:
  triggers:
    - WHEN: routing_failures >= 3
      REASON: "Multiple routing failures"
      PRIORITY: high

    - WHEN: user.wants_human_agent == true
      REASON: "Customer requesting human specialist"
      PRIORITY: medium

  context_for_human:
    - user_id
    - conversation_summary
    - routing_failures
    - conversation_history

  routing:
    queue: "customer_support_l2"
    skills: [support, escalation]
    priority: 1

  on_human_complete:
    - IF human.resolved == true: COMPLETE
    - IF human.needs_agent == true: HANDOFF to Support_Agent
```

### Escalation via ON\_ERROR

`THEN: ESCALATE` triggers the escalation flow after retry attempts are exhausted.

```yaml expandable=true theme={null}
ON_ERROR:
  tool_error:
    RESPOND: "I encountered an issue. Let me connect you with a specialist."
    RETRY: 1
    THEN: ESCALATE

  routing_failure:
    RESPOND: "I am having trouble routing your request."
    RETRY: 1
    THEN: HANDOFF Live_Agent_Transfer
```

## Escalation vs handoff

| Aspect | ESCALATE | HANDOFF |
| - | - | - |
| Target | Human operator | Another agent |
| Visibility | User interacts with human | User interacts with agent |
| Use case | Failure / escalation scenarios | Multi-agent routing |
| Control flow | Suspends agent execution | Transfers execution |

## Troubleshooting

| Issue | Resolution |
| - | - |
| Escalation never triggers | Verify the `WHEN` condition references variables that are actually set during the conversation. Test with explicit values. |
| Human agent lacks context | Include `conversation_history` in `context_for_human`. List all relevant session variables-IDs, collected data and current state. |
| Conversation stalls after human completes | Define `on_human_complete` handlers for all possible human outcomes (`resolved`, `needs_agent`, `needs_followup`). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.