Agent State Checkpoint Prompt for Handoff Recovery

This prompt is for platform engineers and SREs building fault-tolerant multi-agent systems. Its job is to produce a machine-readable checkpoint snapshot immediately before a handoff between specialized sub-agents. The checkpoint captures the current agent's state, in-progress work, pending decisions, active constraints, and tool call results so that if the handoff fails, times out, or the receiving agent rejects the transfer, the orchestrator can roll back to this snapshot and retry without losing work or duplicating side effects. Use this prompt when your system requires idempotent handoff recovery, when agent pipelines span multiple steps with non-trivial state, or when you need an audit trail of what was in flight at the moment of transfer.

The ideal user is an engineer who already has an orchestrator dispatching work to sub-agents and needs a reliable recovery primitive. You should have a defined handoff protocol, a registry of agent capabilities, and a mechanism for serializing and restoring state. The checkpoint prompt works best when paired with a handoff failure recovery prompt that consumes the snapshot and decides whether to retry, escalate, or abort. Before using this prompt, ensure you have instrumented your orchestrator to detect handoff failures—timeouts, schema validation errors on the handoff payload, explicit rejection signals from the receiving agent, or missing acknowledgment within a deadline. Without this detection, the checkpoint is generated but never used.

Do not use this prompt for simple stateless routing decisions where no recovery is needed, or for single-agent workflows without handoffs. If your handoff payload is a single sentence and the receiving agent is stateless, the overhead of checkpoint generation adds latency without benefit. Also avoid this prompt when the sending agent's state is too large to serialize within your context budget—in that case, use a handoff context pruning prompt first to reduce the footprint, then checkpoint the pruned state. Finally, this prompt is not a substitute for idempotent tool design. If your sub-agents perform non-idempotent side effects (sending emails, creating database records without deduplication keys), a checkpoint alone cannot prevent duplicate actions on retry. You must design idempotency into your tool layer in addition to using this checkpoint prompt.

This prompt template is designed to be injected into your orchestrator's pre-handoff hook. It instructs the current agent to produce a structured checkpoint snapshot that includes its identity, task progress, active constraints, tool outputs, and any unresolved decisions. The resulting payload serves as the single source of truth for recovery: if the downstream agent fails to acknowledge the handoff, times out, or returns an error, the orchestrator can use this checkpoint to roll back state and retry without duplicating work or losing context.

textCopy
You are producing a handoff checkpoint before transferring control to another agent. Your checkpoint must be a self-contained, machine-readable snapshot that allows the system to recover state if the handoff fails.

Generate a JSON object with the following structure:

{
  "checkpoint_id": "string, unique identifier for this checkpoint",
  "agent_role": "string, your assigned role name from [ROLE_REGISTRY]",
  "agent_instance_id": "string, your instance identifier",
  "timestamp": "ISO-8601 UTC timestamp",
  "task_id": "string, the task you are working on from [TASK_QUEUE]",
  "task_status": "one of: in_progress | blocked | awaiting_approval | completed",
  "completed_steps": [
    {
      "step_id": "string",
      "description": "string, what was accomplished",
      "output_reference": "string, pointer to result or artifact",
      "completed_at": "ISO-8601"
    }
  ],
  "in_progress_step": {
    "step_id": "string or null",
    "description": "string, what is currently being worked on",
    "partial_output": "string or null, any intermediate result",
    "started_at": "ISO-8601 or null"
  },
  "pending_decisions": [
    {
      "decision_id": "string",
      "question": "string, what needs to be decided",
      "options": ["string array of possible choices"],
      "recommendation": "string or null, your suggested choice with reasoning",
      "blocking": true or false
    }
  ],
  "active_constraints": [
    "string array of constraints from [POLICY_LAYER] that are currently active"
  ],
  "tool_outputs": [
    {
      "tool_name": "string",
      "call_id": "string",
      "result_summary": "string, condensed output",
      "full_result_reference": "string, pointer to complete output"
    }
  ],
  "context_snapshot": {
    "key_facts": ["string array of critical facts established so far"],
    "user_intent": "string, the user's original request",
    "session_highlights": ["string array of important turns or clarifications"]
  },
  "handoff_target": {
    "target_role": "string, the role this checkpoint is intended for",
    "handoff_reason": "string, why the transfer is happening",
    "expected_return": true or false
  },
  "recovery_instructions": {
    "idempotency_key": "string, used to prevent duplicate execution on retry",
    "rollback_notes": "string, what to undo or skip if this checkpoint is replayed",
    "max_retries": 3
  },
  "consistency_hash": "string, hash of critical fields for integrity verification"
}

