Escalation Trigger Prompt for Role Handoff

This prompt is designed for the control loop of a compound AI orchestrator, not for direct user interaction. Its job-to-be-done is to produce a machine-readable escalation decision when a sub-agent cannot complete its assigned task due to a timeout, a confidence score falling below a defined threshold, an unrecoverable tool error, or a detected deadlock. The ideal user is a reliability engineer or platform architect who needs to convert a failed execution state into a structured routing decision that a downstream dispatcher can act on without replaying the entire failed session. The required context includes the sub-agent's original task definition, the failure reason, the current session state, and a registry of available escalation targets.

You should use this prompt when your orchestrator's monitoring logic detects a terminal failure condition in a sub-agent's execution loop. For example, if a 'data-fetcher' agent times out after three retries while querying an internal API, this prompt would classify the reason as TIMEOUT, select the human-operator role as the escalation target, and package the failed query, partial results, and error trace into a structured context payload. The output is not a user-facing message; it is a JSON decision object that your routing middleware parses to invoke the next step in the workflow. This prompt is essential for building resilient agent pipelines where silent failures are unacceptable.

Do not use this prompt for initial task dispatch, where an orchestrator is assigning work to a healthy agent for the first time—that belongs to a separate dispatch prompt. Do not use it for generating a handoff summary between two successful agents, as that requires a different template focused on progress transfer rather than failure classification. Avoid using this prompt to generate user-facing explanations; its output is designed for machine consumption, and exposing raw escalation reasons to end users can create confusion or erode trust. If your workflow requires a human-readable summary of the failure, pipe the output of this prompt into a separate user-communication template rather than modifying this one.

This prompt is designed to sit inside your orchestrator's escalation path. When a sub-agent returns a failure signal, exceeds a timeout, or produces output below a confidence threshold, this prompt takes the sub-agent's final state, the original task, and the available role registry, then produces a structured escalation decision. The output includes a reason classification (e.g., timeout, capability_gap, confidence_below_threshold, deadlock_detected, policy_block), a recommended target role, and a context package formatted for the receiving agent. Use this when you need consistent, auditable escalation logic rather than ad-hoc retry loops or silent failures.

textCopy
SYSTEM: You are an escalation decision engine for a multi-agent system. Your job is to analyze a failed sub-agent execution and produce a structured escalation decision. You do not execute tasks yourself. You only decide where work should go next and what context the receiving agent needs.

INPUTS:
- [ORIGINAL_TASK]: The task originally assigned to the sub-agent.
- [SUB_AGENT_ROLE]: The role and capability declaration of the agent that failed.
- [FAILURE_SIGNAL]: The error, timeout, low-confidence output, or deadlock condition reported.
- [SUB_AGENT_STATE]: The sub-agent's final state, including partial outputs, tool call history, and any unresolved items.
- [ROLE_REGISTRY]: A list of available target roles with their capability manifests, permission boundaries, and current load.
- [SESSION_CONTEXT]: Relevant conversation history, active constraints, and policy rules that must carry forward.
- [ESCALATION_POLICY]: Rules governing when to escalate to a human vs. another agent, retry limits, and deadlock definitions.

OUTPUT_SCHEMA:
{
  "escalation_decision": {
    "should_escalate": boolean,
    "reason_classification": "timeout" | "capability_gap" | "confidence_below_threshold" | "deadlock_detected" | "policy_block" | "tool_failure" | "other",
    "reason_detail": "string explaining the specific failure",
    "target_role": "role_id or 'human_operator'",
    "target_role_justification": "why this role was selected over alternatives",
    "context_package": {
      "original_task_summary": "compressed version of [ORIGINAL_TASK]",
      "completed_work": "what the sub-agent finished before failure",
      "pending_items": ["list of unresolved items"],
      "failure_context": "relevant state at failure point",
      "active_constraints": ["constraints that must carry forward"],
      "tool_outputs_carried_forward": ["tool results the next agent needs"]
    },
    "retry_eligibility": {
      "can_retry_same_role": boolean,
      "retry_conditions": "what must change before retry is safe",
      "max_retries_exceeded": boolean
    },
    "user_notification": "language for notifying the user if applicable, or null"
  }
}

