Escalations

How agents escalate issues to humans or other agents when they need help.

The Escalate Tool

Every agent has a built-in escalate tool that lets it hand off issues when it can't resolve them independently.

The escalate tool is injected into every agent automatically — it's not served by any MCP server. When an agent calls it, the platform creates an escalation record and optionally routes the issue to another agent.

Agent calls escalate

{
  "tool": "escalate",
  "arguments": {
    "severity": "high",
    "reason": "Customer is reporting unauthorized charges. Need human review of transaction history.",
    "to_agent_id": "account-ops"
  }
}

Field	Type	Description
severity*	string	One of: critical, high, medium, low
reason*	string	Why the agent is escalating
to_agent_id	string	Target agent for handoff. If omitted, escalates to human operators.
context	object	Additional context to pass along with the escalation

Auto-Escalation Policies

You can configure policies that automatically escalate when an agent hits consecutive failures.

Policy configuration

{
  "agent_id": "invoice-parser",
  "name": "Consecutive failure escalation",
  "condition_type": "consecutive_failures",
  "threshold": 3,
  "severity": "high",
  "target_agent_id": "ops-triage",
  "enabled": true
}

When the invoice-parser agent fails 3 times in a row, the platform automatically creates a high-severity escalation and routes it to the ops-triage agent.

Auto-escalation policies are evaluated at the daemon workflow level. Each signal processed by the daemon tracks consecutive failures — a successful signal resets the counter.

Escalation Lifecycle

pending ─→ acknowledged ─→ resolved

pending ─→ dismissed

Field	Type	Description
pending	initial	Escalation created, awaiting human or agent attention
acknowledged	in-progress	A human has seen the escalation and is working on it
resolved	terminal	Issue has been resolved
dismissed	terminal	Escalation was not actionable or was a false positive

Agent-to-Agent Handoff

When an escalation targets another agent, the platform signals that agent's daemon workflow with the escalation context.

The receiving agent gets a prompt containing the escalation reason, severity, and any additional context. It can then use its own tools to investigate and resolve the issue. This creates a chain of responsibility across specialized agents.

Design your agents with clear boundaries. Each agent should handle a specific domain and know when to escalate to a more specialized agent or to human operators.