Canary Rollouts for AI Agents

Prerequisites

Before sending live traffic to a candidate, you need a stable user or conversation identifier, an immutable configuration store, a run registry, and traces that connect model calls with tool calls. Define the control bundle, the candidate bundle, and the conditions that will stop or advance the rollout.

You also need an explicit completion or cancellation path for every tool that can change external state. If a side-effecting operation cannot finish safely, report its status, or be cancelled at a known boundary, keep that operation out of the canary. Test it offline or in a non-writing mode first.

Roll out the canary

1. Package the complete agent variant.

   Give the candidate one immutable bundle identifier. That bundle must pin the exact model identifier, prompt revision, tool set, and policy together. An agent canary that varies these independently cannot tell you which change caused a regression or improvement.

   Treat tool definitions as versioned inputs, including their names, schemas, enabled operations, and implementation release. Treat policy as executable configuration: tool permissions, approval requirements, limits, and cancellation rules. The prompt reference should point to an immutable revision, following the same discipline used for versioning agent prompts.

   Record the control bundle in the same format. A label such as candidate-model is insufficient if the prompt or tool permissions can change underneath it. Do not edit a bundle after assignment; create another identifier. This costs configuration work and leaves more releases to manage, but it preserves attribution. If you need to change only the prompt, the candidate is still a new four-part bundle whose other three parts match the control.

2. Set evaluation and operational gates before exposure.

   Run the candidate and control against the same representative test inputs. Specify the expected behavior and graders before examining the candidate results. OpenAI’s evaluation guide, checked 2026-08-26, describes the core sequence as defining the task, running test inputs, and analysing the results. Its hosted Evals platform is being deprecated, so use the method without making the canary depend on that product’s continued availability.

   Cover the behavior that can block a release: task success, prohibited tool use, required approval, malformed tool arguments, and unacceptable responses. Add operational gates for failures, latency, resource use, and tool outcomes, but do not invent universal thresholds. Set each boundary from your service objective or current control behavior, and state whether one severe policy breach stops the rollout immediately.

   Offline evals are a gate, not the canary itself. They exercise selected inputs and known criteria; live routing reveals behavior in real conversations and tool environments. If you cannot define a decision rule for a signal, collecting it will not tell the operator whether to advance or stop.

3. Assign only new conversations, then keep the assignment sticky.

   At the first turn, map a stable routing key to either the control or candidate and persist the resulting bundle identifier with the conversation. Every later turn must read that stored assignment rather than sample again. Sticky assignment keeps one user’s multi-turn session on one variant and avoids changing behavior mid-conversation.

   Pete Hodgson’s feature-toggle treatment, published 2017-10-09, demonstrates a canary with a consistently assigned user cohort; its worked example uses 1% as an example, not a default rollout size. Choose exposure according to the traffic needed for your declared checks and the harm the candidate could cause.

   Route internal or low-risk users deliberately if that is the condition you intend to test, but label the cohort accordingly. Results from a restricted cohort do not establish behavior for a broader population. Per-request random assignment is the wrong mechanism for a conversational agent because one session can cross variants between turns.

4. Make the bundle visible in every trace and outcome.

   Attach the bundle identifier, conversation identifier, run identifier, assignment time, and cohort to the root run trace. Propagate them through model calls and tool calls so an operator can move from a failed outcome to the exact configuration that produced it. Use the practices for correlation identifiers across agent runs when work crosses queues or services.

   Use the OpenTelemetry generative-model semantic-conventions entry point, checked 2026-08-26, as the base vocabulary for model and agent telemetry. That page now directs readers to OpenTelemetry’s dedicated GenAI conventions repository. Add your bundle and cohort fields as application attributes rather than overloading a standard field with a private meaning.

   Capture the outcome needed for the rollout decision: eval grade where available, model or tool error, tool permission decision, cancellation result, and whether an external side effect was attempted and completed. The cost is higher trace volume and careful access control. Omitting bundle identity is worse: aggregate metrics can show a change without identifying which configuration produced it.

5. Separate assignment control from run execution.

   The rollout switch should decide whether new conversations may enter the candidate. It must not blindly terminate work already executing. Track active runs by bundle and classify tools according to whether they are read-only, safely cancellable, or side-effecting.

   Define the rollback action for each class before launch. Read-only work may be cancelled according to its timeout policy. A side-effecting run must either reach a known completion state or be cancelled at a boundary that does not leave an unknown external result. Coordinate these rules with the agent’s cancellation and timeout budgets and its tool permission model.

   Do not implement rollback by retrying every interrupted operation on the control bundle. A retry can repeat a write whose first result is merely unknown. Preserve the original bundle identifier on any recovery work, and require the tool’s own status or idempotency mechanism before deciding whether another attempt is safe.

6. Open the cohort and compare like with like.

   Start candidate assignment only after the dashboards, alerts, and stop control are working. Compare candidate and control over the same observation period and separate results by task type, tool risk, and conversation length where those conditions affect the decision. Inspect severe individual failures as well as aggregate rates; an average can conceal a policy violation.

   Change one bundle at a time during the observation window. Editing the prompt, adding a tool, or loosening a policy creates a new candidate and resets attribution. Hold exposure steady long enough to evaluate the declared gates, but do not claim a sample is sufficient without a method that supports that conclusion.

   Advance only when the candidate meets every blocking gate. If the data is inconclusive, keep the current split or gather more relevant cases. Increasing exposure merely because no alert fired is the wrong answer when the success criteria have not been measured.

7. Roll back or promote without moving active sessions.

   On rollback, first stop new candidate assignments. Keep the control available for new conversations while the run registry identifies candidate work still in progress. Allow already-started side-effecting runs to finish, or cancel them safely under the rules defined earlier. Report any run whose external outcome remains unknown instead of treating it as cancelled.

   Existing multi-turn conversations should retain their pinned bundle until they end or reach an explicitly designed migration boundary. Switching them silently to the control defeats sticky assignment and can make prior tool state or instructions inconsistent with the next turn.

   Promotion uses the same mechanism in the other direction: assign the candidate bundle to new conversations, monitor the same gates, and leave existing control conversations pinned. Retire the rollout switch only after both cohorts’ active sessions and side-effecting runs have drained. Keep the bundle records and decision evidence so a later incident can reconstruct what ran.

Expected result

Done means every run resolves to one immutable model-prompt-tools-policy bundle; every multi-turn conversation stays on its assigned bundle; traces separate candidate from control; and the rollout control can stop new candidate assignments without abandoning or duplicating side effects. Promotion and rollback are routing decisions with explicit handling for work already in progress.