Your AI model is being retired: how to migrate before the shutdown date

Key points

• After the shutdown date, requests to a retired model fail. There is no grace mode to rely on.
• Find every place the model name appears: code, config, background jobs, scripts and outside tools.
• Build the evaluation set from real cases before you switch, not after.
• A newer model can reject settings the old one accepted, and it can format answers differently.
• Roll out behind a flag, keep a fallback to another active model, and make the model name a config value.

How model deprecation works

Model providers retire older models as new ones launch. The words differ a little between providers, but the stages are the same: a model stops getting updates, then it is deprecated with a shutdown date and a recommended replacement, and on that date it is switched off.

OpenAI and Anthropic email the accounts that use a deprecated model, and every provider lists deprecations on its own page. OpenAI states that preview models can be retired on much shorter notice than generally available ones, which is a reason to keep preview models out of anything customers rely on. A real example: on September 30, 2026, Anthropic told developers using Claude Sonnet 4.5 that it would be retired on its API on November 30, 2026, and recommended a newer Sonnet model as the replacement.

Two details catch teams out. Whole APIs are retired too, not only models: OpenAI’s deprecations page lists its Assistants API, with the Responses and Conversations APIs as the replacement. And the same model can follow a different schedule on a cloud platform: Anthropic notes that partner platforms such as Amazon Bedrock set their own retirement dates.

Find every place you use the model

The model being retired is rarely used in only one place. Before choosing a replacement, make a list of every call. Start from the provider’s side, then search your own code. Anthropic’s console, for example, can export usage broken down by API key and model, which shows calls you may have forgotten.

• Application code and configuration files, including every hard-coded model name.
• Background jobs, scheduled tasks and queues that call the model away from the main app.
• Evaluation scripts, data pipelines and internal tools.
• Automation and no-code tools that hold their own model setting.
• Other environments: staging, preview builds and older app versions still in use.
• Every API key and account, including ones owned by a former contractor or a separate cloud account.

For each use, write down what the call does, how much traffic it gets, and what breaks if it fails. That list is your migration plan and your order of work.

Build an evaluation set before you switch

The only reliable way to know whether a replacement is good enough is to run it on your own cases. Anthropic’s own advice is to test your application with the new model well before the retirement date. Do this while the old model still works, so you can record what it does today and compare against it.

1. Collect real inputs from logs: typical requests, hard ones, and the ones that went wrong before. Remove personal data first.
2. Write down what a good answer looks like for each, or keep the old model’s answer where it was right.
3. Include the format checks your code depends on: valid JSON, the right fields, the right tool calls.
4. Decide in advance what result is good enough to switch, so the decision is not made by mood on the day.

How to build and grade a set like this, including using a model as a grader, is covered in how to evaluate AI agents.

Compare the candidates

Start with the provider’s recommended replacement, and add one or two others, including a smaller model if the task is simple. Run each on the same evaluation set and compare more than accuracy:

Measure cost per finished task on your own traffic rather than comparing list prices, because token counts and answer length both move. How to reduce LLM costs explains what drives that number.

Prompt and output changes to expect

Swapping the model name is rarely the whole change. Anthropic’s migration guides list settings that newer models reject with an error, such as sampling parameters, or a reply that the app starts writing for the model, both of which older models accepted. Expect some of these:

• Request settings that are no longer accepted, or that now mean something different.
• Instructions followed more literally, or less, so prompts written around the old model’s habits need review.
• Longer or shorter answers, which affects token limits, cost and screen layout.
• Changes in how tools are called and how structured output is returned.
• A different token count for the same text, so check your maximum output and context limits.

Code that checks the shape of every answer survives these changes far better than code that assumes it; see LLM structured outputs. For prompts, prompt engineering vs context engineering covers what to keep in the prompt and what to move into the context you supply.

Roll out behind a flag, with a fallback

1. Put the new model behind a feature flag, so switching back is a setting, not a deploy.
2. Turn it on for internal users first, then a small share of real traffic, then everyone.
3. Watch error rates, format failures, latency, token use and user feedback at each step, against the old model’s numbers.
4. Keep a fallback to a second active model for when the main one errors or times out. Do not fall back to the model being retired: after the shutdown date that fallback fails too.
5. Finish well before the shutdown date, then remove the old model’s name from everywhere on your list.

Make the next migration small

Models will keep being retired, so the useful outcome of this migration is that the next one is easy:

• Make the model name a configuration value, read in one place, never a string scattered through the code.
• Send every model call through one small module, so request settings and output checks live in one file.
• Keep the evaluation set, and run it automatically whenever a prompt or model changes; see what is CI/CD.
• Prefer pinned, generally available model versions in production, and keep preview models for experiments.
• Have someone check the providers’ deprecation pages regularly, and act on the email when it arrives.

In our AI agent development work, the code and the model provider accounts stay in the client’s name, and a named engineer reviews every change, including a model switch.