RULES:
- Include only information that the receiving agent needs. Omit stale context, resolved decisions, and role-irrelevant data.
- Mark any field as null if it does not apply. Do not invent values.
- The consistency_hash must cover checkpoint_id, task_id, task_status, completed_steps, and pending_decisions using SHA-256.
- If [RISK_LEVEL] is "high", add a human_approval_required boolean and an approval_ticket_reference field.
- Keep the context_snapshot under [MAX_CONTEXT_TOKENS] tokens. Prune aggressively.
- Do not include raw tool outputs in full_result_reference; use pointers to external storage.

Before deploying this template, wire the orchestrator to validate the checkpoint JSON against the schema above. Reject any checkpoint where consistency_hash does not match the computed hash of the covered fields—this catches silent corruption during serialization. Store the checkpoint in an append-only log keyed by checkpoint_id so recovery logic can replay from the last valid snapshot. If the handoff target fails to acknowledge within [HANDOFF_TIMEOUT_SECONDS], the orchestrator should reload this checkpoint, increment a retry counter, and either re-attempt the handoff or escalate to a fallback agent. For high-risk workflows, require a human to approve the checkpoint before the handoff proceeds; the human_approval_required flag gates this path.

The checkpoint prompt is not a standalone utility; it is a recovery primitive that must be embedded inside the handoff orchestration layer. Before any agent-to-agent transfer, the orchestrator calls this prompt with the current agent's full context, in-progress task graph, and pending decisions. The resulting checkpoint snapshot is stored in a durable, versioned state store (such as a database row, a blob in object storage, or a transactional outbox) keyed by session ID and handoff sequence number. The checkpoint must be written before the handoff request is dispatched to the receiving agent. If the handoff succeeds, the checkpoint can be marked as resolved; if the handoff times out, returns an error, or the receiving agent crashes, the orchestrator uses the checkpoint to roll back state and retry with the same or a fallback agent.

Implementation requires several concrete integration points. Checkpoint ID and sequence numbering: assign a monotonically increasing handoff_sequence and a UUID checkpoint_id to each snapshot so the system can distinguish between the initial handoff attempt and subsequent retries. Atomic write-before-dispatch: use a transactional pattern—write the checkpoint to the state store, confirm the write, then dispatch the handoff. If the write fails, abort the handoff and escalate. Validation before storage: run the checkpoint output through a schema validator that confirms required fields (agent_id, session_id, task_state, pending_decisions, active_constraints, context_fingerprint) are present and non-empty. Reject malformed checkpoints and log the failure before the handoff proceeds. Context fingerprinting: include a hash of the serialized context in the checkpoint so the recovery path can detect if context was corrupted or truncated during storage. Retry with idempotency: when recovering from a failed handoff, the orchestrator must pass the checkpoint's handoff_sequence to the receiving agent so it can detect and ignore duplicate work from a partially completed prior attempt.

Model choice matters for checkpoint fidelity. Use a model with strong instruction-following and structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) because the checkpoint must reliably extract state without hallucinating completed work or omitting unresolved decisions. Set temperature=0 or very low to maximize deterministic extraction. For latency-sensitive pipelines, consider a smaller, fine-tuned model that has been trained on your specific state schema, but validate its extraction accuracy against the general-purpose model before cutting over. Logging and observability: emit structured logs containing the checkpoint_id, handoff_sequence, agent_id, token count of the checkpoint, validation status, and storage latency. These logs are essential for debugging handoff failures and for answering the question 'what did the system believe was true at the point of handoff?' during post-incident review.

Human review integration is required when the checkpoint prompt's consistency verification flags a problem. If the prompt's output includes consistency_issues with severity high (for example, contradictory task states, missing required constraints, or a context fingerprint mismatch), the orchestrator should not proceed with the handoff automatically. Instead, route the checkpoint to a review queue where an operator can inspect the snapshot, resolve the inconsistency, and either approve the handoff or abort and restart the task. For lower-severity issues, the system can proceed but must attach the consistency warnings to the handoff payload so the receiving agent is aware of potential state uncertainty.

What to avoid: do not treat the checkpoint as a full context dump. The prompt is explicitly designed to produce a minimal footprint snapshot, and the orchestrator should respect that by not appending raw conversation history or tool outputs to the checkpoint payload. Store the full context separately if needed for debugging, but keep the checkpoint lean to control token costs during recovery. Do not skip the write-before-dispatch atomicity—a handoff that proceeds without a confirmed checkpoint is a handoff that cannot be recovered. Finally, do not assume the checkpoint is immutable after storage; if the receiving agent modifies state and then fails, the next recovery attempt must use the original checkpoint, not the partially mutated state.