AI Agent State Management: Checkpoints, Replay, and Recovery

Four state layers need different rules

The OpenAI Agents SDK sessions documentation describes built-in session memory for conversation history across runs. That is useful context management, but it should not replace a workflow checkpoint or an application's system of record. The documentation also warns against layering incompatible continuation mechanisms in the same run; choose one owned history path.

A checkpoint is a transition record, not a transcript dump

A useful checkpoint names the run, current state, triggering event, validated inputs, produced artifact references, external effects, approval status, retry count, next allowed states, and version of the workflow contract. Store content by reference when possible. Raw prompts and retrieved documents can contain sensitive or adversarial text, so do not duplicate them into every state row.

Make transitions compare-and-set operations. A worker should advance from one expected version to the next or discover that another worker already did. Give each external mutation an idempotency key derived from the run and logical action. When a timeout leaves the result unknown, query the system of record before retrying.

OpenTelemetry's semantic conventions provide common names for observable operations, while its trace model connects spans across a workflow. A trace helps explain a run; it is not the durable state machine itself. Keep trace identifiers in checkpoints so operators can move between control state and diagnostics.

Design replay and recovery before adding memory

Replay should reconstruct decisions from versioned inputs without repeating already committed side effects. Separate pure computation from effects, retain artifact hashes or identifiers, and record the versions of model, prompt, tool schema, policy, and workflow. If old code cannot interpret a pending checkpoint, route it through a migration or explicit manual review rather than guessing.

Recovery paths should include resume after process loss, duplicate event delivery, partial write, tool timeout, rejected approval, stale lock, and unavailable dependency. A resumed run must keep the original authority envelope. It cannot gain tools or permissions merely because a newer release has them. Use approval state as a first-class transition, not a chat message that can be rephrased.

Long-term memory is last, not first. Before writing it, ask whether the information is necessary, sourced, non-sensitive, scoped to the right user or tenant, and likely to reduce future work. The established guide to how agents use memory explains the contextual role; workflow correctness still comes from explicit state.

State failure cases

• Transcript as database: the agent infers that a tool succeeded from its prior narration. Read the owned record and persist the observed result.
• Checkpoint before validation: malformed output advances the phase. Validate schema and invariants before the atomic transition.
• Retry after an unknown write: a timeout causes a duplicate payment, message, or record. Use idempotency and post-timeout readback.
• Cross-user context: one conversation record is reused for different people. Bind every record to a verified owner and tenant.
• Stale context: old or contradictory facts influence a new task. Define when context is reviewed, replaced, or discarded.
• Resume under new authority: a pending run inherits broader tools after deployment. Persist and enforce the original authority envelope.
• Trace equals truth: asynchronous telemetry is mistaken for committed state. Treat traces as evidence, not the transaction ledger.

A recoverable state implementation sequence

1. Define the state machine. List states, allowed events, transition predicates, terminal outcomes, and blocked conditions. Keep model text outside transition names.
2. Choose the systems of record. Name where business facts, workflow checkpoints, conversation context, and trace evidence live. Assign ownership and lifecycle separately.
3. Design the checkpoint schema. Include run and tenant IDs, state version, workflow version, artifact references, approvals, budgets, retries, effects, and trace ID.
4. Make transitions atomic. Use optimistic concurrency or a transaction so duplicate workers cannot both advance. Validate output and authorization before committing.
5. Make effects idempotent. Attach stable keys, record intent and result, and read back uncertain operations. Never rely on the model to remember whether a call executed.
6. Exercise recovery. Crash after each transition boundary, redeliver events, expire locks, reject approvals, and change code versions. Confirm one safe terminal state.
7. Evaluate and observe. Connect checkpoints to traces and regression cases using the AI agent evaluation checklist and LLM observability metrics.

Decision summary

Store only the state required to resume, replay, audit, or recover a transition. Keep checkpoints separate from conversational memory, make side effects idempotent, and prove recovery on interrupted fixtures before treating persistence as a reliability feature.