Advanced10 min
Migration & Graph Versioning
Updating agents in production without breaking active sessions: graph versioning, state migration strategies, and backward-compatible deploys.
Quick Reference
- →Graph versioning: tag each deployed graph with a version identifier so active threads continue on the version they started with
- →State migration: when the state schema changes, write a migration function that transforms old checkpoints to the new shape
- →Use backward-compatible state changes (add optional fields) when possible to avoid migrations entirely
- →Blue-green deployments for agents: run old and new versions simultaneously, route new threads to the new version
- →Set a deprecation window: old graph versions stay active for N days to let in-flight threads complete before removal
The Versioning Problem
Agents have long-lived state that spans deployments
Unlike stateless APIs, agent threads persist across deployments. A user's conversation started on v1 of your graph must continue working after you deploy v2. Breaking state changes crash active threads.
Traditional web services are stateless -- deploy a new version and all requests use it immediately. Agent systems are fundamentally different: each thread has checkpointed state that the graph reads and writes. If you change the state schema or graph topology, existing checkpoints become incompatible with the new code.
- ▸Adding a required field to state breaks all existing checkpoints that lack it
- ▸Removing a state field causes KeyError when old checkpoints are loaded
- ▸Renaming a node breaks edges that reference the old name in saved graph topology
- ▸Changing a tool's output schema breaks downstream nodes that parse the old format
- ▸Reordering conditional edges changes routing behavior for in-flight conversations
| Change Type | Breaking? | Migration Required? | Safe Alternative |
|---|---|---|---|
| Add optional state field | No | No | Use default value in reducer |
| Add required state field | Yes | Yes | Make it optional with default instead |
| Remove state field | Yes | Yes | Mark deprecated, remove in next major version |
| Rename state field | Yes | Yes | Add new field + migration, keep old field temporarily |
| Add new node | No | No | Existing checkpoints never route to it |
| Remove node referenced by checkpoints | Yes | Yes | Keep as no-op stub during deprecation window |
| Change tool output schema | Conditional | If downstream parses it | Version the tool output format |