A deployment is an immutable artifact of your code. Workflows are versioned by deployment. In-flight runs continue on the version they started with; new runs use the latest deployment. Environments (staging, prod) are pointers that resolve to a deployment at run-start time.

deployment_v1   ◄── run_42 (in flight, started before v2)
deployment_v2   ◄── run_43, run_44 (started after v2)
                ▲
                │
       env "prod" ──► deployment_v2

       agnt5 deploy ──► creates deployment_v3
                       env "prod" advances to v3
                       run_42 still on v1
                       run_43, run_44 still on v2
                       new runs go to v3

The routing key for every dispatchable unit is (tenant_id, deployment_id, component_id). Pinning runs to deployment_id is what lets the same workflow code change without breaking inflight executions.

The mental model

Treat a deployment as a frozen snapshot: a tarball of your code, a content hash, a container image. Once published, it never changes. The control plane records the deployment’s manifest — which workflows, functions, tools, and agents it registers — and the runtime keeps the deployment available as long as any run is still using it.

An environment is a named pointer that maps to a deployment. prod, staging, dev are not deployments themselves; they are aliases. agnt5 deploy --env prod creates a new deployment and atomically moves the prod pointer to it. New runs that target environment prod get routed to the deployment the pointer currently names; runs that started under the previous deployment keep running on it.

The runtime resolves the environment pointer at ingress — the moment the run is created. After that, the run’s identity includes its deployment_id, and every step routes back to the same deployment for the entire lifetime of the run. A long-running workflow that started on v2 continues calling v2’s @function handlers even after v3 ships, because the routing key it carries is fixed.

This is what makes rolling deploys safe: you can ship breaking changes to your workflow body, knowing in-flight runs are not subjected to the new code mid-flight.

Why it works this way

Workflows can run for hours, days, or weeks. A naive “always use the latest code” model would mean a workflow that started Monday could see Wednesday’s code partway through, with no compatibility story between the two. Pinning runs to their deployment is the smallest mechanism that gives you a consistent code view per run.

Environments-as-pointers separates deploying code from routing traffic to it. You can publish a deployment without pointing prod at it, then advance the pointer when you are ready. Rollback is the same operation in reverse — point the environment back at the previous deployment; in-flight runs on the buggy deployment finish on it (they would have anyway), and new runs go to the safe one.

The (tenant_id, deployment_id, component_id) routing key is the foundation of multi-tenancy and version coexistence. The runtime never has to ask “which version of this function should I call” — the routing key already encodes it.

Edge cases and gotchas

• Long-running workflows can outlive several deployments. A workflow that runs for two weeks may span five deployments. Plan for this when refactoring: keep @function signatures backwards-compatible if any in-flight run still calls them.
• Removing a workflow does not orphan its runs. A deployment that no longer registers a workflow can still serve in-flight runs from earlier deployments — the runtime keeps the older deployment alive while runs reference it.
• Renaming a function is a breaking change for in-flight runs. Inside a workflow, ctx.step(handler, ...) resolves by registered name. If v3 renames fetch_article to fetch_url, a v2 run mid-flight that next calls ctx.step(fetch_article, ...) still routes to v2’s registry — fine. But if you delete v2 deployment artifacts before v2 runs drain, the routing fails.
• Signals and queries must be compatible across versions. A signal sent to a run uses the run’s deployment routing — but the signal’s payload schema must match what the run’s workflow expects. Treat signal/query schemas as a public API.
• Environment promotion is not run promotion. Promoting staging to point at deployment v5 does not move staging’s in-flight runs to v5. They stay on whatever deployment they started on.
• Cohorted upgrades require explicit gating. AGNT5 does not automatically run two versions of a workflow side-by-side and pick the better one. If you want canary or A/B deployments, gate the routing yourself — for example, two environments pointing at two deployments, with traffic split at the caller.

Related concepts

• Architecture overview — where deployments and environments sit in the runtime.
• What the runtime owns vs. your code — the runtime owns deployment artifacts and version pinning; your code owns staying compatible.
• Sandbox isolation tiers — tier selection is per-deployment.