Course contentsShow
← AI Engineering
Lesson 1776 of 1,88643. Workflow Orchestration and State MachinesFree lesson

Workflow Versioning and Migration

Manage workflow definitions as code and handle version updates for running workflows.

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:

  1. Assign it a new version identifier (e.g., v2, 2024-01-15, semantic versioning)
  2. Deploy it alongside existing versions
  3. 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.