Session Checkpoint and Rollback Prompt Template

This playbook is designed for agent developers managing long-running, multi-step tool workflows where a single failed write operation can corrupt application state. The primary job-to-be-done is creating a recoverable execution boundary around high-risk tool calls—specifically database mutations, filesystem writes, or external API POST/PUT/DELETE operations. You should use this system when your agent orchestrates a sequence of at least three tool calls where a failure in step four would leave steps one through three partially committed, requiring manual intervention to unwind. The ideal user is an AI infrastructure engineer or backend developer who already has access to a session state object, a structured tool call history log, and a serialization mechanism to persist and reload context between turns.

The checkpoint prompt must be invoked immediately before any irreversible or expensive tool call. Irreversible operations include sending emails, charging payment instruments, deleting records, or publishing content. Expensive operations include long-running batch jobs, large file transformations, or calls to rate-limited external APIs where a retry would incur significant cost or delay. The rollback prompt is invoked when the agent's subsequent tool call returns a fatal error, times out, or produces a response that fails output validation. Do not use this system for read-only workflows—a simple retry loop with exponential backoff is cheaper and less complex. Do not use it for single-turn tool calls where the entire interaction is stateless and can be replayed from the initial user input. Do not use it when your tool execution framework already provides ACID transactions or native rollback; layering checkpoint logic on top of atomic operations adds latency without benefit.

Before implementing this prompt, verify that your agent runtime can serialize the full session context—including conversation history, tool call arguments, tool call results, and any intermediate reasoning state—into a structured object that can be stored and retrieved within your latency budget. If serialization takes longer than the tool call itself, the checkpoint overhead may degrade user experience. Also confirm that your rollback mechanism can distinguish between state that should be restored (database records, file contents) and state that should be preserved (audit logs, observability traces). The most common production failure mode is a rollback that restores application state but destroys the evidence needed to debug why the failure occurred. Always preserve the pre-rollback state in an immutable debug log before executing the rollback prompt.

The following templates form a paired contract for session resilience. The first, a Checkpoint Prompt, is injected immediately before a high-risk or irreversible tool call. It instructs the agent to serialize its current reasoning state, pending actions, and the expected outcome of the upcoming call into a structured snapshot. The second, a Rollback Prompt, is triggered when a tool call fails, times out, or returns an unexpected result. It provides the agent with the previously saved checkpoint and instructs it to restore that state, analyze the failure, and decide on a safe next step. Both templates use square-bracket placeholders that your application must populate at runtime.

textCopy
# CHECKPOINT PROMPT
SYSTEM: You are an agent state manager. Your task is to create a precise, restorable snapshot of the current session state before a risky tool call is executed. Do not execute any tools yourself. Output only the structured snapshot.

CURRENT TASK: [CURRENT_TASK_DESCRIPTION]
PRIOR TOOL RESULTS: [PRIOR_TOOL_RESULTS]
PENDING ACTIONS: [PENDING_ACTIONS]
UPCOMING TOOL CALL: [UPCOMING_TOOL_NAME]
UPCOMING TOOL ARGUMENTS: [UPCOMING_TOOL_ARGUMENTS]
EXPECTED OUTCOME ON SUCCESS: [EXPECTED_OUTCOME]
RISK LEVEL: [RISK_LEVEL]

Generate a JSON checkpoint object with the following schema:
{
  "checkpoint_id": "string",
  "timestamp": "ISO8601",
  "prior_state": {
    "completed_actions": ["list of completed action summaries"],
    "key_findings": ["list of critical facts established so far"],
    "active_assumptions": ["list of assumptions the agent is currently operating under"]
  },
  "pending_state": {
    "actions_queued": ["list of actions waiting to execute after this call"],
    "unresolved_questions": ["list of open questions the agent still needs to answer"]
  },
  "tool_call_intent": {
    "tool_name": "string",
    "arguments": {},
    "purpose": "why this call is necessary",
    "expected_result_schema": {}
  },
  "rollback_instructions": "Clear, step-by-step instructions for what the agent should do if this call fails, including alternative tools, fallback data sources, or escalation paths."
}

CONSTRAINTS:
- Include all context required to resume reasoning without the original conversation history.
- If the upcoming tool is destructive (write, delete, send), flag it explicitly in rollback_instructions.
- Do not omit failed assumptions or uncertainty; the rollback agent needs to know what was uncertain.

textCopy
# ROLLBACK PROMPT
SYSTEM: You are an agent recovery manager. A tool call has failed, and you must restore the agent to the last known-good state using the provided checkpoint. Analyze the failure, restore state, and determine the next safe action. Do not re-execute the failed call without explicit approval.

CHECKPOINT: [CHECKPOINT_JSON]
FAILED TOOL CALL: [FAILED_TOOL_NAME]
FAILURE DETAILS: {
  "error_type": "[ERROR_TYPE]",
  "error_message": "[ERROR_MESSAGE]",
  "partial_result": [PARTIAL_RESULT_IF_ANY]
}
CURRENT CONTEXT (POST-FAILURE): [POST_FAILURE_CONTEXT]

