Model IDs, aliases and deprecations: keeping your agent on the model you tested
Claude, OpenAI and Gemini each name and retire models differently. Here is what a pinned ID actually guarantees on each platform as of November 2026, which retirements land in the next few weeks, and how to catch a model change before your agent does.
Some links are affiliate links; we may earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Disclosure
Most agent bugs that show up "out of nowhere" have a boring cause. Somebody changed something. Sometimes it is your prompt, sometimes a tool schema, and sometimes it is the model itself, either because the string in your config quietly points at a newer release, or because the provider retired the old one and your requests started failing or getting rerouted. An agent is more exposed to this than a chatbot, because a small shift in how the model picks tools or formats arguments compounds over a twenty-step run.
So this post skips the question of which model is best (that is what our model table is for) and looks at a plainer one: when you put a model string in your code, what exactly are you getting, how long will you keep getting it, and how do you find out before it changes? The three big APIs answer those questions in different ways, and the differences matter.
What a model ID promises on the Claude API
Anthropic's Model IDs and versioning page is the clearest of the three. It says each Claude model ID identifies a pinned version, and that "the underlying model remains constant for the lifetime of that ID." Starting with the Claude 4.6 generation, IDs dropped the date and follow the pattern claude-{name}-{major}[-{minor}], so you see strings like claude-sonnet-5-5 and claude-opus-5.
The page spends a whole section on a misconception worth repeating: a dateless ID like claude-sonnet-4-6 is not an evergreen pointer to the newest model. It is the snapshot. Anthropic says it does not update the weights or configuration of an existing ID, and that an updated version ships under a new ID. Older models work the other way. Before 4.6, IDs carried a date, like claude-sonnet-4-5-20250929, and the Claude API also accepted a shorter alias such as claude-sonnet-4-5 that "points to the most recent dated snapshot for that minor version." If you still have one of those short aliases in a config file from last year, you were trusting a pointer, not a pin.
There is one honest caveat on the same page. Weights are fixed per ID, but the serving infrastructure around them, including the request router, safety classifiers and sampling logic, can change. Anthropic says infrastructure updates occasionally produce minor differences in observable behavior even when the ID and weights have not changed, and that this is the most likely cause if a stable ID suddenly acts differently. Pinning removes the big source of drift, not every source.
Claude retirements, and the one due this month
The Claude model deprecations page uses four states: active, legacy, deprecated and retired. A deprecated model still works but has a replacement and a retirement date. A retired one does not work at all, and the page is blunt that "requests to models past the retirement date will fail." Anthropic says it gives at least 60 days' notice before retiring publicly released models, by email to customers with active deployments and in the docs.
The date to know right now is November 30, 2026. That is when claude-sonnet-4-5-20250929 retires on Anthropic-operated platforms, with claude-sonnet-5-5 listed as the recommended replacement. Anthropic notified developers on September 30. If your agent still calls Sonnet 4.5, you have a little over two weeks. Two other rows deserve a look. claude-opus-4-5-20251101 is active with a tentative retirement "not sooner than November 24, 2026," and claude-haiku-4-5-20251001 is active with a date of not sooner than October 15, 2026, which has already passed. Neither is deprecated yet, but a "not sooner than" date that has arrived is a strong hint to start testing a replacement now rather than when the email lands.
The page also notes that partner platforms set their own schedules. Amazon Bedrock and the Google-managed Claude offering on Google Cloud keep separate lifecycle tables, so the same model can have a different status and date there. If you run Claude through Bedrock, check Bedrock's dates, not Anthropic's.
Finding your own exposure is easy. The deprecations page says to open the Usage page in Claude Console, click Export, and read the CSV, which breaks usage down by API key and model. That is the quickest way to learn that some forgotten cron job is still on a retiring snapshot.
OpenAI: three notice periods and a field you can poll
OpenAI's deprecations page uses three states: active, deprecated and shutdown. The useful part for planning is the notice table. Unless safety or compliance concerns force a faster timeline, generally available models get at least six months' notice. Specialized variants, such as chat, Codex and deep research versions, plus image generation models, get at least three months. Preview models, which have preview in the name, "may be retired with much shorter notice, such as 2 weeks," and OpenAI says outright that it does not recommend them for business-critical production work unless you can migrate on short notice.
The page lists a big batch shutting down on December 11, 2026: gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-pro, o3 and o3-pro, along with their dated snapshots. The listed replacements are gpt-6.1-sol for gpt-5 and o3, gpt-6.1-terra for gpt-5-mini, gpt-6-luna for gpt-5-nano, and gpt-6.1-sol with reasoning.mode: pro in the Responses API for the two pro models. Behind that, GPT-4o, GPT-4o mini, GPT-4.1 and GPT-4.1 mini snapshots shut down on January 14, 2027, with gpt-6-luna as the replacement. Fine-tuned versions follow the same schedule as their base models, which is easy to forget if your agent runs on a fine-tune.
The page also lists feature shutdowns that hit agent builders directly. On November 30, 2026, the /v1/prompts endpoint and reusable prompt objects go away (the advice is to move prompt content into your own code), and Agent Builder is deprecated in favor of the Agents SDK or ChatGPT Workspace Agents.
The best detail on the page is a small one. To monitor shutdowns programmatically, OpenAI says to call the List models endpoint, GET /v1/models, and check each model's optional shutdown_date field, which is also on the Retrieve a model endpoint. That turns deprecation tracking from "remember to read a web page" into a check you can run on a schedule.
Gemini: four kinds of names, and rerouting instead of failing
Google's models page sorts names into stable, preview, latest and experimental. A stable name such as gemini-3.6-flash points to a specific model that usually does not change, and Google says most production apps should use one. Preview models can be used in production but may have tighter rate limits and can be deprecated with at least two weeks' notice. A latest alias such as gemini-flash-latest "will get hot-swapped with every new release," with a two-week email notice before the model behind it changes. Experimental models are not meant for production.
The more surprising part is what Google does at end of life. The models page says gemini-2.5-pro is deprecated and that, effective December 1, 2026, all API requests to it "will automatically route to" gemini-3.8-flash. The same happens with gemini-2.5-flash, which routes to gemini-3.5-flash-lite on that date. The deprecations page shows this pattern for older 3.x models too: gemini-3.5-flash and gemini-3.7-flash keep their endpoints but route requests to gemini-3.6-flash and gemini-3.8-flash. Google also notes that the shutdown dates in its tables are the earliest possible dates, with exact dates communicated later.
Rerouting is kinder than a hard failure in one sense, since your agent keeps running. But for an agent that is a mixed blessing. A 404 is loud. A silent switch to a different model, sometimes a smaller tier than the one you picked, changes tool selection, output length and cost without a single error in your logs. If you test on gemini-2.5-pro today, what runs on December 2 is a different model.
A pinning routine that fits in an afternoon
Put the model ID in one config value per agent role, not scattered through the code, and use the most specific ID each provider offers: a dateless or dated snapshot on Claude, a dated snapshot on OpenAI where one exists, and a stable name on Gemini. Avoid latest, chat-latest and preview names for anything that runs unattended.
Log the model on every call. Each API returns the model name in its response, so record what came back, not just what you asked for. On Gemini in particular, that is the only way to notice you were rerouted.
Run a weekly check against the sources above. For OpenAI that can be a script that reads shutdown_date from GET /v1/models for every ID in your config. For Claude and Gemini, compare your IDs against the deprecation tables, and on Claude pull the Console usage export now and then.
Finally, keep a small eval set of real agent tasks and run it on the replacement model well before the retirement date. Anthropic and OpenAI both recommend this in their migration guidance, and it is the part that actually protects you. A new model with a better leaderboard score can still break the one tool call your workflow depends on. Chip Huyen's AI Engineering has a solid chapter on building evaluation pipelines if you want a structured way to do it.
Do those four things and a deprecation email becomes a scheduled chore, not a Monday-morning incident.
Sources
Anthropic, Model IDs and versioning: https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions. Anthropic, Model deprecations: https://platform.claude.com/docs/en/about-claude/model-deprecations. OpenAI, Deprecations: https://developers.openai.com/api/docs/deprecations. Google, Gemini models: https://ai.google.dev/gemini-api/docs/models. Google, Gemini deprecations: https://ai.google.dev/gemini-api/docs/deprecations. All pages checked November 14, 2026.