Checkpoint Frequency Decision Prompt

This prompt is designed for agent orchestrators and workflow engines that need to make a deliberate, step-by-step decision about when to save agent state. It is not a generic save-everything instruction. Use it when your agent executes a multi-step plan where some steps are expensive, irreversible, or operate on external mutable resources. The prompt forces the model to weigh the cost of replaying a step against the overhead of saving state, considering context window pressure, step risk, and reversibility. This is a planning-time prompt, called before or during execution, not a post-hoc analysis tool. It belongs inside the agent's planning loop, typically after a plan is generated but before execution begins, or at the start of each step when dynamic replanning is active.

The ideal user is an AI engineer or technical decision maker building an agent harness that manages long-running, stateful workflows. You should use this prompt when your agent operates on resources that cannot be safely replayed—such as sending emails, modifying production databases, or making financial transactions—and when the token cost of full replays exceeds the cost of checkpointing. It is also appropriate when context windows are under pressure and you need a principled way to decide what to keep in active memory versus what to offload to a checkpoint. Do not use this prompt for stateless, single-turn tasks, or for agents whose steps are all idempotent and cheap to replay. In those cases, the decision overhead of the prompt itself wastes tokens and adds latency without reducing risk.

Before wiring this prompt into your agent loop, ensure you have defined the cost and risk profile of each tool or step type your agent can execute. The prompt's placeholders for [STEP_DESCRIPTIONS], [TOOL_RISK_LEVELS], and [REPLAY_COST_ESTIMATES] require concrete, per-step metadata. If you cannot estimate replay cost or risk for a step, the model will default to conservative over-saving, which defeats the purpose. Pair this prompt with a state snapshot mechanism (see Agent State Snapshot Prompt Template) and a resumption protocol (see Interruption-Resume Prompt for Multi-Session Agents) so that checkpoint decisions translate directly into saved state that can be reloaded. In high-risk domains such as finance or healthcare, always route the checkpoint schedule through a human approval step before execution begins, and log every checkpoint decision with its rationale for auditability.

This template is designed to be pasted into your agent's planning module. It instructs the model to act as a checkpoint controller, evaluating the current execution context and producing a decision on whether to save state now, defer, or skip. The prompt forces the model to weigh risk, cost, and context pressure before committing to a checkpoint, preventing both wasteful over-saving and dangerous under-saving.

textCopy
You are a Checkpoint Controller for an autonomous agent execution runtime. Your job is to decide whether to save the agent's full state at the current execution step. Do not execute the step. Only decide on checkpointing.

## Current Execution Context
- Active Plan: [ACTIVE_PLAN_SUMMARY]
- Completed Steps: [COMPLETED_STEPS]
- Current Step: [CURRENT_STEP_DESCRIPTION]
- Current Step Risk Level: [RISK_LEVEL] // Must be one of: LOW, MEDIUM, HIGH, CRITICAL
- Current Step Reversibility: [REVERSIBILITY] // Must be one of: FULLY_REVERSIBLE, PARTIALLY_REVERSIBLE, IRREVERSIBLE
- Estimated Cost of Replay from Last Checkpoint: [REPLAY_COST] // In tokens or dollars
- Context Window Usage: [CONTEXT_USAGE_PERCENT]%
- Time Since Last Checkpoint: [STEPS_SINCE_CHECKPOINT] steps
- Tool Call Required: [TOOL_NAME]
- Tool Call Expected Side Effects: [SIDE_EFFECTS_DESCRIPTION]

## Decision Rules
1. If RISK_LEVEL is CRITICAL or HIGH and REVERSIBILITY is IRREVERSIBLE, you MUST checkpoint.
2. If CONTEXT_USAGE_PERCENT > 85, you MUST checkpoint to prevent overflow.
3. If REPLAY_COST is high and STEPS_SINCE_CHECKPOINT > [MAX_STEPS_BEFORE_CHECKPOINT], you SHOULD checkpoint.
4. If RISK_LEVEL is LOW and REVERSIBILITY is FULLY_REVERSIBLE and CONTEXT_USAGE_PERCENT < 70, you MAY skip.
5. If the tool call has external side effects (e.g., sending an email, modifying a database), you SHOULD checkpoint.

## Output Schema
Respond with a single JSON object:
{
  "decision": "CHECKPOINT_NOW" | "DEFER" | "SKIP",
  "reasoning": "A concise explanation referencing the specific decision rules and context values that led to this decision.",
  "checkpoint_label": "A short, human-readable label for this checkpoint if decision is CHECKPOINT_NOW, e.g., 'pre-db-write' or 'post-approval-gate'.",
  "urgency": "IMMEDIATE" | "STANDARD" | "LOW"
}

To adapt this template, replace every square-bracket placeholder with runtime values from your agent's execution loop. The [RISK_LEVEL] and [REVERSIBILITY] fields should be populated by a prior risk-assessment step, not by this prompt. The [MAX_STEPS_BEFORE_CHECKPOINT] is a tunable constant you should set based on your tolerance for replay cost. After receiving the model's JSON response, validate that the decision field matches one of the three allowed strings before acting on it. For high-risk workflows, log every decision and its reasoning for auditability.

The checkpoint frequency decision prompt is designed to be called by an orchestrator's planning or monitoring module, not directly by an end user. It should be invoked before a new execution phase begins, after a significant tool failure, or when context window pressure exceeds a configured threshold (e.g., 70% utilization). The orchestrator must provide the current plan, completed steps with their outcomes, available tool schemas, and a cost model that includes estimated token costs for replaying each step. The prompt's output is a structured checkpoint schedule that the orchestrator parses and enforces, not advisory text for a human operator.

To integrate this prompt, wrap it in a thin service function that assembles the required inputs, calls the model with response_format set to the defined JSON schema, and validates the output before acting on it. The validation layer must confirm that every step_id in the schedule exists in the current plan, that checkpoint_after_step values are boolean, and that the rationale field is non-empty. If validation fails, retry once with the validation errors appended to the prompt as additional context. Log every checkpoint decision—including the full schedule, the model used, token counts, and validation results—to your observability platform. This log becomes the audit trail for debugging over-saving (wasted storage and latency) or under-saving (costly replays after failure). For high-stakes workflows where replay cost is measured in dollars or irreversible side effects, route schedules with risk_level: high and checkpoint_after_step: false to a human reviewer before execution proceeds.

Model choice matters here. The prompt requires structured reasoning about trade-offs, not just pattern matching. Use a model with strong JSON mode and instruction-following, such as gpt-4o or claude-3-5-sonnet. Avoid smaller, faster models for this decision point unless you've validated their schedule quality against a golden dataset of known-good checkpoint plans. If your orchestrator uses tool-calling, expose a set_checkpoint_schedule tool that accepts the validated schedule object and enforces it in the execution loop. Do not let the agent decide checkpoint timing autonomously at each step; that leads to inconsistent state and makes debugging replay failures nearly impossible. The prompt's job is to produce the policy; the orchestrator's job is to enforce it.