Workflow Versioning and Migration
You'll learn how to evolve workflow definitions over time without breaking in-flight executions.
Why Workflows Need Versions
Your multi-step AI workflow—chaining ASR, retrieval, LLM calls, and TTS—is code. Like any code, it evolves: you fix bugs, add steps, optimize performance, or change branching logic. But unlike a simple API, workflows can run for hours or days. What happens when you deploy v2 while v1 executions are still running?
Versioning lets you manage multiple definitions simultaneously. Each workflow execution locks to a specific version when it starts. Running workflows continue on their original version, while new executions use the latest.
Core Principles
Treat workflows as immutable artifacts. When you change your workflow logic:
- Assign it a new version identifier (e.g.,
v2,2024-01-15, semantic versioning) - Deploy it alongside existing versions
- Let the orchestrator route new executions to v2, while v1 executions complete naturally
Think of it like blue-green deployment for stateful processes.
Migration handles active workflows you must upgrade mid-flight—rare but necessary for critical fixes. The orchestrator pauses the execution, maps its current state (intermediate results, checkpoints) to the new workflow structure, then resumes. This requires careful state schema compatibility.
Practical Strategies
- Backward-compatible changes: Add optional steps, new branches—don't remove required state fields
- Version metadata: Tag each execution with its workflow version for debugging
- Graceful deprecation: Stop accepting new v1 executions, wait for stragglers to finish
- Migration scripts: Write custom code to transform state from v1 → v2 when forced upgrades are unavoidable
Key Takeaway: Version your workflow definitions like code releases, keep running executions on their original version, and only migrate in-flight workflows when absolutely necessary with careful state mapping.