Handoff Prompt for Incomplete Agent Tasks

This prompt is designed for a single, critical job: when an AI agent hits its execution budget, capability boundary, or a configured stop condition and cannot complete its assigned task, it must produce a structured handoff artifact. The ideal user is an AI platform engineer, orchestration developer, or product manager building a multi-agent system where tasks are expensive to lose. The required context includes the agent's original task definition, its execution trace, the current state of all relevant data, and the specific reason for the incomplete termination. Without this, the handoff is just a dead end, forcing a human or another agent to reverse-engineer the failure from raw logs.

This prompt is not a generic error message or a simple status update. It must be used when the cost of losing partial progress is high—think long-running research tasks, multi-step data extraction jobs, or compliance reviews where an agent has already invested significant compute. The output must be machine-parseable and human-actionable, containing the exact state required to resume work without replaying completed steps. A concrete implementation would wire this prompt into an agent's on_failure or on_budget_exceeded hook, passing the agent's internal trace, tool call history, and any intermediate outputs as the [PARTIAL_RESULTS] and [EXECUTION_TRACE] variables. The harness should validate that the output schema includes a resumable state object, not just a natural language summary.

Do not use this prompt for tasks that failed immediately with no useful progress, for agents that can simply retry with a longer budget, or for workflows where the cost of a clean restart is lower than the complexity of a stateful resume. Before implementing, ensure your orchestration layer can serialize and deserialize the [RESUMPTION_STATE] object so a downstream agent or human can pick up the task without manual reconstruction. The next step after generating this handoff is to route it to the appropriate escalation path—either a human review queue, a more capable agent, or a supervisor agent that can re-plan the remaining work.

The following prompt template is designed to be injected into an agent's context when it has exhausted its step budget, encountered an unrecoverable tool failure, or determined that the remaining work is outside its capability boundary. It forces the agent to produce a structured handoff payload that a human operator or a downstream agent can consume without reconstructing state from raw logs. The template uses square-bracket placeholders that your application must populate before sending the prompt to the model.

textCopy
SYSTEM: You are an agent that has been unable to complete the assigned task within your execution budget or capability boundary. You must now produce a structured handoff so that a human operator or another agent can resume the work without data loss.

TASK_CONTEXT:
[ORIGINAL_TASK_DESCRIPTION]

WORK_COMPLETED:
[COMPLETED_STEPS_AND_OUTPUTS]

CURRENT_STATE:
[INTERMEDIATE_RESULTS_AND_ARTIFACTS]

FAILURE_REASON:
[WHY_THE_TASK_COULD_NOT_BE_COMPLETED]

EXECUTION_BUDGET_REMAINING:
[STEPS_OR_TOKENS_REMAINING]

INSTRUCTIONS:
Produce a JSON handoff payload with the following structure. Do not include any text outside the JSON object.

{
  "handoff_type": "incomplete_task",
  "agent_id": "[AGENT_IDENTIFIER]",
  "task_id": "[TASK_IDENTIFIER]",
  "status": "partial_complete",
  "summary": "<One-paragraph summary of what was accomplished and why the task is incomplete.>",
  "completed_work": [
    {
      "step": "<Step description>",
      "outcome": "<What was produced or determined>",
      "artifacts": ["<Reference to any saved outputs, files, or data>"]
    }
  ],
  "remaining_work": [
    {
      "step": "<Next step that must be completed>",
      "estimated_effort": "<Low | Medium | High | Unknown>",
      "dependencies": ["<What must be true before this step can start>"],
      "required_inputs": ["<Data, decisions, or context needed to proceed>"]
    }
  ],
  "current_state": {
    "variables": {"<key>": "<value>"},
    "open_decisions": ["<Decisions that are still pending>"],
    "blockers": ["<What is preventing completion>"]
  },
  "resume_instructions": "<Step-by-step instructions for a human or agent to pick up where you left off. Include exact commands, API calls, or queries if applicable.>",
  "confidence_assessment": {
    "completed_work_confidence": "<High | Medium | Low>",
    "remaining_effort_confidence": "<High | Medium | Low>",
    "notes": "<Any caveats about the quality or completeness of the work done so far.>"
  },
  "escalation_recommendation": "<Whether this should go to a human reviewer, a specialized agent, or be retried with different parameters.>"
}

CONSTRAINTS:
- Do not fabricate completed work. Only report steps you actually executed.
- If you are uncertain about the quality of a completed step, flag it in confidence_assessment.notes.
- The resume_instructions field must be specific enough that a new agent or human can resume without reading your full execution trace.
- If any artifacts are stored externally, include retrieval paths or identifiers.
- If the task involves regulated data or high-risk actions, set escalation_recommendation to "human_review_required".

To adapt this template for your application, replace each square-bracket placeholder with live data from your agent's execution context. The [ORIGINAL_TASK_DESCRIPTION] should contain the user's original request verbatim. [COMPLETED_STEPS_AND_OUTPUTS] should be a structured log of what the agent actually did, not what it planned to do. [INTERMEDIATE_RESULTS_AND_ARTIFACTS] must include pointers to any saved state, files, or database records so the handoff is self-contained. If your agent framework tracks step counts or token usage, populate [STEPS_OR_TOKENS_REMAINING] with the actual remaining budget to help the model decide how much detail to include. For high-risk domains such as healthcare, finance, or legal workflows, add an additional constraint requiring the agent to flag any completed work that may need human verification before the next agent acts on it.

The handoff prompt for incomplete agent tasks is not a standalone chat interaction; it is a programmatic checkpoint inside an agent execution loop. The orchestration layer must invoke this prompt when the agent reaches a termination condition—such as exhausting its step budget, hitting a tool failure it cannot recover from, or encountering an input outside its capability boundary. The prompt receives the agent's current state, partial results, and the reason for termination, then produces a structured handoff payload that a downstream agent or human reviewer can consume without reconstructing context from raw logs.

To integrate this prompt, wrap it in a function that accepts a typed input object: agent_id, task_id, termination_reason (enum: STEP_BUDGET_EXHAUSTED, TOOL_FAILURE, CAPABILITY_GAP, TIMEOUT), completed_steps (ordered list of step descriptions with outputs), remaining_steps (ordered list of pending steps with dependencies), current_state_snapshot (serialized agent memory or blackboard state), and error_log (if applicable). The prompt template's [PARTIAL_RESULTS] placeholder should be populated with a structured JSON dump of this input, not raw conversation text. After the model returns the handoff summary, validate the output against a schema that requires handoff_summary, accomplished, remaining, estimated_remaining_effort, resumption_instructions, and blockers fields. Reject any output missing these fields and retry with a stricter schema reminder.

For production reliability, implement a retry policy with a maximum of two attempts. On the first validation failure, append the validation errors to the retry prompt and request a corrected output. If the second attempt also fails, log the raw output and the input state to an observability system, then fall back to a minimal handoff constructed from the structured input alone—this ensures the task is never silently dropped. Store the validated handoff payload in the task's state record with a timestamp and the model version used. When a human reviewer or downstream agent picks up the task, the orchestration layer must load this handoff record and present it as the starting context, not the raw agent trace. Test this flow end-to-end with simulated incomplete tasks across all termination reasons before deploying to production.

Model choice matters here: prefer models with strong instruction-following and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, because the handoff must be reliably parseable. Avoid small or quantized models that may drop required fields or hallucinate completion status. If the handoff will be reviewed by humans in regulated workflows, add a human-review flag to the output schema and route the payload to a review queue before marking the task as handed off. Never allow the agent to retry the original task after producing a handoff unless a human explicitly re-queues it with updated context—otherwise you risk duplicate work and state corruption.