Agent Architecture
Advanced 13 min read Agent Architecture

Agent State Management

One truth, flowing through stages

Multi-stage agents need state that is typed, versioned, inspectable and resumable — a single source of truth flowing through every stage. State schema design is architecture: where it lives decides what breaks.

state managementschemaversioningcheckpointsingle source of truthresume
Prerequisites: Agent State
Before we start

What you will learn

  • Design typed state contracts across stages
  • Version state safely
  • Handle concurrent and resumed sessions
Introduction

What is this?

State management centralizes agent data: the typed state object that every stage reads and extends, stored durably per session, versioned, checkpointed. Stages must not invent their own state; the contract is the single source of truth. Divergence across stages is the #1 source of multi-agent bugs.

Motivation

Why do you need it?

  • Typed state catches contract violations at compile/test time.
  • Versioned state survives code evolution over running sessions.
  • Checkpoints make long tasks crash-safe and resumable.
  • A single truth makes debugging and audit tractable.
Think about it

Mental model

Imagine

A patient's shared medical chart

Think of

Centralized state

Every specialist (stage) reads and writes the ONE chart — meds, tests, notes. A doctor who keeps their own private chart creates contradictions and endangers the patient. Typed fields, versions, append-only notes; every doctor reads the same truth.

Mechanics

How it works

  • Define the state schema (typed, with required fields per stage).
  • Store durably per session; checkpoint after stages.
  • Version the schema; migrate old sessions.
  • Pass state by reference into stages; log mutations.
  • Support resume: reload last checkpoint and continue.

State lifecycle.

Init
Stage A
Checkpoint
Stage B
Resume
Real world

In production

  • Long-running migration agents persist tenant state per batch.
  • Multi-stage support flows keep one case state across escalations.
  • Undo-friendly systems snapshot state before each write.
Guidelines

Best practices

  • One state schema per session, typed and documented.
  • Stages extend, don't fork — enforce via interface.
  • Checkpoint after consequential stages.
  • Version state now; migrating later is painful.
Watch out

Common mistakes

  • Each stage caching its own copy drifts.
  • Untyped state (JSON.parse anywhere) — typos become runtime bombs.
  • No version tag, so deployments break old sessions.
Root cause analysis

Common issues

Error
Stage writes state in a different shape
Root cause

Untyped contract

Fix

Enforce types/interfaces at stage boundaries.

Error
Race on concurrent stages writes
Root cause

Shared mutable state

Fix

Isolate per-branch sub-state; merge deterministically.

When things break

Debugging tips

  • Cross-stage inconsistencies → audit state mutations per stage; find the fork.
  • Resume produces wrong context → checkpoint doesn't capture everything the loop needs.
  • Old sessions break post-deploy → schema migration missing.
Interviews

Interview checkpoint

Practice

Hands-on lab

State Machine for an Agent
25 min · intermediate
In progress
Objectives
  • Declare states and allowed transitions
  • Advance state through a step function
  • Reject transitions outside the graph

State Machine for an Agent

25 min · intermediate

0/3 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Stages should treat state as…

2

Schema versioning protects running sessions during deploys.

Go deeper

Official documentation

State management (LangGraph)
docs