Treat a model retirement as a production migration, not a model-name edit. A replacement can change tool-call behavior, token usage, safety outcomes, retention eligibility and latency even when its API format stays familiar. The safe path is to inventory every dependency, evaluate the replacement against the work your customers perform, then roll it out with a reversible policy change.
The OpenAI deprecations page records shutdown dates and recommended replacements. It also distinguishes a legacy model from a deprecated model with a shutdown date. That distinction is useful, but it does not remove the need to test a replacement in your application.
Start with the model dependency, not the provider announcement
An engineering team needs a record for each workload that names a model. Search application configuration, scheduled jobs, evaluation fixtures, saved conversations, routing policies and customer-specific overrides. Include the API features the workload depends on, not only the model ID.
| Record | Example question | Why it changes the migration |
|---|---|---|
| Workload | Does this power drafting, classification or a tool-using agent? | A changed response can have different consequences |
| Interface | Does it use streaming, structured output or tools? | A replacement can change response fields or stop conditions |
| Policy | Which customers, regions and retention requirements apply? | An otherwise capable model can be ineligible |
| Evaluation | Which expected outputs and failure cases matter? | A generic benchmark cannot prove your behavior |
| Rollback | What model and configuration will you restore? | A staged release needs a safe exit |
For example, a hypothetical SaaS product uses a retiring model for support-answer drafts and a second model for tool calls. The drafting path may tolerate a style change. The tool path needs argument-schema checks, authorization checks and an evaluation set that includes refusal and malformed-call cases. Calling both workstreams “the model migration” hides the different risks.
Check the replacement's behavioral contract
Read the provider's migration material before you reuse the old request payload. Anthropic's migration guide gives concrete examples: model changes can affect thinking configuration, token accounting, response fields, refusal handling, pricing and data-retention eligibility. Those facts are provider- and model-specific, so record the version and check date with your decision.
Run a representative, authorized evaluation set through both configurations. Compare the outcomes that matter to the workload: task success, refusal path, valid tool-call rate, policy verdict, latency, token count and cost. Do not promote a replacement because one prompt looks better in a console.
| Check | Pass condition to define | Failure to investigate |
|---|---|---|
| Request compatibility | The application accepts the new response and terminal states | A parser treats a refusal as success |
| Policy eligibility | Region, retention and approved-model rules still permit it | A customer receives a model outside its terms |
| Task quality | The agreed evaluation cases meet the stated threshold | A small demo hides a workflow regression |
| Tool safety | Arguments remain valid and authorized | A more capable model calls a broader operation |
| Operations | Budget and latency remain within the service objective | A silent cost or queue increase reaches customers |
These thresholds are product decisions. They are not a claim that a provider's suggested successor will meet them.
Use policy-controlled staged rollout
Put model selection behind a configuration boundary. Alectura policies can allow models and provider regions per customer, and its model catalog exposes the connections available to a request through GET /alectura/v1/models. That gives an application a place to make a customer-specific transition explicit. It does not evaluate model quality or translate between provider formats for you.
Start with a small, selected group that has agreed to the change. Preserve the logical request ID, policy version, selected model and connection in operational records. Compare the new path with your baseline and stop the rollout on the predefined failure conditions. Expand only after the release owner reviews the results.
Avoid a fallback that quietly moves a customer to a model which has not passed its policy and evaluation gates. Alectura retries a permitted fallback after a failure before the provider's first byte; it is not a substitute for deciding that a new model is acceptable for a workload.
Plan for the cases that do not migrate cleanly
Some workloads should remain on the existing model until a date, be redesigned, or be removed. A model that needs retention unavailable to a customer, a missing feature, or a failed safety evaluation is a reason to choose one of those outcomes. Do not add an untested cross-family fallback just to avoid a visible change.
Also test the shutdown day. Confirm that your client shows a clear service state, that an operator can see which configuration failed, and that retry behavior cannot generate duplicate tool actions. A deprecation notice gives time to do this work. It does not guarantee unchanged output or uninterrupted eligibility.
Make the next migration cheaper
Keep the inventory, evaluation results, approval and rollback record after the cutover. Subscribe to the provider's deprecation notices and periodically review the catalog your policies allow. The next migration then starts with known workloads and evidence rather than an emergency search for strings in repositories.
To test a customer-specific model policy against a non-production requirement, start with the Alectura quickstart.