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

Agent evaluates escalation triggers.
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.
The payload is sent to the configured human agent provider.
A human agent reviews and completes the task.
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 (e.g., 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

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.

context_for_human:
  - customer_id
  - customer_name
  - amount
  - conversation_history

Structured context

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
queue	string	No	Target queue in the human agent system.
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.

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.

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.

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

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.

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

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Escalation to human agent from an agent

When to use escalation

How escalation works

DSL configuration

Trigger properties

Priority levels

Context for human

Structured context

Routing configuration

Metadata propagation

Post-completion behavior

Examples

Escalation from supervisor

Escalation via ON_ERROR

Escalation vs handoff

Troubleshooting

​When to use escalation

​How escalation works

​DSL configuration

​Trigger properties

​Priority levels

​Context for human

​Structured context

​Routing configuration

​Metadata propagation

​Post-completion behavior

​Examples

​Escalation from supervisor

​Escalation via ON_ERROR

​Escalation vs handoff

​Troubleshooting

When to use escalation

How escalation works

DSL configuration

Trigger properties

Priority levels

Context for human

Structured context

Routing configuration

Metadata propagation

Post-completion behavior

Examples

Escalation from supervisor

Escalation via ON_ERROR

Escalation vs handoff

Troubleshooting