Govern promotion through dependency retirement

Learning objective

Govern agent-version promotion, dependency compatibility, deprecation, and retirement.

Core idea

An immutable agent version gives you a stable definition, but release governance decides whether that version may serve production and whether its dependencies remain supportable. Maintain a record of approved combinations, responsible owners, required evidence, and retirement constraints. Treat promotion as an authorization decision and retirement as removal of a usable target, rather than as incidental deployment housekeeping.

A multi-agent release can become unsuitable without any change to its saved prompt. A model can retire, a tool can remove a contract, or a credential can be revoked. Governance must track those dependencies and produce a tested successor while the preceding combination remains available. See 4.3.2 for the release record and 4.3.4 for recovery from it.

How it works

Give every version a governed use state

Foundry saved agent versions are immutable; changing a version’s definition requires saving another version. You can compare agent setup, chat outputs for identical inputs, and YAML definitions in version history. These mechanisms help identify what changed, but a comparison does not itself approve a production release.

Maintain application-owned states such as candidate, approved, deprecated, and retired for your release sets. These are governance labels you define, not asserted Foundry agent-version status values. A candidate has not passed all required evidence. An approved set has explicit production authorization. A deprecated set remains available for a stated transition or recovery purpose but is no longer the preferred target. A retired set must no longer receive work.

Connect each state transition to evidence and authority. For promotion, record the exact saved versions, compatible dependency record, validation results, and approver. For deprecation, record the successor, migration requirements, support owner, and end of the permitted use window. For retirement, record that consumers and recovery policies no longer depend on the set before disabling or deleting its runtime resources.

An agent version can exist while its release set is prohibited from use. Existence is not authorization. Conversely, keeping an approved record does not keep its dependencies alive. Make the governance record describe both policy permission and technical usability.

Enforce promotion and compatibility separately

Azure DevOps Services Approvals and checks protect resources used by pipeline stages. Administrators configure them outside pipeline YAML. Use Branch control or Required template to constrain the deployment path, Invoke REST API to query your compatibility and evaluation evidence, and Approvals for the responsible release owner. See 4.3.3 for the stage and traffic design.

The compatibility service is application logic. It should resolve the candidate’s recorded agents, prompts, model versions, tool contracts, and orchestration artifact before granting promotion. A passed test for a different specialist version or dataset does not authorize this candidate. Require new evidence when a dependency changes, even if the coordinator version does not.

Check permissions and contracts independently: authorization does not prove response compatibility, and compatibility does not prove published-identity access. See 2.3.9 and 1.2.3; join their evidence in the release decision.

Record the policy version behind approval and reassess approved sets when safety criteria change. You define the evidence requirements; pipeline checks enforce the decision.

Track model lifecycle and upgrade behavior

The Foundry Models lifecycle page distinguishes Preview, Generally Available, Legacy, Deprecated, and Retired. Preview models have experimental weights, runtime, and API schemas and are not guaranteed to become generally available. Legacy is an optional stage that still permits deployments before deprecation. Deprecated is a restricted transition state, while Retired removes the model from service and inference returns 410 Gone.

For deprecated models, existing-customer eligibility is evaluated at subscription level for the specific model version. Existing customers can continue creating and managing deployments; new customers cannot access it. A separate subscription under the same tenant does not inherit eligibility. This can affect an environment migration even while an existing production deployment still runs.

The standard GA lifecycle sets the retirement date at launch: deprecation at 12 months and retirement at 18 months. Consult the Model retirement schedule for publisher-specific commitments. GA retirement notices arrive at least 60 days ahead through email to subscription owners with active deployments and Azure Service Health health advisories. Preview models receive at least 30 days’ notice and can be force-upgraded or retired without a replacement.

Detect lifecycle changes with the subscription-scoped Models API: GET /subscriptions/{sub}/providers/Microsoft.CognitiveServices/locations/{location}/models. Inspect lifecycleStatus together with deprecation.inference. The documented Deprecated stage maps to API value Deprecating; API value Deprecated means Retired and inference returns 410 Gone. An inference retirement date in the past also identifies retirement if the status field lags.

