Exception Handling Handoff Prompt for Edge Cases

This prompt is designed for autonomous agents operating within a strictly bounded scope. Its primary job is to prevent silent failures, hallucinated completions, or infinite retry loops when the agent encounters an edge case it cannot resolve. Use this when your agent's architecture includes a defined 'capability boundary'—a clear contract stating what the agent can and cannot do. The ideal user is an AI engineer or platform developer integrating an agent into a production system where unhandled exceptions could corrupt data, mislead users, or violate policy. The required context includes the agent's original task, the specific input or condition that triggered the exception, and a log of any failed internal attempts to resolve it.

Do not use this prompt for routine task completion handoffs where the agent successfully completed its work and is simply passing results to a human for final approval. Those scenarios require a structured summary prompt, not an exception handler. Similarly, avoid using this for low-confidence outputs that still fall within the agent's domain—confidence-based escalation has its own dedicated prompt template. This prompt is specifically for out-of-distribution inputs, missing tools, policy blocks, or environmental conditions that the agent was never designed to handle. In high-risk domains such as healthcare, finance, or legal review, this handoff must include an evidence package and an audit trail. The harness should log every exception handoff event, including the agent's identity, the timestamp, and the specific boundary condition that was violated, to support governance reviews.

Before wiring this into your application, map your agent's explicit capability boundaries. If you cannot list what the agent is not allowed to do, this prompt will fire too often or too rarely. Start by defining a taxonomy of out-of-scope conditions—unsupported input types, missing permissions, unrecognized intents, or environmental failures—and test the prompt against each. The next step is to pair this prompt with a routing layer that captures the handoff payload and delivers it to the appropriate human queue. Avoid the common failure mode of treating every unexpected model output as an exception; reserve this prompt for genuine capability gaps, not recoverable formatting errors or transient tool failures.

This template is designed to be pasted directly into your agent's escalation path. It forces the model to identify the specific edge case, explain why it falls outside the agent's capability boundary, and package enough structured context for a human operator to pick up the task without reading raw agent logs or replaying the session. Replace every square-bracket placeholder with runtime values before sending to the model. The template assumes the agent has already attempted its standard resolution path and determined that escalation is required.

textCopy
You are an exception-handling agent responsible for producing structured handoff packages when the primary agent encounters an input or situation outside its defined operating envelope.

## INPUT
[AGENT_IDENTITY]: The role and capabilities of the agent that encountered the exception.
[OPERATING_ENVELOPE]: A clear description of what the agent is authorized and able to handle, including domain boundaries, action limits, and policy constraints.
[SESSION_CONTEXT]: The relevant conversation history, tool outputs, and state leading up to the exception.
[TRIGGER_INPUT]: The specific user request, tool result, or system event that caused the exception.
[FAILURE_REASON]: What the agent attempted and why it could not proceed (capability gap, policy block, ambiguity, missing tool, confidence below threshold).
[CONSTRAINTS]: Any additional rules for the handoff, such as required fields, tone, or compliance notes.

