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 human agent reviews and completes the task.
After completion:
- The system executes configured post-completion actions.
- The workflow may resume, transfer, or end.

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: condition
      REASON: "reason for escalation"
      PRIORITY: medium
      TAGS: [tag1, tag2]

  context_for_human:
    - variable1
    - variable2

  routing:
    queue: "queue_name"
    skills: [skill1, skill2]
    priority: 1

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

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

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

​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

Post-completion behavior

Examples

Escalation from supervisor

Escalation via ON_ERROR

Escalation vs handoff

Troubleshooting