A model passes through the Deprecated stage, which the API calls Deprecating, before it is Retired, which the API calls Deprecated.

For Azure OpenAI deployments that support automatic updates, inspect versionUpgradeOption. OnceNewDefaultVersionAvailable updates to the default within two weeks of its designation. OnceCurrentVersionExpired upgrades at retirement. NoAutoUpgrade prevents automatic upgrading, but the deployment stops working when its version expires. The documented null value is equivalent to OnceCurrentVersionExpired.

Automatic upgrades apply to Global Standard, Data Zone Standard, and Standard deployment types. Provisioned deployments are not auto-upgraded; migrate manually through in-place migrations or multi-deployment migrations. Validate the replacement before either migration.

Retire consumers and recovery targets deliberately

Identify callers of deprecated tools and specialists, test their successors, and retain overlapping contracts or adapters where both sets must run. Record each remaining consumer and its permitted use deadline.

For Container Apps, az containerapp revision deactivate stops all running replicas of a revision. Coordinate that operation with traffic allocation and the application’s handling of in-flight work. Do not remove the preceding recovery target merely because the candidate has received its first successful production request. Close the agreed recovery window using quality evidence and dependency readiness.

Deleting an agent invalidates its identifier. The Foundry lifecycle documentation says a 404 Not Found for a previously created ID means it was deleted and repeated retries do not restore it. Preserve the evidence you need for audit, and ensure consumers no longer invoke the identifier before deletion. An archived release record is historical evidence, not an executable rollback target.

Key distinctions and trade-offs

Agent governance labels versus model lifecycle stages: Candidate and approved are application policy states. Preview, Deprecated, and Retired are documented model stages. Do not confuse permission to promote an agent with the vendor’s support status for its model.

Deprecation versus retirement: Deprecation schedules transition while some use remains possible. Retirement ends usable service. A recovery plan that depends on a retired model has lost its target.

Automatic upgrade versus controlled promotion: Automatic upgrade preserves a supported target under the documented policy but can replace the tested model version. Explicit selection improves change control while requiring active migration before expiration.

Historical approval versus continuing compatibility: Approval records a decision under particular evidence and policy. Dependency changes and stricter criteria can require reassessment without changing the saved agent definition.

Architecture / decision scenario

A service has approved set A and candidate set B. B changes a specialist contract and adopts a replacement model. The release owner requires a compatibility record and an Invoke REST API check before the production-environment Approvals check permits promotion. Passing a prompt-only evaluation is insufficient because the changed specialist and model must be tested together.

The team marks A deprecated in its own registry after B is approved, but retains A during the recovery window. It discovers that A’s model deployment uses OnceCurrentVersionExpired; leaving it alone could replace the model behind the recorded deployment name at retirement. The team schedules an evaluated migration and records the resulting version, rather than assuming A remains reproducible indefinitely.

A proposed recovery deployment in another subscription cannot rely on deprecated-model eligibility from production. The team verifies availability there and validates a supported alternative. Only after consumers have moved and the recovery window closes does it deactivate A’s revision and retire the set. Its historical record remains, clearly distinguished from a runnable target.

Common exam traps

• Assuming saving an immutable version authorizes production use forever.
• Treating application governance labels as Foundry agent status enums.
• Confusing the documented Deprecated stage (Deprecating in the API) with API value Deprecated, which means Retired.
• Assuming eligibility in one subscription transfers to another in the same tenant.
• Using NoAutoUpgrade as a promise of availability after retirement.
• Deleting an agent and retrying its previous identifier as recovery.

What to remember

Govern use states, evidence, compatibility, and dependency lifetime together. Name the promotion owner and enforcement check, inspect the model’s upgrade policy, and migrate before the recovery target becomes unavailable. Preserve historical evidence while distinguishing deprecated, authorized, and technically runnable release sets.

Knowledge check

References

• Microsoft, Agent development lifecycle in Microsoft Foundry
• Microsoft, Pipeline deployment approvals
• Microsoft, Foundry Models lifecycle and support policy
• Microsoft, Azure OpenAI in Microsoft Foundry Models working with models
• Microsoft, Manage revisions in Azure Container Apps