## OUTPUT_SCHEMA
Return a JSON object with the following fields:
- "exception_id": string (unique identifier for this exception instance)
- "timestamp": string (ISO 8601 timestamp of when the exception occurred)
- "agent_identity": string (the agent that encountered the exception)
- "exception_category": string (one of: "capability_gap", "policy_violation_risk", "ambiguous_intent", "tool_failure", "confidence_below_threshold", "domain_boundary", "other")
- "edge_case_description": string (a concise, specific description of what makes this input or situation an edge case)
- "why_outside_envelope": string (explanation of why this falls outside the agent's defined operating envelope, referencing the specific boundary that was hit)
- "agent_actions_attempted": array of strings (the steps the agent took before escalating, in order)
- "failure_point": string (the exact step or condition where the agent could not proceed)
- "context_for_human": string (all information a human needs to understand the situation and take over, including relevant excerpts from the session, tool outputs, and user intent)
- "suggested_human_actions": array of strings (ranked list of actions the human reviewer should consider, with rationale for each)
- "urgency": string (one of: "low", "medium", "high", "critical", with a one-sentence justification)
- "related_policies": array of strings (any policies, rules, or constraints relevant to the exception)
- "requires_approval": boolean (whether the human action requires formal approval before execution)

## INSTRUCTIONS
1. Identify the specific edge case from [TRIGGER_INPUT] and [SESSION_CONTEXT]. Do not generalize. Name the exact condition that broke the agent's ability to proceed.
2. Map the edge case to the correct exception_category. If multiple categories apply, choose the most specific one.
3. Explain why this falls outside [OPERATING_ENVELOPE] by referencing the specific boundary, capability limit, or policy constraint that was violated or exceeded.
4. List every action the agent attempted before escalation. Do not skip failed attempts.
5. Provide enough context_for_human that a reviewer can understand the situation without reading raw logs. Include relevant excerpts, not full transcripts.
6. Rank suggested_human_actions from most to least recommended. Each action must include a one-sentence rationale.
7. Set urgency based on impact, not on the agent's frustration. Justify in one sentence.
8. If [CONSTRAINTS] specifies required fields or compliance notes, ensure they are reflected in the output.
9. If the exception involves regulated data, financial decisions, health information, or legal content, set requires_approval to true and flag the relevant policies.
10. Do not speculate beyond the evidence. If information is missing, note it explicitly rather than filling gaps.

Adapt this template by adjusting the exception_category enum to match your agent's actual failure taxonomy. If your system uses structured tool-call logs, replace the agent_actions_attempted array with a reference to the trace ID instead of duplicating steps. For high-compliance environments, add a "reviewer_attestation" field to the output schema that captures the human reviewer's identity, decision, and timestamp. Always validate the output JSON against the schema before routing to a human queue—malformed handoffs create more work than no handoff at all.

The Exception Handling Handoff Prompt is not a standalone chat prompt—it is a circuit breaker inside an agent execution loop. Wire it as a fallback handler that activates when the primary agent's execution guardrails are tripped. Common triggers include: a tool returning an error code outside the agent's recovery list, an input that fails schema or policy validation after retries, a confidence score dropping below a configured threshold, or the agent detecting a topic or entity type explicitly listed in its out-of-scope manifest. The orchestration layer should catch these signals, suspend the agent's execution context, and invoke this handoff prompt with the full failure context, agent trace, and original input.

Implement the harness as a structured function call, not a free-text prompt injection. The function should accept parameters: agent_id, session_id, original_input, failure_reason_code, agent_trace (last N steps), tool_errors (array of error objects), and out_of_scope_evidence (the specific field or condition that violated the operating envelope). The prompt template's [EDGE_CASE_DESCRIPTION] should be populated programmatically from failure_reason_code and out_of_scope_evidence. The [AGENT_CONTEXT] placeholder should receive a serialized summary of agent_trace and tool_errors, not the raw log dump—preprocess the trace to extract the last meaningful action, the point of failure, and any partial results. This keeps the handoff payload tight and prevents the human reviewer from having to parse raw agent chatter. On the application side, validate the model's output against the [OUTPUT_SCHEMA] before routing to a human queue. If the model fails to produce a valid exception_category or required_human_action, retry once with a stricter constraint prompt, then fall back to a templated handoff with raw context attached.

Model choice matters here. Use a model with strong instruction-following and structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature to 0 or near-zero to avoid creative drift in the exception_category and required_human_action fields. Log every handoff invocation with the session_id, failure_reason_code, and the generated exception_category for monitoring. Track the rate of handoffs by failure_reason_code to identify whether the agent's operating envelope needs expansion or whether upstream input validation is insufficient. If a specific failure_reason_code triggers handoffs for more than 5% of sessions, that's a signal to either extend the agent's capability, add a pre-processing guard, or refine the out-of-scope detection logic. Do not use this prompt for transient errors (network timeouts, rate limits)—those belong in a retry loop with exponential backoff. Reserve this handoff for genuine edge cases where the agent's design contract says 'stop and ask a human.' Wire the output into your existing ticketing or review queue system with the exception_category as a routing tag and the urgency_level mapped to your SLA tiers.