How do I roll out an agent revision without stranding active tasks?

New traffic is only one population in a rollout

A percentage-based canary routes newly arriving work. An agent service may also hold accepted tasks from yesterday that are sleeping, waiting for a callback, or awaiting a reviewer. Their next step can arrive after the deployment team has declared the rollout complete.

The release inventory must therefore include future runnable work. Queue depth is an incomplete view because many legitimate waits do not occupy the execution queue. Use the task system of record to enumerate the revisions that still have obligations.

Choose a compatibility rule before replacing workers

One possible rule keeps a task on its original release until completion. Another allows a compatible new worker to interpret older state. A third performs an explicit migration at a defined boundary. Each carries a different burden: retained capacity, backward compatibility, or a tested transformation with recovery.

Temporal’s Worker Versioning documentation gives a concrete product example of pinned and upgradeable workflows. An ordinary message queue has no such guarantee unless the application builds the routing and compatibility contract. Use the runtime’s actual semantics rather than borrowing the product terminology as a promise.

Completion may leave additional support obligations. Temporal notes that a closed Workflow can execute code paths when queried within its retention period while workers of that version are polling. Distinguish reading stored history from a worker-executed Query, and explicitly retain or retire the latter capability under the service contract.

The approval that arrives after the last old worker leaves

Consider a hypothetical fleet with 180 tasks accepted under release 17. At rollout time, 160 have completed and 20 remain active: 12 are waiting for human review, and eight are waiting for scheduled evidence refreshes. The execution queue is empty. The team removes release 17 workers and assigns every worker release 18, whose state reader no longer accepts one field used by release 17.

The next morning, an approval arrives and the task cannot advance. The failure began at worker retirement, not at approval delivery. A release inventory would have shown 20 outstanding obligations and stopped retirement until the team retained capacity or established a supported disposition.

Maintain a release disposition table

Copy this artifact into the rollout record. The counts and revisions here belong to the constructed scenario.

Task population	Count	Allowed executor	Disposition before retirement	Required evidence
Finished on release 17	160	Compatible executor if historical Queries or replay require one	Retain supported query/replay capability or approve its retirement	Terminal state, retention window, and query disposition verified
Awaiting reviewer	12	Release 17 cohort	Continue pinned or reviewed migration	Future approval route tested
Scheduled refresh	8	Release 17 cohort	Preserve wakeup and assets	Timer-to-worker route exercised
New admissions	Variable	Release 18 canary	Expand only within release policy	Candidate manifest and serving health
State already written by 18	Measured live	Compatible executor	Assess separately if rollback requested	Old reader compatibility or repair plan

Add owners and expiry dates to retained cohorts, including the disposition of historical queries after worker retirement. An unsupported task should become a visible exception requiring disposition, never silently fall back to the newest worker.

Retire a revision only after its obligations end

The retirement gate queries nonterminal tasks, durable timers, outstanding callback routes, and any policy-governed operations that can create more work for the revision. It checks retained-history Query and replay commitments against their support and retention windows, then confirms that no new admissions can target the old cohort. A runtime’s drained status is insufficient if promised historical operations still need its workers.

Keep enough compatible capacity to meet the support contract while the population shrinks and retained operations remain supported. A single neglected worker that cannot be restarted from retained assets is not a dependable support strategy. Test replacing an old-cohort worker after the main fleet has moved forward, including a supported Query against a closed workflow when the runtime requires execution.

Rollback changes routing before it repairs history

Stop further exposure to a faulty revision, then inspect what its tasks have already persisted or changed. Kubernetes rollback restores a Pod template revision; it cannot restore an application’s earlier database contents or reverse a tool action.

This article owns deployment population and compatibility decisions. Use safe long-running task recovery for state reconstruction and effect reconciliation. Do not replace that process with a blanket instruction to rerun every task on the old image.

Long support windows change the architecture decision

Weeks-long waits can require several compatible releases, retained model assets, and explicit support ownership. If those costs are excessive, reconsider task lifetime or choose a runtime with suitable migration capabilities. Continue with worker draining during deployment and the connected release strategy in AI Agent Platform Engineering.