Handoff Timeout and Abort Prompt Template

This prompt is designed for the error-recovery path of a multi-agent orchestrator, specifically for reliability engineers and platform teams who need to prevent silent failures when a sub-agent becomes unresponsive. It is triggered by a watchdog timer or a response validator that detects a stalled sub-agent—one that has exceeded its execution window, returned a malformed response, or stopped responding entirely. The job-to-be-done is not to diagnose the root cause of the failure, but to safely terminate the interaction, preserve state for debugging, notify the end-user, and route the task to a fallback. This is a critical safety net; without it, a single stuck agent can block an entire pipeline, consuming resources and degrading the user experience without any visible error.

Do not use this prompt for initial agent dispatch or for generating a standard handoff summary when a sub-agent completes successfully. Those workflows are covered by separate playbooks for orchestrator dispatch and handoff summary generation. This prompt belongs exclusively in the abort path. The required context includes the original task assignment, the sub-agent's last known state, the timeout threshold that was exceeded, and any partial or malformed output received. The ideal user is an engineer integrating this into an orchestrator's exception-handling logic, where the prompt's structured output—an abort decision, a state snapshot, a user notification, and a fallback routing instruction—can be parsed and acted upon programmatically.

Before wiring this into production, ensure your watchdog timer and response validator are correctly configured to trigger this prompt only on genuine stalls, not on transient network latency. A false trigger will abort a healthy agent and create unnecessary fallback load. You should also define clear ownership of the fallback path: the orchestrator must know which agent or human queue receives the aborted task. Finally, treat the preserved state as ephemeral debugging data with a strict retention policy to avoid accumulating sensitive context in logs. The next step is to review the prompt template and adapt its placeholders to your specific agent registry, timeout values, and notification channels.

This prompt is designed to sit inside your orchestrator's error-handling path. When a sub-agent exceeds its execution window or fails to respond, this template produces a structured abort decision, a cleanup plan, and a fallback routing instruction. It is not a generic timeout handler—it is built for multi-agent pipelines where silent failures cascade into broken user experiences and orphaned state.

textCopy
SYSTEM: You are a reliability controller for a multi-agent orchestration system. Your job is to detect when a sub-agent has exceeded its execution window, decide whether to abort, and produce a structured recovery payload.

ROLE: Timeout and Abort Controller

INPUT:
- [AGENT_ID]: Identifier of the sub-agent being monitored.
- [AGENT_ROLE]: Declared role of the sub-agent.
- [TASK_DESCRIPTION]: The task assigned to the sub-agent.
- [ELAPSED_TIME_MS]: Milliseconds since the task was dispatched.
- [TIMEOUT_THRESHOLD_MS]: Maximum allowed execution time.
- [LAST_RESPONSE_TIMESTAMP]: ISO-8601 timestamp of the last response from the sub-agent, or null if no response received.
- [AGENT_STATE_SNAPSHOT]: Serialized state of the sub-agent at last checkpoint, including tool call history, partial outputs, and pending approvals.
- [FALLBACK_AGENTS]: List of available fallback agents with their capabilities and current load.
- [USER_VISIBLE_CONTEXT]: What the user has been shown about this task so far.

CONSTRAINTS:
- If ELAPSED_TIME_MS < TIMEOUT_THRESHOLD_MS and LAST_RESPONSE_TIMESTAMP is within [HEARTBEAT_INTERVAL_MS], do not abort. Return a WAIT decision.
- If the sub-agent has produced partial valid output, preserve it. Do not discard work that can be reused.
- If the sub-agent is in the middle of a tool call with side effects, flag the tool call state explicitly so the fallback agent can decide whether to retry, rollback, or continue.
- Never expose raw agent internals to the user. User-facing messages must be clear, calm, and actionable.
- If no fallback agent can handle the task, escalate to [HUMAN_QUEUE_ENDPOINT] with full context.

OUTPUT_SCHEMA:
{
  "decision": "ABORT" | "WAIT" | "ESCALATE_TO_HUMAN",
  "reason": "String explaining the decision with specific evidence from INPUT.",
  "abort_detail": {
    "agent_id": "[AGENT_ID]",
    "failure_classification": "TIMEOUT_NO_RESPONSE" | "TIMEOUT_PARTIAL_OUTPUT" | "HEARTBEAT_LOST" | "TOOL_CALL_STUCK",
    "partial_output_preserved": "String or null. Any valid output the sub-agent produced before timing out.",
    "tool_call_state": {
      "active_tool": "String or null. Name of the tool in flight.",
      "tool_call_id": "String or null.",
      "side_effects_possible": true | false,
      "recommended_recovery": "RETRY_IDEMPOTENT" | "ROLLBACK_AND_RETRY" | "DO_NOT_RETRY" | "MANUAL_REVIEW_REQUIRED"
    },
    "checkpoint_restore_instructions": "String. How to restore agent state from AGENT_STATE_SNAPSHOT if retrying."
  },
  "fallback_routing": {
    "selected_agent": "String or null. ID of the fallback agent.",
    "handoff_payload": {
      "task_description": "String. The original task, possibly scoped down.",
      "prior_progress": "String. What was completed before abort.",
      "constraints_carried_forward": ["String. Constraints the fallback must respect."],
      "do_not_repeat": ["String. Actions already completed that must not be duplicated."]
    },
    "escalation_reason": "String or null. Why no fallback agent was suitable."
  },
  "user_notification": {
    "message": "String. What to tell the user. Calm, honest, no internals.",
    "estimated_wait": "String. How long until resolution, if known.",
    "action_required_from_user": "String or null. If the user must provide input."
  },
  "audit_log_entry": {
    "timestamp": "ISO-8601",
    "orchestrator_version": "[ORCHESTRATOR_VERSION]",
    "abort_trigger": "TIMEOUT" | "HEARTBEAT_LOSS" | "MANUAL_ABORT",
    "context_hash": "String. Hash of the full context for traceability."
  }
}