Perform the following steps and output a structured recovery plan:
1. **State Restoration**: Restore the agent's working state from the checkpoint's `prior_state` and `pending_state`.
2. **Failure Analysis**: Classify the failure as TRANSIENT, PERMANENT, or UNCLEAR. Explain your classification.
3. **Impact Assessment**: Determine if any partial side effects occurred and whether they need reversal.
4. **Next Action Decision**: Choose one of: RETRY (with modified arguments), FALLBACK (use alternative tool or data source), ESCALATE (request human intervention), or ABORT (terminate the workflow safely).
5. **Recovery Plan**: Output a JSON recovery plan with the following schema:
{
  "restored_state_summary": "string",
  "failure_classification": "TRANSIENT | PERMANENT | UNCLEAR",
  "failure_rationale": "string",
  "partial_side_effects": ["list of any detected side effects"],
  "next_action": "RETRY | FALLBACK | ESCALATE | ABORT",
  "next_action_details": {
    "tool_name": "string or null",
    "modified_arguments": {},
    "fallback_rationale": "string",
    "escalation_message": "string"
  },
  "safety_checks_performed": ["list of safety validations run before recommending next action"]
}

CONSTRAINTS:
- Never recommend re-executing a destructive tool call without human approval.
- If the failure is UNCLEAR, default to ESCALATE.
- Validate that the restored state does not reintroduce stale or invalidated data.

To adapt these templates for your application, replace each square-bracket placeholder with live data from your agent's execution context. The [CHECKPOINT_JSON] placeholder in the Rollback Prompt must receive the exact JSON output from the Checkpoint Prompt—do not summarize or truncate it. For high-risk domains such as finance or healthcare, add a [HUMAN_APPROVAL_REQUIRED] boolean flag to the Rollback Prompt and gate the RETRY and FALLBACK actions behind an explicit approval step in your application harness. Test both prompts with simulated tool failures, including timeouts, malformed responses, and partial writes, to ensure the rollback instructions are specific enough to prevent the agent from hallucinating a recovery path.

A common adaptation mistake is treating the checkpoint as optional logging rather than a mandatory pre-call gate. If your application skips the checkpoint for 'low-risk' calls, you will have no recovery path when those calls fail unexpectedly. Wire the Checkpoint Prompt into your tool-call interceptor so it fires automatically before any call marked with a risk level above a configurable threshold. The Rollback Prompt should be the only path for resuming after a failure—do not allow the agent to continue without explicit state restoration.

The checkpoint and rollback prompts are not standalone; they are control-plane instructions that must be injected into an agent's execution loop at specific decision points. The checkpoint prompt should be invoked immediately before any tool call classified as risky—typically write operations, destructive actions, or calls with side effects that cannot be easily reversed. The rollback prompt is invoked when a subsequent tool call fails, a validator rejects an output, or the agent itself detects an inconsistency in its working state. Both prompts expect a structured state object as input and produce a structured state object as output, which means the harness must maintain a serializable session state that can be passed between prompt invocations without loss of fidelity.

To integrate these prompts into an agent framework, implement a state manager that holds the current working state as a typed object with at least three partitions: checkpoint (the last known-good snapshot), current (the live state being mutated), and pending (proposed changes not yet committed). Before a risky tool call, serialize current into the [CURRENT_STATE] placeholder of the checkpoint prompt, execute the prompt, and store the returned checkpoint_id and state_snapshot in the checkpoint partition. After the tool call completes, run a validation step: compare the tool's actual output against the expected schema, check for error codes, and verify that side effects match intent. If validation passes, promote pending to current and clear the checkpoint. If validation fails, load the rollback prompt with [CHECKPOINT_STATE] set to the stored snapshot and [FAILURE_CONTEXT] containing the error details, tool response, and any partial state mutations. The rollback prompt returns a restored_state that replaces current, and the harness should log the rollback event with the checkpoint ID for auditability.

For production reliability, implement a retry wrapper around the rollback path: if the rollback prompt itself fails or produces a state that fails schema validation, escalate to a human operator with the full checkpoint snapshot and failure trace. Never silently discard a failed rollback. Additionally, set a maximum checkpoint age—if a checkpoint is older than a configurable TTL (e.g., 5 minutes or 10 tool calls), evict it and force a fresh checkpoint before the next risky operation. This prevents the agent from rolling back to a state so stale that the user's intent or external system state has diverged. Wire both prompts into your observability stack: log every checkpoint creation, rollback invocation, and state reconciliation attempt with trace IDs that link the checkpoint, the triggering tool call, and the rollback outcome. This traceability is essential for debugging multi-step agent failures and for compliance reviews in regulated workflows.