Agent State
State that survives requests
Agents are stateful: message history, tool results, memory and checkpoints must persist across requests for long-running work. State architecture — where it lives, how it's versioned, how it resumes — decides durability.
What you will learn
- Identify all agent state kinds
- Persist state durably with versioning
- Resume sessions across requests
What is this?
Agent state includes the conversation history, tool-call traces, memory references, and current plan/checkpoint. For anything longer than one request, this state must persist — in a store keyed by session, versioned, resumable, and consistent. Stateless servers + durable state is the architecture that survives restarts, redeploys, and scale-out.
Why do you need it?
- Long tasks span many requests.
- Persisted state allows crash-recovery and resumability.
- State separation makes workers stateless and scalable.
- Versioned state prevents schema drift against running sessions.
Mental model
A save file in a video game
Persisted agent state
You die (crash) at the boss and reload the save — starting at the last checkpoint, not the title screen. The save holds your inventory (tool results), position (current step), and quest log (plan). Save files = durable, versioned, resumable state.
How it works
- Serialize session state: messages, calls, results, plan, checkpoint.
- Store per-session (DB/key-value/Blob).
- Load on request; append; save at checkpoints.
- Version the state schema (migrations for old sessions).
- Support resume: reload and continue the loop.
Stateless workers, durable state.
In production
- Long-running research sessions persist and resume across requests.
- Migration agents snapshot state per batch.
- Multi-worker fan-out coexists with one durable session record.
Best practices
- Keep workers stateless; state lives in the store.
- Checkpoint after each meaningful step.
- Version your state schema from day one.
- Make state inspectable (audit, debugging).
Common mistakes
- Holding state in-process (die on restart).
- Saving only at the end (crash loses everything).
- Unversioned blobs that break when code changes.
Common issues
Agent loses memory between requestsState not persisted
Persist messages+calls+checkpoint per session.
Old sessions fail after deploySchema drift
Version state; write migrations/loaders.
Debugging tips
- Session 'resets' on redeploy → state in-memory; move to store.
- Resume reproduces wrong context → load path missing parts; log what loads.
- Mid-session schema broke → migrations absent; add versioned loaders.
Interview checkpoint
Quick quiz
Workers should be…
Checkpoint per step protects long tasks from crashes.