Handoff Prompt with Escalation Reason Code Taxonomy

This prompt is for operations leads and platform engineers who need to standardize how AI systems categorize and package handoff events before routing them to human operators. The job-to-be-done is producing a structured handoff payload that includes a reason code from a defined taxonomy, supporting evidence, severity classification, and SLA context—so that downstream queues, ticketing systems, and on-call responders receive consistent, triage-ready information regardless of which AI workflow triggered the escalation. Without a shared taxonomy, handoffs become noisy, misrouted, and slow to resolve.

Use this prompt when you have multiple AI agents or automated workflows that escalate to humans and you need a single categorization scheme that works across support, infrastructure, compliance, and safety use cases. The prompt expects a defined taxonomy of escalation reason codes—such as CONFIDENCE_BELOW_THRESHOLD, GUARDRAIL_VIOLATION, TOOL_FAILURE, PERMISSION_DENIED, REGULATORY_BOUNDARY, or EDGE_CASE_DETECTED—and produces a payload that includes the selected code, a severity level, an urgency flag, and operator routing hints. You should also provide the raw context that triggered the escalation so the model can ground its classification in evidence rather than guessing.

Do not use this prompt when the escalation reason is obvious from a single error code, when the handoff target is another automated system that expects a raw log dump, or when the taxonomy itself is unstable and undergoing frequent redefinition. This prompt is not a replacement for a queue routing engine—it produces the categorization and context package, but your application layer must still handle delivery, acknowledgment tracking, and SLA timer starts. For high-severity escalations where misclassification could delay incident response, always include a human review step before the payload is committed to the routing queue.

This template is the core instruction set for generating a standardized handoff payload. It forces the model to classify the reason for escalation using a predefined taxonomy, attach supporting evidence, and produce a structured output that downstream routing and queueing systems can parse reliably. The prompt is designed to be adapted by replacing the square-bracket placeholders with your organization's specific codes, severity levels, and SLA definitions before integration.

codeCopy
SYSTEM: You are an AI system handoff controller. Your task is to generate a structured handoff payload when you reach a safe operating limit and must escalate to a human operator. You must classify the reason for handoff using only the provided taxonomy.

TAXONOMY:
[ESCALATION_REASON_CODES]

SEVERITY LEVELS:
[SEVERITY_LEVEL_DEFINITIONS]

SLA CONTEXT:
[SLA_DEFINITIONS]

INPUT CONTEXT:
[CONVERSATION_HISTORY]
[ACTION_LOG]
[TOOL_CALL_RESULTS]
[ERROR_STACK]

OUTPUT_SCHEMA:
{
  "handoff_type": "escalation",
  "reason_code": "[SELECT_FROM_TAXONOMY]",
  "reason_evidence": "[EVIDENCE_SUPPORTING_REASON_CODE]",
  "severity": "[SELECT_FROM_SEVERITY_LEVELS]",
  "urgency_flag": boolean,
  "sla_context": "[RELEVANT_SLA_DETAILS]",
  "operator_routing_hints": {
    "queue": "[SUGGESTED_QUEUE]",
    "required_skills": ["[SKILL_1]", "[SKILL_2]"]
  },
  "unresolved_state": "[SUMMARY_OF_UNRESOLVED_ITEMS]",
  "operator_orientation": "[CONCISE_BRIEF_FOR_OPERATOR]"
}

CONSTRAINTS:
- Select the reason_code ONLY from the provided TAXONOMY.
- If no reason code perfectly matches, use the closest parent code and note the gap in reason_evidence.
- Set urgency_flag to true if severity is [HIGH_SEVERITY_LEVELS] or SLA breach is imminent.
- The operator_orientation must be a single paragraph under 100 words.
- Do not invent new reason codes.

To adapt this template, replace the [ESCALATION_REASON_CODES] placeholder with your actual taxonomy, formatted as a clear list of codes and definitions. The [OUTPUT_SCHEMA] can be modified to match your ticketing or incident management system's API contract, but the core logic of mapping evidence to a fixed taxonomy must remain intact. For high-risk domains, add a [HUMAN_REVIEW_REQUIRED] boolean field to the schema and ensure the downstream system enforces a review step before any action is taken based on this payload.

This prompt is designed to be called by an AI agent or orchestration layer when the system determines it can no longer proceed autonomously. The caller must supply the full conversation transcript, the agent's action log, the specific failure or escalation trigger, and the reason code taxonomy. The prompt returns a structured JSON payload that your application parses and routes to a human review queue, ticketing system, or incident management platform. Do not call this prompt for every turn—only when the agent hits a defined escalation condition such as a guardrail violation, tool failure, confidence drop, or explicit user request for a human.

Integration pattern. Wrap the prompt in a function that accepts typed inputs (transcript, action_log, escalation_trigger, reason_code_taxonomy, severity_hint) and returns a validated HandoffPayload object. Before calling the model, assemble the taxonomy into the prompt's [REASON_CODE_TAXONOMY] placeholder as a JSON array of {code, label, description, urgency_default} objects. After receiving the model response, validate the output against your HandoffPayload schema: required fields include reason_code, severity, urgency_flag, summary, evidence, and routing_hints. If validation fails, retry once with the validation error injected into the prompt as additional context. If the retry also fails, log the raw output and fall back to a minimal handoff containing the raw transcript and a generic ESCALATION_UNCLASSIFIED reason code.

Routing and logging. Extract the routing_hints.queue_suggestion and urgency_flag from the validated payload to assign the ticket to the correct operator team with the appropriate SLA. Write the full payload, the prompt version, the model version, and the escalation trigger to your audit log before enqueueing. For regulated domains, require a human reviewer to acknowledge the handoff within a configurable time window; if the window expires, escalate to a fallback queue. Avoid using the model's raw output directly in customer-facing messages without review—the payload is an internal operations artifact, not a user message. The next step is to build a lightweight receiver that parses this payload and renders it for the operator alongside the original transcript.