AI Agent State Snapshots: Resume Long Jobs Without Repeating Side Effects

An agent spends 40 minutes researching vendors, creates a purchase order, and crashes before writing its final message. On restart, the transcript says what it intended to do—but not whether the external action committed. Replaying the conversation could create a second order.

State snapshots give long-running agents a durable recovery point. They capture execution state, not just words, so the system can distinguish completed work from work that is safe to retry.

Snapshot the state machine, not only the transcript

A useful snapshot records the current step, plan version, structured working state, completed tool calls, pending approvals, deadlines, model and prompt versions, and the identifiers needed to look up external effects.

Store tool inputs as redacted references when they contain secrets. Preserve immutable result digests and external object IDs. The transcript can remain available for context, but it should not be the authoritative ledger of whether an action happened.

Use a monotonic snapshot sequence and optimistic concurrency. A worker should write snapshot 42 only if snapshot 41 is still current. This prevents two recovering workers from advancing the same job independently.

Separate resumable state from ephemeral detail. Full token streams, temporary UI hints, and large retrieved documents may be reconstructed or stored by reference. The snapshot should be compact enough to write after meaningful transitions.

Draw a commit boundary around every side effect

The hardest moment is between calling an external API and recording its success. A crash can happen after the remote system commits but before the agent stores the result.

Use idempotency keys derived from the job and logical action. On recovery, retry with the same key or query the external system by that identifier. If the provider offers neither idempotency nor lookup, classify the action as ambiguous and require reconciliation instead of automatic replay.

Model each action with states such as prepared, dispatched, confirmed, and reconciled. Persist prepared before sending. Persist the external ID immediately after a confirmed response. Never treat a missing response as proof that nothing happened.

Approvals need the same discipline. Save exactly what was approved, its scope, and an expiry. A later prompt revision must not silently expand old authorization.

Resume with deterministic orchestration and flexible reasoning

The workflow engine should decide which step is eligible to run. The model can decide how to perform that step within policy. If the model alone infers position from a long transcript, small wording changes can produce duplicate or skipped work.

Pin the workflow definition and schema version to the snapshot. When code changes, migrate stored state explicitly or finish old jobs on a compatible worker. Validate snapshot data before injecting it into a model prompt; persisted content can still contain untrusted instructions.

After recovery, recheck time-sensitive assumptions. A saved flight price, inventory count, or access token may have expired even though the research step is complete. Durability preserves facts about execution, not the freshness of the outside world.

Test crashes as first-class inputs

Inject failures before dispatch, after dispatch, after remote commit, during snapshot writes, and while two workers compete for a lease. Assert that each logical side effect occurs at most once and that ambiguous states become visible.

Track resume count, snapshot age, replayed pure steps, reconciled actions, ambiguous effects, migration failures, and time from restart to progress. Encrypt stored state and apply retention limits because snapshots can contain a concentrated history of user intent.

A durable agent is not one that never fails. It is one that can explain where it stopped, prove what already happened, and continue without making the user pay for the same action twice.