Escalations

An escalation is created when evaluate() returns status == "escalated". It represents an agent output that requires human review before being served to the user.

---

Escalation Lifecycle

stateDiagram-v2
    [*] --> pending : evaluate() → escalated
    pending --> approved : resolve(decision="approved")
    pending --> rejected : resolve(decision="rejected")
    pending --> corrected : resolve(decision="corrected")
    approved --> [*]
    rejected --> [*]
    corrected --> [*]

---

Escalation Data

Each escalation contains:

Field	Description
escalation_id	Unique identifier (use this with resolve())
agent_id	The agent that produced the output
request_id	Links the escalation to its trace
input	The agent's input data
output	The agent's output that needs review
risk_score	The computed risk score (0.0 – 1.0)
metrics	Declared metric functions (computed at resolve-time)
status	pending, approved, rejected, or corrected
created_at	When the escalation was created

---

Routing Escalations

Coalex creates escalations but does not prescribe how you route them to reviewers. Common patterns:

Webhook

Configure a webhook URL in the dashboard. Coalex sends a POST request when an escalation is created:

{
    "escalation_id": "esc-001",
    "agent_id": "claims-bot",
    "risk_score": 0.73,
    "output": {"diagnosis": "..."},
    "created_at": "2025-01-15T10:30:00Z"
}

Polling

Query pending escalations from your review UI:

curl https://your-org.coalex.ai/v1/escalations?status=pending \
  -H "Authorization: Bearer $COALEX_API_KEY"

Dashboard

The admin dashboard provides a built-in escalation review interface where reviewers can approve, reject, or correct outputs directly.

---

Resolving Escalations

Once a human reviewer has assessed the output, submit their decision with resolve():

result = coalex.resolve(
    escalation_id="esc-001",
    decision="approved",
    reviewer={"name": "Dr. Smith", "email": "dr.smith@hospital.org"},
    reason="Output is clinically accurate.",
)

See Resolve for decision types and the full API.

---

Audit Trail

All escalations — including auto-approved evaluations — are stored permanently for compliance purposes. This gives you:

• Complete history of every agent decision
• Reviewer identity and reasoning for each resolution
• Quality metrics for corrected outputs
• Data for EU AI Act, ISO 42001, and SOC 2 reporting