INSTRUCTIONS:
1. Compare ELAPSED_TIME_MS against TIMEOUT_THRESHOLD_MS.
2. Check LAST_RESPONSE_TIMESTAMP against the current time. If the gap exceeds [HEARTBEAT_INTERVAL_MS], treat as heartbeat loss.
3. If either condition triggers, classify the failure and populate abort_detail.
4. Select the best fallback agent from FALLBACK_AGENTS based on capability match and current load. If none qualify, set escalation_reason.
5. Construct the user_notification. Never mention agent IDs, timeouts, or internal state.
6. Populate the audit_log_entry with traceable identifiers.
7. Return ONLY valid JSON matching OUTPUT_SCHEMA. No additional text.

To adapt this template, replace every square-bracket placeholder at runtime before the prompt reaches the model. [AGENT_ID], [TASK_DESCRIPTION], and [TIMEOUT_THRESHOLD_MS] should come from your orchestrator's dispatch records. [AGENT_STATE_SNAPSHOT] must be a serialized checkpoint captured before the sub-agent was invoked—do not rely on the sub-agent to self-report its state after it has already stalled. [FALLBACK_AGENTS] should be a live query against your agent registry filtered by capability tags, not a static list. The [HEARTBEAT_INTERVAL_MS] should be shorter than [TIMEOUT_THRESHOLD_MS] to catch silent failures before the full window expires. If you are operating in a regulated domain, ensure the audit_log_entry.context_hash is stored immutably and linked to your decision log for post-incident review.

This prompt is designed to sit inside an orchestrator's error-handling path, not as a standalone chat interaction. When a sub-agent exceeds its execution window or fails to respond, the orchestrator should invoke this prompt with the sub-agent's original task, the elapsed time, and any partial output. The prompt's job is to produce a structured abort decision, a state preservation payload for debugging, a user notification template, and a fallback routing instruction. Do not call this prompt for every handoff; reserve it for timeout conditions, unresponsive agents, or deadlock detection where the orchestrator must decide whether to retry, escalate, or abort.

Wire the prompt into your orchestrator's timeout handler. When a sub-agent call exceeds [TIMEOUT_SECONDS], capture the sub-agent's [TASK_DESCRIPTION], [ELAPSED_TIME], [PARTIAL_OUTPUT] (if any), and [AGENT_ID]. Pass these as variables into the prompt template. The model should return a JSON object with fields: abort_decision (enum: retry, escalate, abort, wait), state_snapshot (serialized context for debugging), user_notification (a message safe for end-user display), fallback_route (target agent ID or human queue), and reason (a concise explanation). Validate the output against this schema immediately. If abort_decision is retry, enforce a maximum retry count (typically 2-3) and exponential backoff before re-invoking the sub-agent. If escalate, route to the specified fallback agent or human review queue. If abort, log the state snapshot, notify the user with the provided template, and clean up the session. Never silently swallow a timeout without logging the state snapshot—this is your primary debugging artifact for post-incident review.

Model choice matters here. This prompt requires strict schema adherence and low-latency decision-making under failure conditions. Use a fast, instruction-following model (GPT-4o, Claude 3.5 Sonnet, or equivalent) with JSON mode or structured output enabled. Set temperature to 0 or near-zero to prevent creative abort decisions. If your orchestrator uses tool-calling, expose the abort decision as a tool schema so the model returns typed arguments rather than free-form JSON. Log every invocation: timestamp, agent ID, timeout threshold, elapsed time, model response, and the final action taken by the orchestrator. These logs become essential for tuning timeout thresholds and identifying which sub-agents are prone to hanging. For high-reliability systems, add an eval step that checks whether the abort_decision is consistent with the reason field and whether the user_notification is appropriate for the [RISK_LEVEL] of the task. If the task is high-risk (e.g., financial transaction, clinical note, access control change), require human approval before executing any abort decision other than wait.

Common failure modes to guard against: the model may produce an abort_decision of retry without checking whether the sub-agent is in a permanently broken state, leading to infinite retry loops. Mitigate this by capping retries and requiring the reason field to explain what changed since the last attempt. The model may generate a user_notification that exposes internal system details (agent IDs, timeout thresholds, stack traces). Mitigate this by adding a post-processing filter that strips internal identifiers from user-facing messages, or by including a [USER_VISIBLE_CONSTRAINTS] placeholder in the prompt that explicitly forbids internal detail leakage. The model may hallucinate a fallback_route to an agent that doesn't exist. Mitigate this by validating the fallback_route against your live agent registry before routing. If the route is invalid, default to a pre-configured human escalation queue and log the mismatch.

Do not use this prompt as a substitute for proper sub-agent health monitoring. Timeout and abort logic is a last-resort safety net, not a primary reliability strategy. Instrument your sub-agents with heartbeat signals, progress callbacks, and resource utilization metrics so the orchestrator can detect degradation before the timeout fires. When a timeout does fire, treat the resulting state snapshot as a bug report: investigate why the sub-agent hung, whether the timeout threshold is calibrated correctly, and whether the task decomposition was too large for a single agent. Feed these findings back into your sub-agent design and timeout configuration. The goal is to make timeout events rare, well-understood, and safely handled—not to build an elaborate abort machinery that masks systemic agent reliability problems.