12 — State Persistence

Concept overview

State persistence records an agent execution beyond the lifetime of a process or conversation connection. Useful state includes the current workflow position, validated observations, artifact references, pending operations, budgets, and version information. A conversation transcript alone rarely contains enough information to restart safely after a tool call or concurrent update.

Separate authoritative workflow state from disposable caches and long-term user memory. Checkpoints describe what the runtime knows, while business systems describe which external effects actually occurred. Recovery must reconcile these views rather than assume that replaying a saved prompt reproduces the same decisions or side effects.

Why it matters in production

Proof of concept

A prototype may keep messages in memory while testing interaction design. Introduce durable checkpoints as soon as losing a run creates material rework or ambiguous external actions.

Production

Production requires atomic updates, encryption, retention policies, and a consistent execution identifier. Checkpoints should be written at meaningful boundaries with known replay behavior.

Enterprise scale

At scale, partition state by tenant and execution, control hot-record contention, and migrate schemas deliberately. Large raw tool payloads belong in an artifact store with references, not repeatedly copied checkpoint documents.

Architecture components

Checkpoint store

Persists versioned execution state and supports atomic conditional updates.

Artifact repository

Holds large immutable evidence and output objects referenced by checkpoints.

Execution identity

Connects thread, run, task, and external operation identifiers without conflating them.

Recovery coordinator

Loads compatible state and reconciles pending or uncertain effects before resuming.

Retention controller

Applies deletion, archival, and tenant-specific data handling rules to stored state.

The architecture, mapped

flowchart LR
 W["Agent worker"] --> C["Versioned checkpoint store"]
 W --> A["Immutable artifact store"]
 W --> T["Business tool"]
 T --> O["Operation ledger"]
 C --> R["Recovery coordinator"]
 O --> R
 A --> R
 R --> N["Replacement worker"]
 N --> C

sequenceDiagram
 participant W as Original worker
 participant C as Checkpoint store
 participant T as Business service
 participant R as Recovery worker
 W->>C: Persist pending operation identity
 W->>T: Execute command with operation identity
 T->>T: Commit business effect
 Note over W: Worker stops before recording response
 R->>C: Load pending operation
 R->>T: Query original operation status
 T-->>R: Existing committed result
 R->>C: Record result and resume next stage

Runtime flow

1. 1

   Create execution

   Assign a stable run identifier and persist initial inputs, permissions context, and schema version.

2. 2

   Apply observation

   Validate a tool result and update the state using an expected-version check.

3. 3

   Checkpoint boundary

   Save completed work and pending operation identities before advancing dependent stages.

4. 4

   Recover ownership

   A replacement worker claims the run with a lease or fencing token.

5. 5

   Reconcile effects

   Query external operation status for commands whose outcomes were not durably recorded.

6. 6

   Resume and retain

   Continue from a compatible checkpoint, then apply completion retention and deletion rules.

Resuming a document collection case

Banking operations · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

A banking operations team gathers business-account documents over several days, with customers and reviewers responding asynchronously.

The problem

A chat-only implementation loses which documents were validated and can repeatedly ask customers for already accepted evidence.

Agent requirement

The assistant must resume the case accurately after deployment or worker failure without duplicating document requests.

Architecture

A checkpoint store tracks required and accepted documents, while encrypted artifacts retain originals and an operation ledger records sent requests.

Runtime

• A new document is validated and its artifact reference is committed with the current case version.
• When another reviewer resumes the case, the agent loads accepted evidence and reconciles pending outbound requests before proposing next steps.

Failure scenario

If two workers update the same case, one conditional write fails and reloads the current state instead of overwriting new evidence.

Operational impact

Track recovery success, state conflicts, checkpoint size, and repeated customer requests. Retention must follow the organization's approved case-data policy.

Architecture tradeoffs

Failure scenarios & recovery

Common architecture mistakes

Persisting only chat messages

Store typed workflow position, operation identities, and accepted evidence.

Treating a cache as durable truth

Choose storage guarantees that match recovery requirements.

Saving secrets in every checkpoint

Store protected references and retrieve short-lived credentials at execution.

When to choose this pattern

Choose it when

• Runs span process restarts or long user pauses.
• External effects require reliable recovery and reconciliation.
• Operators need a durable account of accepted evidence.

Avoid it when

• The request is stateless and safely recomputable.
• Stored context creates unnecessary data retention exposure.
• No stable execution identity can be maintained.

Architecture checklist

• Define authoritative state fields and owners.
• Version checkpoint schemas.
• Use conditional writes or fenced ownership.
• Keep large artifacts outside checkpoint records.
• Test recovery around every command boundary.
• Document retention and deletion propagation.

Related concepts

• 3 — Agentic State Machines
• 6 — Asynchronous Agent Execution
• 16 — Task Interruption & Resumption
• 57 — Crash-Safe Memory
• 95 — Distributed Memory Architectures

Primary references

• LangGraph: persistence