Back to Recipes

AI Escalation Queue

Build a human-in-the-loop escalation system so AI agents hand off complex tasks to people when they get stuck.

Best for: Teams deploying AI agents that need human oversight

What You Get

  • -Escalation task queue database
  • -Priority and routing logic
  • -Agent-to-human handoff API
  • -Dashboard for human reviewers
  • -Resolution tracking

Step by Step

1. Create the escalation database

Create PostgreSQL table: escalations (id uuid, source_agent text, issue_description text, priority text, context_data jsonb, status text, assigned_to uuid, created_at timestamptz, assigned_at timestamptz, resolved_at timestamptz, resolution_notes text, webhook_url text). Add indexes on status, priority, created_at.

2. Build the escalation API

Create REST endpoints: POST /api/escalations (create from agent), GET /api/escalations (list with filters), PATCH /api/escalations/:id/claim, PATCH /api/escalations/:id/resolve. All endpoints validate agent identity via API key.

3. Implement auto-assignment

On creation, auto-assign based on round-robin from active reviewers pool. For urgent priorities, also send Slack/email notification. Update status to 'assigned' and set assigned_at timestamp.

4. Build the real-time dashboard

Create a Next.js dashboard with: escalation list (sortable by priority, status, age), color-coded priority badges (red for urgent, yellow for high, blue for medium, gray for low), claim/resolve buttons, and WebSocket updates for new escalations.

5. Add resolution webhooks

When an escalation is resolved, POST the resolution (notes, resolution, timestamp) to the source agent's webhook_url. Include the original context_data for reference. Log delivery success/failure.

6. Build metrics and monitoring

Track: average time to first assignment, average resolution time by priority, escalation rate per agent, top 10 escalation reasons (parsed from issue_description via OpenAI categorization). Display on a metrics dashboard.

7. Add priority timeout escalation

Implement a cron job that checks for stale escalations: urgent >1 hour without assignment = notify on-call, high >4 hours = bump priority flag, medium >24 hours = notify manager. Update task appearance on dashboard.

Stack

PostgreSQLNext.jsOpenAIWebSocket for real-time updates

Build This

Copy this prompt and paste it into Claude Code, OpenCode, Codex, or Cursor to build this recipe.

Build me an AI escalation queue system. It should: 1) Provide an API for AI agents to create escalation tasks with fields: source_agent, issue_description, priority (low/medium/high/urgent), context_data (JSON blob), status (open/assigned/resolved). 2) Auto-assign tasks to human reviewers round-robin or by expertise tag. 3) Show a real-time dashboard where humans can view, claim, and resolve tasks. 4) When a human resolves a task, send the resolution back to the AI agent via webhook. 5) Track metrics: average resolution time, escalation rate per agent, common escalation reasons. 6) Include a priority matrix: urgent+high turns red after 1 hour, medium after 4 hours, low after 24 hours. 7) Add notification (email/Slack) for new urgent escalations.

Common Failure Modes

  • !No human available to handle escalations
  • !Escalation loop (agent re-escalates same issue)
  • !Context too large to pass in escalation
  • !Prioritization is ignored

Implementation Notes

Keep escalation context concise but complete. Set up on-call rotation for urgent escalations. Log every status change with timestamp.

Want ai escalation queue running in your business?

4M Labs can deploy ai escalation queue as a production workflow:

  • Connected to your tools and data sources
  • Secured for your team with proper access controls
  • Deployed with monitoring and error handling
  • Documented for handoff and future maintenance
Book an Implementation Sprint