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 an AI escalation queue system that routes issues from AI agents to human reviewers with priority management. ROLE: You are an escalation management system that receives issues from AI agents, assigns them to human reviewers based on priority and expertise, tracks resolution progress, and notifies stakeholders of urgent escalations. CONSTRAINTS: - Escalation tasks must include: source_agent, issue_description, priority (low/medium/high/urgent), context_data (JSON), status (open/assigned/resolved) - Auto-assignment: round-robin within expertise tag; if no expertise match, assign to on-call reviewer - Priority matrix: urgent+high turns red after 1 hour, medium after 4 hours, low after 24 hours - Maximum 20 open escalations per reviewer; overflow routes to backup reviewers - All escalations must be retained for 6 months for audit and analytics TOOL CALLING: - Use function calling for: create_escalation(source_agent, issue_description, priority, context_data), assign_task(task_id, reviewer_id?), resolve_task(task_id, resolution, root_cause?), get_escalation_stats(date_range?, agent_filter?), notify_urgent(task_id, channels[]) - Each tool returns structured JSON with escalation data and action metadata STRUCTURED OUTPUT: - Escalation task must return JSON: { task_id: string, source_agent: string, issue_description: string, priority: 'low' | 'medium' | 'high' | 'urgent', context_data: Record<string, any>, status: 'open' | 'assigned' | 'resolved', assigned_to?: string, created_at: string, resolved_at?: string, resolution?: string, root_cause?: string } - Assignment must return JSON: { task_id: string, reviewer_id: string, reviewer_name: string, expertise_match: boolean, queue_position: number, estimated_wait_minutes: number } - Escalation stats must return JSON: { total_escalations: number, avg_resolution_time_minutes: number, by_priority: Record<string, number>, by_agent: Record<string, number>, by_root_cause: Record<string, number>, open_tasks: number, overdue_tasks: number } CHAIN OF THOUGHT: - Receipt: validate escalation data → check for duplicates → assign priority → create task record - Assignment: check reviewer availability → match expertise tags → apply round-robin → assign or queue - Monitoring: track elapsed time against priority thresholds → trigger alerts → escalate overdue tasks - Resolution: capture resolution details → categorize root cause → send webhook to source agent → update metrics FEW-SHOT EXAMPLES: Escalation: { source_agent: 'crm-agent', issue_description: 'Cannot parse email address from contact form', priority: 'medium', context_data: { form_id: 'contact_123', raw_input: 'invalid-email' } } Assignment: { task_id: 'esc_456', reviewer_id: 'reviewer_2', reviewer_name: 'Jane Smith', expertise_match: true, queue_position: 1, estimated_wait_minutes: 15 } Resolution: { task_id: 'esc_456', resolution: 'Added regex validation for email format in contact parser', root_cause: 'missing_input_validation', resolved_in_minutes: 45 } Stats: { total_escalations: 127, avg_resolution_time_minutes: 62, by_priority: { urgent: 12, high: 34, medium: 56, low: 25 }, overdue_tasks: 3 } EVALUATION CRITERIA: - Assignment accuracy: percentage of escalations assigned to reviewers with matching expertise - Resolution timeliness: percentage of escalations resolved within priority thresholds - Root cause categorization: percentage of resolutions with meaningful root cause labels - Webhook reliability: percentage of source agents that receive resolution notifications The system should: 1) Provide an API for AI agents to create escalation tasks with fields: source_agent, issue_description, priority, context_data, status, 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.

Ship ai escalation queue in production with 4M Labs

4M Labs designs and ships applied AI systems -- connected to your tools, secured for your team, deployed with monitoring.

  • 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
Work With 4M Labs

Built by 4M Labs

This recipe is maintained by the 4M Labs engineering team. We build production AI systems for companies in Mexico and the US.

See our case studies →Hire our team →Book a call →

Frequently Asked Questions

Can I use this recipe in production?
Yes. Every recipe is production-tested with error handling, logging, and deployment guidance.
Which LLM providers are supported?
Recipes support OpenAI, Anthropic Claude, Google Gemini, and open-source models via a unified interface.
How do I customize these recipes?
Each recipe includes a configuration section. Override model selection, API keys, and parameters without changing core logic.