Escalations

An escalation is your agent saying your team is needed. There are five kinds:

Kind	Raised when	Resolved when
`approval`	A step or run in a real conversation needs an approval only your team can give (the procedure’s approval is `by: "team"`, or the agent doesn’t let people in the chat approve)	It’s decided, anywhere: the conversation, the console or the API
`question`	A task asks something only your team can answer	It’s answered
`handoff`	The agent hands a request to your team from a chat (its `escalate` tool): the person asked for a person or another team, or its instructions say the request goes to someone else. It holds who the agent says should take it (`owner`) and everything it knew (`details`). The chat doesn’t wait on it	You mark it handled (`dismiss`)
`procedure_failed`	A run that followed a procedure failed	The procedure gets a new revision (`fixed`), is deleted, or you dismiss it
`procedure_change`	A run that followed a procedure got the right result another way. The escalation holds the procedure rewritten to what worked (`proposal`)	You accept the proposal (it becomes the next revision), the procedure gets another revision, or you reject it

What isn’t an escalation:

An approval or question whoever is chatting can answer stays in the chat.
Test chats never escalate: your team’s own chats in the console, the widget preview and Coach. A test chat’s run shows how it went against its procedure on the task instead, with Review in Coach.
Evals raise procedure escalations quietly: they’re in the list as “from an eval”, with no email, webhook or chat message.

The procedure check

After every run that followed a procedure, a model reads the procedure (at the revision the run was given) and what the run did, and says whether it followed the steps, did it another way that worked, or failed. Nothing about the procedure changes until someone accepts a proposal or saves a new revision. A run of a revision that’s since been changed isn’t checked. The check is AI Review on the pricing page: it runs on the cheapest model of the agent’s own provider and is paid by its tokens at that model’s price, like a chat reply, rounded up to the next cent (a cent or two a run). A conversation’s price shows it as AI Review. It doesn’t run when your balance is empty, and you can turn it off for an agent (below). Repeats add up: there’s one open escalation per procedure and kind, with count and the latest 20 runs in tasks.

{
  "object": "escalation",
  "id": "esc_8b1f0c2d4e6a7b9c1d",
  "agent_id": "support",
  "kind": "procedure_change",
  "status": "open",
  "source": "live",
  "summary": "Used the warranty API instead of the page: one load instead of five clicks.",
  "count": 3,
  "procedure": { "id": "prc_8fK2mQ0aLp4x", "title": "Find the warranty end date from a serial number", "revision": 3 },
  "failed_at": "2",
  "proposal": { "base_revision": 3, "body": "1. Open https://api.example.com/warranty/{serial}.\n2. Read end_date.\nCheck: the serial matches." },
  "owner": null,
  "details": null,
  "tasks": ["task_Hq2x", "task_Pz9m", "task_Ab3c"],
  "conversation_id": null,
  "request_id": null,
  "created_at": "2026-10-20T15:03:36.037Z",
  "last_seen_at": "2026-10-20T17:41:02.511Z",
  "resolved_at": null,
  "resolution": null,
  "resolved_by": null,
  "resolved_revision": null
}

Escalation rules

Each agent decides what escalates, in its escalations setting (the console: the agent’s Escalations tab). Every key is on by default:

Key	Off means
`qa`	Its procedure runs aren’t checked, so nothing is charged for them and no `procedure_failed` or `procedure_change` is raised. Test chats show no check either.
`approval`, `question`	Approvals and questions only your team can take still wait in their conversation, where you can decide them, but aren’t escalated: no list entry, email or webhook.
`handoff`	The agent isn’t offered `escalate`, so it can’t hand requests to your team from a chat.
`procedure_failed`, `procedure_change`	Runs are still checked (and charged) while `qa` is on, and the verdict is kept on the run, but that kind isn’t raised.

curl -X PATCH https://guidinghand.ai/v1/agents/support -H "Authorization: Bearer $EAGER_API_KEY" \
  -H "Content-Type: application/json" -d '{"escalations": {"qa": false}}'

Like every setting, they’re part of the agent’s versions: a draft’s rules apply once it’s published. A task follows the rules of the version it ran.

In the console

Escalations lists them, with the number open on its tab. Open one to:

decide an approval or answer a question right there, in its conversation;
Fix in Coach (or Edit in Coach for a proposal): the agent’s Coach opens in a new chat that already knows what went wrong, the procedure as it is now and which runs to read, and proposes the fix;
Accept, Reject or Dismiss, or Mark handled for a hand-off.

A procedure with an open escalation is marked in the agent’s Procedures tab.

Being told

Email, right away, to the org’s owners and admins: a hand-off, and an approval or question only your team can decide that’s still open a minute after it was raised.
A daily digest of procedure escalations raised or grown since the last one. None when nothing’s new.
Webhooks: escalation.created, escalation.updated (a repeat, or a new proposal) and escalation.resolved, with escalation. See Webhooks.
Teams or Slack: each new one posted as a thread in the channel you chose, with a button to resolve it and Coach a reply away. See Teams and Slack.

In the API

curl https://guidinghand.ai/v1/escalations?status=open -H "Authorization: Bearer $EAGER_API_KEY"
curl -X POST https://guidinghand.ai/v1/escalations/esc_8b1f0c2d4e6a7b9c1d/accept -H "Authorization: Bearer $EAGER_API_KEY"

GET /v1/escalations filters by status, agent_id, kind and q, and its answer has open_count. POST /v1/escalations/{id}/dismiss, /accept and /reject resolve procedure escalations, and dismiss marks a hand-off handled (admins); approvals and questions are decided in their conversation. Accepting a proposal answers 409 if the procedure changed since it was proposed. To open Coach with one, send escalation_id with the first message to POST /v1/agents/{agent_id}/coach.

Get started

Build an agent

Guides

Tasks and sessions

Your org

SDKs

The procedure check

Escalation rules

In the console

Being told

In the API

​The procedure check

​Escalation rules

​In the console

​Being told

​In the API

The procedure check

Escalation rules

In the console

Being told

In the API