Restore the recorded compatible release set

Learning objective

Roll back the compatible agent, model, prompt, tool, and orchestration release set using recorded immutable version evidence; do not assume Foundry hosted agents natively support traffic-weighted routing.

Core idea

Rollback restores a known compatible combination, not merely an earlier coordinator prompt or container. If the preceding agent expects a tool schema that no longer exists, switching back can make the incident worse. Identify the set that passed validation, confirm its dependencies remain available and authorized, and then direct work to it through a controlled mechanism.

Foundry hosted-agent endpoints serve one version at a time and route 100% of traffic to that version. Traffic splitting between versions is unsupported. A weighted rollout and its weighted reversal belong at your own routing layer, such as Container Apps ingress. Reverting a Foundry version reference and changing Container Apps traffic are different operations with different scopes.

How it works

Recover the evidence before choosing a target

Start with the release record described in 4.3.2. It should connect immutable agent identifiers and runtime artifacts to their tested model, prompt, tool, and orchestration dependencies. Retrieve the preceding approved record rather than inferring it from a deployment label, a branch name, or whatever artifact a build system produces today.

Foundry saved agent versions cannot be edited in place. For prompt-based agents, the recorded <agent_name>:<version> identifies the saved definition that contains the instructions and configured model and tools. The lifecycle documentation explicitly supports directing requests to specific agent versions for controlled deployment and rollback. Restore the intended definition, but also verify what its external references resolve to. See 2.1.4 for prompt-version evidence; rollback here concerns the entire workflow.

A hosted-agent version snapshots its image, resource allocation, environment variables, and protocol configuration. That snapshot is useful evidence for orchestration code and configuration. It does not assert that a remote tool implementation or model behind a deployment name has remained unchanged. Preserve the relevant dependency evidence with the version, and compare it with the deployed targets before recovery.

Use the record to answer five questions: which agent versions receive work, which prompt definitions they contain, which model versions they invoke, which tool contracts they expect, and which orchestration artifact coordinates them. A set with one unresolved answer is a recovery candidate requiring validation, rather than an established known-good target.

Confirm the dependencies can still run together

Check model deployment identity, resolved model version, and upgrade policy. Azure OpenAI’s versionUpgradeOption can permit automatic replacement of a model behind the same deployment name. For supported deployments, NoAutoUpgrade prevents replacement but does not preserve availability after retirement. An immutable agent version is therefore not a permanent reservation of its referenced model.

Check tool endpoints and adapters against the recorded contract. Restore the compatible adapter or tool service when necessary, rather than making the preceding agent consume an incompatible response. See 2.3.9 for tool compatibility and replay semantics. Include specialist handoff contracts in the check: a coordinator can fail even when every individual specialist runs successfully.

Check permissions and credential references. Published-agent permissions can differ from project permissions; see 1.2.3 for identity lifecycle. Do not undo a security rotation by restoring a revoked credential. If the approved combination cannot operate with permitted credentials, create and validate a repaired set before exposing it.

Container Apps secret values are application-scoped and do not create a revision when changed. Updating a secret does not automatically change an existing revision’s ordinary secret usage until restart or deployment; versionless Key Vault references have their own automatic adoption behavior. The recovery test must examine resolved bindings, not assume the retained revision restores every secret and configuration value.

Restore work through the mechanism you control

For a retained Container Apps revision, az containerapp revision list and az containerapp revision show provide revision evidence. An inactive retained revision can be activated with az containerapp revision activate. Confirm that it starts and its dependencies work before assigning traffic. In multiple revision mode, az containerapp ingress traffic set with --revision-weight returns allocation to the selected revision; the weights must still total 100%.

A complete reversal assigns 100% to the approved recovery revision and 0% to the failing revision. Record the resulting configuration and the actual release identifiers observed in requests. az containerapp revision deactivate stops all running replicas of the selected revision, so do not treat deactivation as a harmless metadata operation while it still owns in-flight work.

