Agent-to-Agent Escalation Routing Prompt

This prompt is a control-plane component for orchestration engineers and platform builders managing multi-agent topologies. Its job is to produce a structured routing decision when an agent hits a defined boundary and cannot proceed autonomously. The trigger is not a simple error, but a specific operational state: low confidence in an output, a detected capability gap, a policy trigger that requires a different authority level, or a tool failure that the current agent cannot resolve. The output is a machine-readable decision containing a target agent identifier, a context payload for the handoff, and a reason code that logs why the transfer occurred. This is not a prompt for generating user-facing text; it is infrastructure logic expressed in natural language.

The ideal user is an AI platform engineer wiring together an agent mesh. They should use this prompt inside an orchestration layer that reads the routing decision and programmatically executes the handoff. The required context includes the current agent's role and capabilities, the task state, the failure or boundary condition, and a registry of available downstream agents with their specializations. Do not use this prompt for agent-to-human handoffs, which require a different output schema focused on summarization and approval requests. Do not use it for single-agent retry logic, where the correct path is a self-correction or tool-call loop. Do not use it when the current agent can resolve the task with a clarification question or an alternative tool call. Misapplying this prompt in those scenarios will produce unnecessary routing overhead and fragment the task context.

Before implementing, ensure your orchestration layer can parse a strict JSON routing decision and act on it. The prompt's value is in standardizing the handoff contract: every escalation produces the same fields, making agent behavior auditable and the topology reconfigurable without rewriting prompts. If your system lacks a formal agent registry or cannot enforce that the target agent receives the full context payload, the routing decision will be useless. Start by defining the boundary conditions that should trigger this prompt, then map each condition to the reason codes your orchestration layer will log and monitor. Avoid using this prompt as a catch-all error handler; it is a precision tool for planned capability boundaries.

This prompt template is designed to be wired into an orchestration layer that manages a fleet of specialized agents. It acts as a decision node, consuming structured context about the current agent's state, the task at hand, the available downstream agents, and the organization's escalation policy. The output is a strict JSON routing decision that your application can parse and execute without ambiguity. Use this when you need a deterministic, auditable handoff between agents rather than an open-ended conversation.

textCopy
You are an escalation router for a multi-agent system. Your job is to decide which agent should handle a task when the current agent cannot proceed.

[CURRENT_AGENT_ROLE]

[TASK_CONTEXT]

[AGENT_CATALOG]

[ESCALATION_POLICY]

[CONSTRAINTS]

Based on the information above, produce a routing decision. If the task should stay with the current agent, set target_agent_id to null and reason_code to "NO_ESCALATION_REQUIRED". If escalation is required, select the best target agent from the catalog and package the essential context for handoff.

Return ONLY valid JSON matching this schema:
{
  "decision": {
    "escalate": boolean,
    "target_agent_id": string | null,
    "reason_code": "CAPABILITY_GAP" | "LOW_CONFIDENCE" | "POLICY_TRIGGER" | "TOOL_FAILURE" | "TIMEOUT" | "NO_ESCALATION_REQUIRED",
    "rationale": string,
    "confidence": number
  },
  "handoff_payload": {
    "task_summary": string,
    "completed_steps": [string],
    "pending_steps": [string],
    "artifacts": [{"id": string, "type": string, "summary": string}],
    "constraints_to_preserve": [string],
    "user_visible_context": string
  }
}

To adapt this template, replace each square-bracket placeholder with structured data from your application state. [CURRENT_AGENT_ROLE] should describe the agent's capabilities, current task, and reason for considering escalation. [TASK_CONTEXT] must include the original user request, any intermediate results, and the specific blocker. [AGENT_CATALOG] is a list of available agents with their IDs, capabilities, and current availability status. [ESCALATION_POLICY] encodes your organization's rules: when to escalate, which agent types handle which scenarios, and any cost or latency constraints. [CONSTRAINTS] can include output length limits, forbidden agent targets, or required approval steps. After adapting, validate that the JSON schema is enforced in your application layer—do not rely on the model alone to produce valid JSON every time.

Before deploying, build a test harness with at least 20 scenarios covering each reason_code. Include edge cases: an agent catalog with no suitable target, a task that partially matches two agents, and a policy that conflicts with capability matching. Measure routing accuracy against human-labeled decisions and track context preservation by having a downstream agent attempt to continue the task using only the handoff_payload. If the downstream agent cannot proceed without re-asking for information, the handoff payload is incomplete. For high-stakes domains, log every routing decision with the full prompt and response for auditability, and consider a human-in-the-loop review step when confidence falls below 0.85 or when reason_code is POLICY_TRIGGER.

This prompt is a decision node in an agent mesh, not a conversational turn. It expects a structured escalation signal from the current agent and must return a validated routing decision that the orchestration engine can act on without human parsing. The harness is responsible for assembling the prompt, calling the model, validating the output, and executing the handoff. Treat the prompt as a pure function: deterministic inputs, structured output, and a single retry path on validation failure.

The orchestration engine should follow a strict execution sequence. First, receive the current agent's escalation signal and fetch the live agent catalog from the service registry—never hardcode agent names or capabilities in the prompt. Second, assemble the prompt by injecting the catalog, the escalation context, and the output schema into their respective placeholders. Third, call the model with response_format set to json_object and temperature at or below 0.2 to minimize variance in routing decisions. Fourth, validate the output against the expected schema before any routing action: check that target_agent_id exists in the catalog, that handoff_reason_code matches an allowed enum, and that handoff_payload contains all required fields. Fifth, log the full routing decision with a timestamp, session ID, and the raw model response for auditability. Sixth, execute the handoff by posting the handoff_payload to the target agent's input queue. If validation fails, inject the specific validation error into the [CONSTRAINTS] placeholder and retry exactly once. If the target agent is unavailable, fall back to the next_best_agent_id from the validated output or escalate to a human review queue if no fallback exists.

Never route based on an unvalidated model output. A hallucinated agent ID or malformed payload can cause silent handoff failures that are difficult to diagnose in production. Build the harness to fail closed: if validation fails after the retry, if the target agent is unreachable, or if the model returns a refusal, route to a human review queue with the full context preserved. Log every decision path—success, fallback, and failure—so the operations team can monitor escalation rates, fallback frequency, and validation failure patterns over time.