Multi-Agent Handoff State Preservation Prompt

This prompt is designed for multi-agent orchestrators and framework developers who need a reliable, machine-readable handoff package when transferring work from one specialized agent to another. Use it when a generalist agent completes its scoped work and must pass partial results, open questions, and unresolved dependencies to a downstream specialist agent. The prompt produces a structured JSON payload that the receiving agent can consume without replaying the entire execution history.

Do not use this prompt for single-agent checkpointing, human-readable summaries, or cross-session resumption. Those scenarios require different state serialization patterns covered in sibling playbooks such as Agent State Snapshot or Human-in-the-Loop Handoff State. Using this prompt for human review will produce overly verbose, machine-optimized payloads that obscure decision rationale. Using it for intra-agent checkpointing will include unnecessary handoff metadata that bloats context windows without adding resumption value.

Before implementing this prompt, confirm that your system has at least two distinct agent roles with separate system prompts, tool sets, or authority boundaries. If a single agent can complete the entire workflow, use a checkpointing prompt instead. If the handoff requires human approval before the specialist agent proceeds, combine this prompt with the Human-in-the-Loop Handoff State prompt to produce both the machine-readable payload and a reviewer-ready summary. Always validate the handoff payload against the receiving agent's expected schema before passing control.

The following prompt template is designed to be injected into your orchestrator agent's handoff instruction. It forces the originating agent to serialize its execution context into a structured package before transferring control. This prevents the common failure mode where a downstream agent receives only a vague task description and must re-discover context that was already established, leading to duplicated work, contradictory actions, and wasted tokens. Replace every square-bracket placeholder with live state from your agent runtime at the moment of handoff.

textCopy
You are handing off execution to a specialized agent. Before transferring control, produce a complete handoff package using the structure below. Do not omit any section. If a section has no applicable content, explicitly state that it is empty and why.

## Handoff Package

### 1. Task State
- **Original Objective:** [ORIGINAL_OBJECTIVE]
- **Current Phase:** [CURRENT_PHASE]
- **Completed Steps (with evidence):**
  - [STEP_ID]: [OUTCOME] | Evidence: [EVIDENCE_REFERENCE]
- **In-Progress Step:** [STEP_ID] | Status: [STATUS] | Partial Output: [PARTIAL_OUTPUT]
- **Remaining Steps:** [REMAINING_STEP_LIST]

### 2. Relevant History
- **Key Decisions Made:**
  - [DECISION] | Rationale: [RATIONALE] | Made at step: [STEP_ID]
- **Errors Encountered and Resolutions:**
  - [ERROR] | Resolution: [RESOLUTION] | Step: [STEP_ID]
- **User Clarifications Received:**
  - [QUESTION] -> [ANSWER] | Step: [STEP_ID]

### 3. Unresolved Dependencies
- **Blocked Steps:** [STEP_ID] | Blocker: [BLOCKER_DESCRIPTION]
- **Pending Approvals:** [APPROVAL_ITEM] | Required from: [APPROVER_ROLE]
- **Missing Information:** [INFORMATION_GAP] | Needed for step: [STEP_ID]
- **Assumptions Awaiting Validation:** [ASSUMPTION] | Confidence: [LOW/MEDIUM/HIGH]

### 4. Authority Boundaries
- **Actions This Agent Is Authorized to Take:** [AUTHORIZED_ACTIONS]
- **Actions Requiring Escalation:** [ESCALATION_ACTIONS]
- **Hard Constraints:** [CONSTRAINTS]
- **Risk Level of Remaining Work:** [RISK_LEVEL]

### 5. Context References
- **Tool Outputs to Preserve:** [TOOL_OUTPUT_REFERENCES]
- **Source Documents:** [DOCUMENT_REFERENCES]
- **Checkpoint ID for Rollback:** [CHECKPOINT_ID]

### 6. Handoff Instructions
- **Why This Handoff Is Occurring:** [HANDOFF_REASON]
- **Expected Output from Downstream Agent:** [EXPECTED_OUTPUT_SCHEMA]
- **Return Handoff Required:** [YES/NO] | Condition: [RETURN_CONDITION]
- **Do Not Duplicate These Steps:** [COMPLETED_STEP_IDS]

Adapt this template by removing sections irrelevant to your agent architecture, but never remove the Unresolved Dependencies or Authority Boundaries sections—these are the most common sources of multi-agent failure. If your orchestrator uses structured tool calls rather than free-text handoffs, convert each section into a typed JSON schema with required fields and enum constraints. For high-risk domains, add a Human Review Required boolean field that gates the handoff until a human operator confirms the package is complete. Test the template by simulating a mid-execution handoff and verifying that the downstream agent can resume without asking any question already answered in the handoff package.

Before deploying this prompt into a production multi-agent system, build an eval that measures context sufficiency: give the handoff package to a fresh agent instance and measure whether it attempts to re-execute completed steps or re-request information already present. A passing eval requires zero duplicate work and zero redundant clarification requests. Also test the failure mode where the originating agent produces an incomplete handoff—your orchestrator should reject the handoff and request regeneration rather than forwarding a partial package to the downstream agent.

The handoff prompt is not a standalone artifact; it is a contract between two agents inside an orchestration runtime. The orchestrator (or the handing-off agent itself) calls this prompt immediately before transferring control. The output is a structured handoff package that the receiving agent consumes as its initial context. To make this reliable in production, the harness must enforce schema compliance, validate context sufficiency, and provide a fallback path when the handoff package is incomplete or the receiving agent rejects it.

Start by wrapping the prompt call in a function that accepts the current agent's state, task history, and the target agent's capability description. The function should construct the prompt with the required placeholders: [CURRENT_AGENT_STATE], [TASK_HISTORY], [UNRESOLVED_DEPENDENCIES], [TARGET_AGENT_CAPABILITIES], and [AUTHORITY_BOUNDARIES]. After receiving the model response, validate the output against a strict JSON schema that includes required fields: task_state, relevant_history, unresolved_dependencies, authority_boundaries, and handoff_rationale. If validation fails, retry once with the validation errors injected into the prompt as [PREVIOUS_ERRORS]. If the second attempt fails, log the failure and escalate to a human operator or a fallback summarization agent.

For multi-agent systems using tool-calling models, the handoff package should be treated as a tool response that the receiving agent processes before its first action. Implement a receive_handoff tool that the receiving agent must call before any other tool. This tool parses the handoff JSON, loads it into the agent's working memory, and returns a confirmation that includes a checksum of the state. The orchestrator should compare this checksum against the original to detect silent corruption. Log every handoff event with a unique handoff_id, the sending agent, receiving agent, timestamp, schema validation result, and the receiving agent's confirmation checksum. This audit trail is essential for debugging duplicate work, dropped context, and authority boundary violations.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities for the handoff prompt. If the handoff involves sensitive data or high-risk actions, route the prompt through a model with lower latency but higher reliability for schema adherence, and consider adding a lightweight validation model that checks the handoff package for completeness before the receiving agent consumes it. For long-running workflows, store the handoff package in a persistent state store keyed by handoff_id so the orchestrator can replay or audit the transition later.

Avoid wiring this prompt directly into the agent's main execution loop without the validation and retry wrapper. A malformed handoff package that reaches the receiving agent can cause cascading failures, repeated work, or silent context loss that is expensive to detect and repair. The harness should also enforce a timeout on the handoff prompt call itself—if the model takes too long to generate the package, fall back to a simpler state summary and flag the handoff for human review. The goal is to make handoffs boring, auditable, and recoverable, not to optimize for the happy path alone.