An AI model deprecation becomes an outage only when a model identifier is treated as a harmless configuration detail. In production, that identifier can determine output structure, tool behavior, latency, token use, rate limits, safety filters, and cost. A safe migration therefore needs more than replacing one string.
The practical sequence is: inventory every dependency, confirm exactly what the provider is retiring, test the proposed replacement against real tasks, shadow it without creating duplicate side effects, revise operational budgets, keep a tested rollback route, and verify production after the switch. Start while both models are available; a retirement date is a deadline for completed migration, not a suggested start date.
Information check: Provider lifecycle facts and dated examples in this article were verified against official documentation on 2026-07-24. Dates and replacement recommendations can change, so recheck the linked provider pages before using this checklist for a live migration.
1. Inventory every model dependency
Begin with observed usage, not a repository-wide search alone. A model name may live in application code, an environment variable, an infrastructure template, a gateway rule, a prompt-management service, a scheduled batch job, a fine-tuning reference, or a vendor dashboard.
Build one row per workload:
| Field | What to record |
|---|---|
| Owner and service | Team, repository, deployment, and escalation contact |
| Provider path | Direct API, cloud marketplace, gateway, or embedded product |
| Exact model ID | Alias, dated snapshot, fine-tuned ID, or deployment name |
| API surface | Chat, responses, embeddings, audio, image, batch, or tool use |
| Traffic and criticality | Requests per day, peak load, user impact, and recovery target |
| Behavioral contract | Required schema, tools, languages, refusals, and quality thresholds |
| Operational contract | Context size, output cap, latency, rate limit, and budget |
| Data boundary | Regions, retention settings, logging, and sensitive-data rules |
Use billing exports, API gateway logs, provider usage reports, and tracing data to catch workloads that are not obvious in source control. Anthropic, for example, documents a Claude Console usage export that breaks usage down by API key and model. That is useful evidence, but it does not replace searches for dormant disaster-recovery jobs or rarely triggered workflows.
Search for aliases as well as snapshots. An alias may move without a hard failure, while a dated snapshot may stop accepting requests. Record both the configured value and the model actually reported in responses or telemetry where the provider exposes it.
2. Read the deprecation scope, not just the headline
“Deprecated” can refer to a model, one snapshot, an endpoint, an SDK module, a preview feature, new fine-tuning jobs, or all inference. Those scopes require different work. Confirm four items in the provider’s own notice: the affected identifier, the final availability date, the affected platform, and the recommended replacement.
Platform boundaries matter. Anthropic states that its published dates apply to Anthropic-operated platforms, while partner-operated platforms such as Amazon Bedrock and Google Cloud can set different schedules. A direct Claude API migration date should not be copied into a Bedrock runbook without checking Bedrock’s catalog.
Current examples show why a dated source ledger is necessary:
- OpenAI’s deprecation page, checked 2026-07-24, lists
gpt-5.2-chat-latestandgpt-5.3-chat-latestfor shutdown on 2026-08-10, withgpt-5.6-solas the recommended replacement: OpenAI API deprecations. - Anthropic’s page, checked 2026-07-24, lists
claude-opus-4-1-20250805as deprecated on 2026-06-05 with a retirement date of 2026-08-05 andclaude-opus-4-8as the recommended replacement. It also says customers with active deployments receive at least 60 days’ notice for publicly released models: Claude model deprecations. - GitHub’s Copilot model table, checked 2026-07-24, records retirement dates and suggested alternatives for models exposed through Copilot. That is a separate product lifecycle from a provider’s direct API: GitHub Copilot supported models.
- Google Cloud’s lifecycle page, checked 2026-07-24, distinguishes a deprecation date from a shutdown date and documents the retired Vertex AI generative AI SDK module separately from model lifecycles: Vertex AI generative AI deprecations.
- Amazon Bedrock’s lifecycle page, checked 2026-07-24, says its dates are specific to Bedrock and may differ from model-provider dates. It exposes lifecycle state through
GetFoundationModelandListFoundationModels, and says migration does not happen automatically at end of life: Amazon Bedrock model lifecycle. - Microsoft’s schedule, checked 2026-07-24, lists lifecycle stage, retirement date, and replacement by model and version for Foundry Models. Use the schedule for the deployed Azure offering rather than importing a direct-provider date: Microsoft Foundry model retirement schedule.
Store the notice URL, the date your team checked it, and a copy of the relevant identifiers in the migration ticket. For a worked example focused on an intermediary product, see how to respond to a GitHub Models retirement.
3. Build equivalence tests around your contract
A provider’s suggested replacement is a migration candidate, not proof of equivalence. Build a fixed evaluation set from representative, permitted production inputs. Include common requests, long-context cases, multiple languages, malformed input, adversarial instructions, tool failures, and the rare cases that produce costly incidents.
Test the properties your application actually depends on:
- Task quality: factuality, completeness, classification accuracy, or a domain rubric.
- Output contract: valid JSON, required fields, citations, formatting, and maximum length.
- Tool behavior: correct tool choice, valid arguments, sequencing, and refusal to call unsafe tools.
- Safety behavior: expected refusals, escalation paths, and handling of injected instructions.
- Operations: time to first token, end-to-end latency, token use, error rate, and retry rate.
Keep deterministic checks as release gates, then add scored review for qualities that cannot be reduced to exact matches. Do not let one blended score hide a severe regression: schema validity and prohibited actions should be hard pass/fail gates. The approach in machine gates for AI output helps separate enforceable requirements from subjective review.
Run the old and new model with explicitly versioned prompts and parameters. Otherwise, a prompt edit made during testing can be mistaken for a model improvement. Save the evaluation dataset version, model IDs, request parameters, evaluator version, and raw outputs so another engineer can reproduce the decision.
4. Shadow traffic without duplicating side effects
Shadowing sends a copy of eligible production input to the candidate model while the current model still serves the user. It reveals real input distributions and operational behavior, but only if the shadow path is isolated.
The candidate must not send email, write to a database, execute a purchase, update a ticket, call a mutable tool, or stream output to the user. Replace tools with read-only stubs or record the proposed calls for offline scoring. Apply the same data-handling rules as production; “only a test” does not authorize a new provider, region, retention mode, or logging destination.
Sample gradually. Start with low-risk routes, redact or exclude sensitive classes when required, and cap shadow spend. Assign a correlation ID so old and new outputs can be compared without logging secrets or unnecessary prompt content.
A useful shadow report separates:
- hard-gate failures;
- quality changes by task segment;
- p50 and p95 latency;
- input, output, and cached tokens;
- provider errors and timeouts; and
- proposed tool calls.
Do not promote solely because average quality improved. Review the worst regressions and the highest-impact routes before increasing traffic.
5. Update token, cost, and capacity budgets
Replacement models can change tokenization, reasoning-token accounting, prompt caching, context limits, maximum output, batch support, and rate-limit tiers. Recalculate the system rather than copying the retired model’s values.
For each route, estimate cost from observed input, output, cache, and retry usage. Then load-test within the applicable provider limits. A larger context window does not mean the application should automatically send more context, and a lower list price does not guarantee a lower bill if outputs grow or cache hits fall.
Check batch and asynchronous workloads independently. They may use different endpoints, quotas, completion windows, or supported model lists. If the migration touches offline processing, compare the operational differences between OpenAI Batch and Claude Message Batches before assuming the interactive path and batch path can switch together.
Set explicit promotion limits for spend per request, p95 latency, error rate, and token growth. Treat these as workload-specific engineering thresholds, not provider guarantees. Update alerts, dashboards, capacity plans, and budget alarms before shifting production traffic.
6. Keep a rollback plan that can actually run
A rollback plan is credible only while the old route remains available and someone has rehearsed it. Put model selection behind a controlled configuration or feature flag, but version the prompt, parser, tool schema, and safety policy with it. Rolling back only the model ID may fail if the migration also changed request shape or output parsing.
Define:
- the person authorized to roll back;
- the metrics and hard failures that trigger it;
- the exact configuration bundle to restore;
- how to drain or reconcile in-flight requests;
- how queued and batch jobs will be handled;
- how to prevent duplicate side effects; and
- the latest time at which the old model can still serve as the rollback target.
Keep an independent fallback if the old model’s retirement is close. That might be a second validated model, a reduced-function path, or a queue that pauses non-urgent work. Do not describe a retired model as a fallback after its shutdown date.
Perform one rollback drill before the cutover. Measure configuration propagation time and confirm that dashboards identify which model handled each request. If rollback would violate a newly required data or API contract, document a forward-fix procedure instead of pretending reversibility exists.
7. Verify production and close the migration
Move traffic in stages—such as internal, low-risk, partial, then full—only when the previous stage meets its gates. The exact percentages and observation periods should follow workload volume and incident risk; there is no universal safe rollout schedule.
During and after cutover, verify:
- no calls reach the deprecated identifier across online, batch, scheduled, and disaster-recovery paths;
- quality gates remain within approved thresholds by route and user segment;
- schema, tool-call, refusal, timeout, and retry behavior is stable;
- token use, cache hit rate, latency, rate limits, and cost match the revised budget;
- alerts and runbooks refer to the active model; and
- support and incident teams know what changed.
Keep watching after 100% rollout because low-frequency paths may take days to appear. Query logs and provider usage again, then remove the old model only after the rollback window closes. Archive the provider notice, test evidence, approval, deployment record, and final verification date.
Migration gate summary
Use this table as a release record, not as a substitute for workload-specific thresholds.
| Gate | Minimum evidence | Stop condition |
|---|---|---|
| Inventory | Observed usage plus code, configuration, batch, and recovery-path searches | Any ownerless or unidentified model call |
| Scope | Official notice, checked date, platform, exact ID, and shutdown date | Platform or affected API surface is unclear |
| Equivalence | Versioned evaluation set, raw outputs, and separate hard gates | Schema, safety, or side-effect gate fails |
| Shadow | Read-only isolation, correlation IDs, and capped traffic and spend | Candidate can create external side effects |
| Capacity | Measured p95 latency, errors, tokens, retries, and per-request cost | Approved operational budget is exceeded |
| Rollback | Tested configuration bundle and named decision owner | Old route is unavailable and no validated fallback exists |
| Production | Staged rollout plus usage-log confirmation across every path | Deprecated traffic or a high-impact regression remains |
If a second provider is part of the fallback plan, validate its data boundary, quotas, behavior, and cost independently. Designing an LLM fallback strategy covers that wider reliability decision.
Frequently asked questions
What happens if we keep calling a model after its retirement date?
The documented outcome depends on the platform, but retired-model requests generally fail rather than migrate automatically. Confirm the behavior and error code in the platform-specific notice, then make sure alerts distinguish retirement failures from ordinary transient errors.
Is changing the model ID enough?
Usually not. The replacement may differ in request fields, output shape, tool calls, context and output limits, latency, token accounting, rate limits, or safety behavior. Version and test the prompt, parser, tools, and operational limits with the ID.
Should we use the provider’s recommended replacement without evaluating it?
Treat it as the first candidate, not as automatic equivalence. Test it on representative permitted inputs and keep schema, unsafe actions, and other critical requirements as separate pass/fail gates.
How early should a model migration start?
Start as soon as the affected workload and official deadline are confirmed. The necessary lead time depends on traffic, risk, evaluation coverage, and whether both models can run in parallel; the retirement date should be the completion deadline.
Can the old model remain our rollback after cutover?
Only until its platform-specific shutdown and while access still works. As that date approaches, validate another model, a reduced-function path, or a safe queue for non-urgent work. See the token-budget and circuit-breaker patterns for agents for limiting failures while a fallback is active.
The final checklist is short: inventory, scope, equivalence tests, safe shadowing, revised budgets, rehearsed rollback, and production verification. Completing those steps before the provider deadline turns a forced model change into a controlled release rather than an emergency string replacement.