Incomplete Task Handoff Prompt

This prompt is a structured serialization protocol for agent state, designed for orchestration engineers who must transfer a partially completed unit of work from one agent to another. The primary job-to-be-done is lossless context transfer when an agent has been interrupted, timed out, or reached its capability boundary. The ideal user is an AI platform engineer building a multi-agent orchestration layer who needs a machine-readable handoff package that a receiving agent can parse and act on without re-executing completed work or misinterpreting intermediate results. The required context includes the original task definition, a list of completed subtasks with their outputs, a list of remaining subtasks, any preserved intermediate artifacts (e.g., tool call results, retrieved documents, partial code), and a clear specification of the capabilities the receiving agent must possess.

Use this prompt when the sending agent has made meaningful progress that would be expensive or impossible to reproduce, and the receiving agent is a different specialization or instance that lacks the sending agent's short-term memory. Concrete triggers include: a tool-call timeout after retrieving 3 of 5 required documents, a context-window overflow during a long chain-of-thought, a capability gap where the current agent cannot perform the next required action (e.g., a planning agent handing off to a code-execution agent), or a preemptive handoff to a more cost-effective model for remaining simpler subtasks. The prompt is also appropriate when an orchestrator detects an agent health-check failure and must reroute in-flight work. In all cases, the sending agent must have enough context to accurately describe what is done and what remains; do not use this prompt if the agent itself cannot reliably enumerate its own progress.

Do not use this prompt when the task is fully complete and only a final response is needed—that is a standard output, not a handoff. Do not use it when the failure is unrecoverable and requires human intervention with full context; in that case, use an Agent Human-in-the-Loop Handoff Prompt instead. Avoid using this prompt when the receiving agent is identical in capability and context to the sending agent, as the handoff overhead exceeds the benefit of a simple retry. Critically, do not use this prompt if the sending agent cannot distinguish between completed and uncompleted work, as a hallucinated progress report will corrupt the downstream agent's execution. For high-risk domains such as healthcare or finance, the handoff package must include an [EVIDENCE_LOG] with source grounding for every completed subtask, and the receiving agent should be instructed to re-validate any intermediate results that influence a final decision. The next step after reading this section is to review the prompt template and adapt the [COMPLETED_SUBTASKS] and [REMAINING_WORK_ITEMS] schemas to match your agent graph's specific task decomposition format.

This prompt template is designed to be pasted directly into your orchestration layer. It instructs a model to act as a failing agent that must produce a lossless handoff artifact for a successor agent. The template uses square-bracket placeholders for all dynamic inputs, ensuring no unresolved tokens leak into the final request. Before sending this to the model, replace every placeholder with the actual values from your execution context.

codeCopy
You are an agent in a multi-agent workflow. Your task was to [ORIGINAL_TASK_DESCRIPTION], but you are unable to complete it due to [FAILURE_REASON].

Your only job now is to produce a structured handoff package so a successor agent can resume the work without losing context or repeating completed steps. Do not attempt to solve the original task. Do not fabricate results.

Generate a JSON object conforming to this exact schema:
{
  "handoff_version": "1.0",
  "originating_agent": "[AGENT_ID]",
  "failure": {
    "reason": "[FAILURE_REASON]",
    "failure_type": "[FAILURE_TYPE]",
    "timestamp": "[CURRENT_TIMESTAMP]"
  },
  "completed_subtasks": [
    {
      "subtask_id": "string",
      "description": "string",
      "result": "string | object",
      "artifacts": ["string"]
    }
  ],
  "remaining_work": [
    {
      "subtask_id": "string",
      "description": "string",
      "priority": "high | medium | low",
      "dependencies": ["subtask_id"],
      "estimated_effort": "string"
    }
  ],
  "intermediate_state": {
    "key_findings": ["string"],
    "working_data": {},
    "assumptions": ["string"],
    "open_questions": ["string"]
  },
  "required_capabilities": ["string"],
  "context_for_successor": "string"
}

Rules:
- Populate `completed_subtasks` only with work that is fully finished and verified. If you are unsure, list it under `remaining_work` with a note.
- The `intermediate_state.working_data` object must contain all partial results, intermediate calculations, and retrieved context. Preserve everything.
- `required_capabilities` must list the tools, permissions, or knowledge the successor agent needs. Be specific (e.g., "access to customer_db:read", not "database access").
- `context_for_successor` is a free-text field where you must explain the user's original intent, any decisions you made, and pitfalls to avoid.
- If [RISK_LEVEL] is "high", you must also flag any safety, compliance, or data-handling concerns in `context_for_successor`.

[INPUT]
[CONTEXT]

To adapt this template, start by mapping your agent's internal state to the completed_subtasks and intermediate_state fields. The most common failure mode is an agent claiming a subtask is complete when it is not; if your agent cannot assert completion with high confidence, add a confidence field to each subtask object and enforce a minimum threshold before marking it complete. For high-risk workflows, always route the handoff JSON through a validation step that checks for missing required fields and non-empty remaining_work arrays before forwarding to the successor agent. Never send a handoff with an empty required_capabilities list—this is a strong signal that the failing agent did not properly diagnose its own limitations.

The Incomplete Task Handoff Prompt is designed to sit at the boundary between two agents in a multi-agent pipeline. When an upstream agent cannot complete its assigned work—due to a timeout, tool failure, policy refusal, or capability gap—this prompt structures the handoff so the receiving agent gets a complete picture of what was done, what remains, and what intermediate results are available. In an orchestration framework, this prompt should be invoked by the supervisor or orchestrator agent immediately after detecting an incomplete termination signal from the upstream agent. The orchestrator should capture the upstream agent's final state, partial outputs, and any error context, then populate the [COMPLETED_SUBTASKS], [REMAINING_WORK_ITEMS], [INTERMEDIATE_RESULTS], and [FAILURE_CONTEXT] placeholders before calling the handoff prompt.

Wire this prompt into your agent framework as a structured handoff function that runs before routing work to the next agent. The function should: (1) validate that all required fields in the handoff payload are populated—empty [COMPLETED_SUBTASKS] is acceptable if nothing was finished, but missing [REMAINING_WORK_ITEMS] should trigger an error; (2) serialize intermediate results in a format the receiving agent can consume, preserving file handles, database cursors, or API response objects as structured references rather than raw text dumps; (3) attach a unique handoff ID and timestamp for traceability across agent boundaries; (4) log the full handoff payload to your observability pipeline so you can audit context transfer fidelity later. If the receiving agent is a different model or has different tool access, include a [REQUIRED_CAPABILITIES] field that the orchestrator checks against the receiving agent's capability registry before routing—mismatches should escalate to a human operator rather than silently failing downstream.

For production reliability, implement a handoff validation step before the receiving agent begins work. This validator should confirm that the handoff payload is parseable, that all referenced intermediate results are accessible, and that the remaining work items are actionable given the receiving agent's known capabilities. If validation fails, retry the handoff prompt once with an explicit error message injected into [FAILURE_CONTEXT]. If validation fails twice, escalate to a human-in-the-loop queue with the partial handoff package and a structured summary of what could not be validated. Avoid the common failure mode of passing incomplete handoffs silently—this is the primary cause of duplicated work and conflicting agent actions in multi-agent systems. Use the eval criteria defined in the playbook (completeness of handoff, accuracy of state capture, clarity of boundary marking) as automated guardrails in your CI/CD pipeline before deploying any changes to the handoff prompt or the surrounding orchestration logic.