Graceful Shutdown and State Save Prompt

This prompt is for agent runtime developers and operators who need a reliable mechanism to save agent state and shut down cleanly when an external signal, timeout, or resource exhaustion event occurs. The primary job is to produce a shutdown checkpoint that captures in-flight task status, resource cleanup notes, and a priority-ordered resumption queue so that execution can resume later without losing work or replaying expensive steps. The ideal user is an engineering lead or AI infrastructure developer building autonomous agent systems that run for extended periods, consume billable resources, or operate in environments where interruptions are expected—such as cloud spot instances, CI/CD pipelines with timeouts, or human-in-the-loop workflows with approval gates.

Use this prompt when your agent runtime must respond to a shutdown signal by saving state before the process terminates. This includes scenarios where the agent receives a SIGTERM, hits a context-window limit, exhausts a token budget, or encounters a resource quota. The prompt expects structured input describing the current plan, completed steps, in-progress tasks, tool outputs, and any pending human decisions. It is designed for agents that already maintain an execution plan and track step-level progress—if your agent lacks these primitives, you need the Agent State Snapshot Prompt Template first to establish baseline state serialization. Do not use this prompt for routine checkpointing during normal execution; the Checkpoint Frequency Decision Prompt handles that scheduling concern. Do not use it when the agent has already crashed or lost state—the Agent Context Reconstruction Prompt After Failure addresses post-crash recovery.

This prompt is not a replacement for application-level signal handling or process supervision. Your runtime must catch the shutdown signal, invoke the prompt with current state, persist the output, and then terminate. The prompt assumes the model has access to the full execution context at shutdown time; if context has already been truncated, pair this with the Context Window Overflow Recovery Prompt before invoking shutdown. For high-risk domains where in-flight task loss could cause financial, safety, or compliance damage, always log the shutdown checkpoint to an append-only audit store and require human review before resumption. The next section provides the copy-ready template you can adapt to your agent's state schema and shutdown triggers.

This template is designed to be copied directly into your agent's shutdown handler. It instructs the model to produce a structured checkpoint when a shutdown signal, timeout, or resource-exhaustion threshold is triggered. The prompt forces the agent to account for in-flight tasks, note any resources that require cleanup, and build an explicit resumption queue so the next session can pick up execution without replaying completed work. Use it as the core instruction block inside a broader system prompt or as a standalone message dispatched by your orchestration layer when a preemption event fires.

textCopy
You are an agent that must perform a graceful shutdown and save your complete execution state.

Your current context:
[CURRENT_PLAN]
[COMPLETED_STEPS]
[IN_FLIGHT_TASKS]
[TOOL_OUTPUTS]
[RESOURCE_STATE]

Shutdown trigger: [SHUTDOWN_REASON]
Time available before forced termination: [TIME_BUDGET_SECONDS] seconds.

Produce a shutdown checkpoint using the exact schema below. Do not start any new tasks. Do not make any tool calls.

[OUTPUT_SCHEMA]

Constraints:
[CONSTRAINTS]

Examples of valid checkpoints:
[EXAMPLES]

Risk level for this workflow: [RISK_LEVEL]

Adapt this template by replacing each square-bracket placeholder with concrete values from your agent runtime. [CURRENT_PLAN] should contain the full plan object, including dependencies and statuses. [IN_FLIGHT_TASKS] must list every task that has started but not yet been confirmed complete—this is the highest-risk data for resumption. [TIME_BUDGET_SECONDS] lets you bound how long the model spends on the shutdown prompt itself; set this based on your infrastructure's grace period. If your agent uses tools, include [TOOLS] with their current availability status so the resuming agent can detect tool-level changes. For high-risk workflows, add a [HUMAN_REVIEW_FLAG] constraint that marks the checkpoint as requiring operator approval before resumption. Always validate the output against [OUTPUT_SCHEMA] before persisting the checkpoint to storage.

This prompt is not a standalone chat interaction—it is a runtime safeguard that must be triggered by the agent harness, not by the model's own initiative. The harness should invoke this prompt when it receives an OS signal (SIGTERM, SIGINT), when a configurable execution timeout is reached, or when resource monitors detect memory/CPU exhaustion. The prompt expects a structured snapshot of the agent's current state as input, including the active plan, completed steps, in-flight tool calls, and any partial outputs. The harness is responsible for assembling this context and injecting it into the [AGENT_STATE] placeholder before the model call.

Wiring pattern: Register a shutdown hook in your agent runtime that (1) sets a shutting_down flag to block new tool dispatches, (2) waits for in-flight tool calls to complete or times them out individually (recommended: 5-second per-call grace period), (3) serializes the current plan state, tool outputs, and pending decisions into a structured object, (4) calls the model with this prompt and the serialized state, and (5) persists the model's JSON output to durable storage (S3, database, or local disk with fsync) before exiting. The model call itself should have a separate timeout (e.g., 10 seconds) to prevent the shutdown sequence from hanging indefinitely. If the model call fails, the harness must fall back to saving the raw serialized state as a best-effort checkpoint and log the failure for operator review.

Validation before persistence: The harness must validate the model's output against the expected schema before writing it to storage. At minimum, confirm that resumption_queue is a non-empty array, that each item has a priority field, and that in_flight_task_handling contains explicit dispositions (retry, discard, await-human) for every task that was in flight. If validation fails, retry once with a stripped-down prompt that asks only for the resumption queue. If that also fails, save the raw state and emit a critical alert—do not silently persist an invalid checkpoint. For high-risk workflows (healthcare, finance, infrastructure), route the checkpoint to a human review queue before marking it as the authoritative resumption state. The checkpoint should include a timestamp, agent session ID, and a hash of the pre-shutdown state for audit trail integrity.

Storage and resumption contract: Persist the checkpoint with a well-known key pattern (e.g., checkpoints/{session_id}/{timestamp}.json) and update a pointer to the latest valid checkpoint atomically. When the agent runtime restarts, it must check for an existing checkpoint before initializing a new session. If a checkpoint exists, load it, validate schema integrity, and pass the resumption_queue to the agent's planning module. Do not assume the checkpoint is valid just because it exists—run the Resume-from-Checkpoint Validation Prompt (sibling playbook) before executing any resumed tasks. If the checkpoint is corrupted or references tools that are no longer available, fall back to a human operator or a safe re-initialization path rather than silently skipping or hallucinating state.

What to avoid: Do not call this prompt inside the agent's normal reasoning loop—it is a shutdown path only. Do not rely on the model to decide when to save state; the harness owns checkpoint timing. Do not skip validation because 'the shutdown was clean'—corrupted checkpoints are most common during resource exhaustion, which is exactly when this prompt is triggered. Finally, test shutdown-and-resume end-to-end in your CI pipeline with injected signals, forced timeouts, and simulated partial tool failures. A checkpoint that saves successfully but cannot be resumed is worse than no checkpoint at all because it creates a false sense of safety.