CONSTRAINTS:
- Do not fabricate capabilities for target roles. Only select roles whose declared manifests in [ROLE_REGISTRY] cover the pending items.
- If no role matches, set target_role to 'human_operator' and explain the gap.
- If [ESCALATION_POLICY] requires human approval for this failure class, set target_role to 'human_operator' regardless of role availability.
- The context_package must not exceed [MAX_CONTEXT_TOKENS] tokens. Prune aggressively, prioritizing pending items and active constraints over completed work.
- If the failure is classified as 'deadlock_detected', include the deadlock cycle description in reason_detail.
- If the failure is 'policy_block', do not attempt to route around the policy. Escalate to human_operator.

OUTPUT FORMAT: Valid JSON only. No markdown, no commentary.

Adaptation guidance: Replace each square-bracket placeholder at runtime. [ROLE_REGISTRY] should be a serialized list of available agent manifests, not free-text descriptions—this ensures the model selects roles based on declared capabilities rather than name similarity. [ESCALATION_POLICY] should include concrete thresholds (e.g., "confidence below 0.7 triggers escalation") rather than vague guidance. The context_package size constraint [MAX_CONTEXT_TOKENS] should be set based on your target model's context window minus the system prompt and output buffer. If you are using this in a regulated domain, add a [REQUIRE_HUMAN_REVIEW] boolean to the output schema and enforce it in your application layer before any automated handoff executes.

What to do next: Wire this prompt into your orchestrator's error-handling path so it fires on sub-agent timeout, explicit failure return codes, or confidence scores below your threshold. Validate the JSON output against the schema before acting on the escalation decision. Log every escalation decision with the full input state for post-incident debugging. If target_role is human_operator, route to your human review queue with the context_package and user_notification fields pre-filled. Avoid the temptation to skip this prompt and hard-code escalation paths—failure modes evolve as you add agents, and a structured decision prompt gives you an auditable, adaptable escalation surface that a switch statement cannot.

The escalation trigger prompt is not a standalone chat prompt; it is a decision node inside an agent orchestrator. It should be called when a sub-agent signals failure, exceeds a timeout, returns a low-confidence result, or encounters a deadlock condition. The orchestrator packages the sub-agent's state, the original task, the failure signal, and the available role registry into the prompt's [CURRENT_STATE], [FAILURE_SIGNAL], and [ROLE_REGISTRY] placeholders. The prompt returns a structured escalation decision that the orchestrator parses and executes: either routing to a new target role with a packaged context payload, escalating to a human operator, or terminating the task with a logged reason.

Wire the prompt into a decision function with strict input validation before invocation. The [ROLE_REGISTRY] must be a validated list of active roles with capability manifests, current availability status, and permission boundaries. The [FAILURE_SIGNAL] must include a machine-readable failure code (TIMEOUT, LOW_CONFIDENCE, TOOL_ERROR, PERMISSION_DENIED, DEADLOCK, UNKNOWN) and the sub-agent's last output. Validate that [CURRENT_STATE] contains the original task definition, conversation history, and any tool call results. If any required input is missing or malformed, do not call the model; instead, log the validation failure and fall back to a default escalation path (typically human review). After receiving the model's output, validate the JSON schema: reason_classification must match an allowed enum, target_role must exist in the provided registry, and context_package must not exceed a predefined token budget. If validation fails, retry once with the validation error injected into the [CONSTRAINTS] field. If the retry also fails, escalate to a human operator with the raw model output and validation errors attached.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature=0 to maximize decision consistency. Log every escalation decision with a trace ID, the input state hash, the model's raw output, the validated decision, and the action taken by the orchestrator. This audit trail is essential for debugging incorrect escalations and for governance reviews. Avoid calling this prompt inside a tight retry loop without backoff; a sub-agent that repeatedly triggers escalation should be quarantined, not retried indefinitely. The orchestrator should track per-agent escalation counts and trigger an operator alert if a single agent exceeds a threshold within a session. For high-risk domains, require human approval before executing any escalation that grants a new role access to sensitive tools or data. The approval gate should present the escalation reason, the proposed target role, and the context package for review before the orchestrator proceeds.