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

​
DSL Configuration

ESCALATE:
  triggers:
    - WHEN: condition
      REASON: "reason for escalation"
      PRIORITY: medium
      TAGS: [tag1, tag2]

  context_for_human:
    - variable1
    - variable2

  routing:
    queue: "queue_name"
    skill_tags: [skill1, skill2]
    priority_boost: 1

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

​
Trigger Properties

PropertyTypeRequiredDescription
WHENstringYesCondition that triggers escalation.
REASONstringYesHuman-readable reason for the escalation.
PRIORITYstringYesPriority level: low, medium, high, or critical.
TAGSstring[]NoTags for routing and categorization in the human agent queue.

​
Priority Levels

LevelUse case
lowNon-urgent requests (e.g., general feedback).
mediumStandard requests (e.g., user requests human assistance).
highUrgent issues (e.g., repeated failures, outages).
criticalImmediate attention required (e.g., 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.
PropertyTypeRequiredDescription
queuestringNoTarget queue in the human agent system.
skill_tagsstring[]NoRequired skills for the human agent.
priority_boostnumberNoAdditional priority applied to the task.

​
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
ActionBehavior
COMPLETEEnd the workflow
HANDOFFTransfer back to an agent
CONTINUEResume 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"
    skill_tags: [support, escalation]
    priority_boost: 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

AspectESCALATEHANDOFF
TargetHuman operatorAnother agent
VisibilityUser interacts with humanUser interacts with agent
Use caseFailure / escalation scenariosMulti-agent routing
Control flowSuspends agent executionTransfers execution

​
Troubleshooting

IssueResolution
Escalation never triggersVerify the WHEN condition references variables that are actually set during the conversation. Test with explicit values.
Human agent lacks contextInclude conversation_history in context_for_human. List all relevant session variables-IDs, collected data and current state.
Conversation stalls after human completesDefine on_human_complete handlers for all possible human outcomes (resolved, needs_agent, needs_followup).