For a Foundry Agent Application, the documented management operation updates the child agentdeployments resource with PUT, selecting agents[].agentName and agents[].agentVersion. The published deployment type distinguishes Managed prompt agents from Hosted agents. Selecting a recorded previous version through that update is a way to restore the reference; it is not a percentage-based traffic operation. The application supports one active deployment and directs 100% of its endpoint traffic to it.

Rollback restores the recorded set only after its dependencies are confirmed, through a revision weight in Container Apps or a version reference in a Foundry Agent Application.

The publishing page labels its code packages as preview. Treat those SDK samples according to that warning rather than assuming production support from the availability of an example. For the management REST path, discover supported API versions through az provider show --namespace Microsoft.CognitiveServices as the page instructs. Preserve the deployment’s required properties when updating it and verify the resulting reference and state.

Distinguish restored routing from repaired outcomes

A routing change affects where admitted work goes; it does not erase a tool action already committed by the failing release. Record affected workflow identifiers and reconcile uncertain or duplicate effects through the application’s recovery policy. See 3.3.9 for incident reconstruction and replay. Do not rerun a side-effecting workflow merely because its caller failed to receive a response.

Define how in-flight sessions finish, stop, or resume under compatible state. That is application policy, not a guarantee provided by a traffic weight. Test a representative request after the switch, verify agent and dependency attribution, and compare operational and behavioral results with the approved baseline. Declare recovery only when the intended set is actually serving acceptable outcomes.

Key distinctions and trade-offs

Reference rollback versus compatible-set rollback: An agent version update restores one reference. A compatible-set rollback restores the tested combination of references and implementations.

Retained revision versus usable recovery target: Retention preserves deployment evidence. Availability, permissions, and dependency compatibility determine whether that evidence can become a working service.

Traffic reversal versus compensation: Reversal stops further exposure through a router. Compensation or reconciliation handles consequences already produced by the faulty workflow.

Keeping the preceding set runnable increases recovery speed but consumes maintenance effort and may retain infrastructure. Rebuilding it during an incident reduces standing capacity requirements but introduces startup, artifact, and dependency uncertainty. Choose the retention period as part of release governance, rather than discovering it during failure.

Architecture / decision scenario

A canary coordinator starts misreading a specialist’s tool result. The incident record identifies candidate set B and approved set A. A’s record contains the coordinator and specialist versions, prompt-bearing definitions, model version, tool adapter, and orchestration revision.

The operator finds that the shared tool changed its response contract after A’s acceptance test. Assigning A 100% immediately would reproduce a different failure. The team restores A’s compatible adapter, verifies its model remains available, and checks its permitted secret bindings. It then activates the retained revision if needed and restores its ingress allocation to 100%.

If the workflow instead uses a published Foundry application, the operator updates the deployment’s recorded agentVersion after the same compatibility checks. There is no assumed native weighted split. Finally, the team reconciles tool effects already initiated by B and validates A-attributed outcomes before closing recovery.

Common exam traps

• Reverting the prompt while leaving incompatible tools or specialists deployed.
• Treating a deployment name as immutable model evidence.
• Assuming Foundry hosted agents expose traffic-weighted version routing.
• Deactivating a revision without considering its running replicas and work.
• Restoring credentials that security policy has revoked.
• Equating a successful routing update with reversal of committed tool effects.

What to remember

Recover from recorded immutable evidence, then verify that the whole combination remains usable. Use Container Apps weights for controlled traffic reversal or the documented Foundry deployment update for a version reference change. Validate restored outcomes and reconcile previous effects; rollback does not rewrite workflow history.

Knowledge check

References

• Microsoft, Agent development lifecycle in Microsoft Foundry
• Microsoft, Hosted agents in Foundry Agent Service
• Microsoft, Agent applications in Microsoft Foundry
• Microsoft, Manage revisions in Azure Container Apps
• Microsoft, Traffic splitting in Azure Container Apps
• Microsoft, Manage secrets in Azure Container Apps
• Microsoft, Azure OpenAI in Microsoft Foundry Models working with models