Designing for Model Deprecations with Virtual Models and Staged Cutovers

On July 23, 2026, OpenAI is scheduled to shut down 15 listed model entries — a mix of dated snapshots and aliases spanning Codex, chat, deep-research, search, audio, realtime, and computer-use APIs, per its deprecations page. The immediate task is migration. The durable engineering problem is dependency ownership: application code should not depend directly on identifiers whose lifetimes are controlled by a model provider.

This post describes a safer operating pattern — inventory current usage, place a stable virtual-model alias between applications and provider models, evaluate replacements against workload-specific tests, shift synchronous traffic through a weighted canary, and preserve a fast rollback path.

‍

1. Read the Calendar Like an SRE

OpenAI's deprecations page defines the semantics directly: a model becomes deprecated at the moment of announcement — it still works, but it now has a shutdown date — and once shut down, requests to it no longer resolve. The published notice policy is at least six months for generally available models and at least three months for specialized variants such as Codex and chat-latest models. Preview models may receive notice as short as two weeks, and OpenAI explicitly advises against using previews for business-critical production workloads unless the team can migrate quickly (OpenAI deprecations page).

The April 22 announcement established two concentrated shutdown batches: 15 listed entries on July 23, and on October 23 a further set of legacy GPT-3.5, GPT-4, GPT-4 Turbo, GPT-4.1 Nano, GPT-4o, and o-series snapshots and aliases, along with gpt-image-1 and several fine-tuned base-model families. Note what October 23 is not: it is not the entire GPT-4 family, and it is not the entire o-series — the dated o3-2025-04-16 and o3-pro-2025-06-10 snapshots are listed separately for December 11, and only the gpt-4o-2024-05-13 snapshot appears from the GPT-4o line.

The image-model sequence deserves attention as precedent. When DALL·E 2 and 3 shut down on May 12, OpenAI had listed gpt-image-2, gpt-image-1, or gpt-image-1-mini as recommended replacements. Teams that selected gpt-image-1-mini must now migrate again before its December 1 shutdown, and gpt-image-1 itself is scheduled for October 23. The lesson generalizes: the migration target can also be on the calendar, and an architecture whose response to deprecation is editing model strings everywhere and redeploying will repeat that work on the vendor's cadence.

Nor is this one provider's pattern. Anthropic lists Claude Opus 4.1 for retirement on August 5, 2026, with a documented policy of at least 60 days' notice for publicly released models (Anthropic model deprecations). Google lists October 16, 2026 as the earliest shutdown for Gemini 2.5 Pro, Flash, and Flash-Lite, and one preview model — gemini-3.1-flash-lite-preview — ran from March 3 to May 25, 2026, under three months from release to shutdown (Gemini deprecations). DeepSeek's own API documentation says the legacy aliases deepseek-chat and deepseek-reasoner will be deprecated on July 24, 2026, mapping them for compatibility to the non-thinking and thinking modes of deepseek-v4-flash; it does not identify that date as a shutdown (DeepSeek models and pricing). These four providers all publish active model-lifecycle changes; their notice periods and migration mappings differ.

2. The Inventory Problem: You Cannot Migrate What You Cannot Find

Every migration guide starts with "audit your usage," and every platform team knows why that step slips: model IDs hide in service configs, notebook constants, CI pipelines, framework defaults, coding-agent configuration files, and third-party tools nobody remembers adopting. Grep finds the strings in your repositories; it does not find the volume, the owner, or the traffic that originates outside version control. The reliable census is observational: if every model call crosses one gateway, then per-model usage — split by team, application, user, and virtual account, with cost attached — is a dashboard query, and "who still calls this retiring model" has a live answer with names and dollar figures on it. Anthropic's own guidance points the same direction, recommending customers export per-key, per-model usage audits before migrating. That census is also the prioritization function: a model with three residual calls a day from a forgotten batch job is a ticket; one carrying a customer-facing feature at six figures a month is a project.

3. Indirection: Virtual Models Turn a Redeploy Into a Routing Update

The structural fix is the oldest idea in systems engineering — add a name layer you control between the caller and the thing that changes. In TrueFoundry's gateway the unit is the virtual model: for supported synchronous requests routed through the gateway (chat and Anthropic Messages, Responses, completions, embeddings, rerank, moderation, image, and audio operations), applications call a stable alias such as prod-coding-agent, and operators configure which real models sit behind it, with weight-, priority-, or latency-based routing plus per-target retries and fallbacks (virtual model docs). Under that indirection, a shutdown date decomposes into gateway operations: the census from Section 2 identifies the aliases whose backing models retire, and each alias gets a compatible successor mapped once and centrally. Selecting a compatible backing target does not require changing the model identifier in consuming services — the property that matters most where the consuming services number in the hundreds and their owners in the dozens — though application changes may still be necessary when a replacement requires different prompts, tools, parameters, or output handling.

The gateway's unified, OpenAI-compatible API spanning more than 1,000 models widens the successor search: the bake-off for a retiring model can exercise the provider's suggested mapping alongside Anthropic, Google, or self-hosted open-weight candidates through a common request surface (gateway introduction). A common surface is not equivalence, and it should not be mistaken for it: providers differ in tool-call semantics, structured-output support, accepted parameters, multimodal capability, context limits, safety behavior, tokenization, and pricing — which is precisely why candidates must be evaluated explicitly, per Section 4, rather than assumed interchangeable. One discipline note the image-model precedent teaches: point aliases at pinned snapshots, not at provider-side "latest" aliases. OpenAI's calendar retires chat-latest aliases like any other entry — a name you don't control is still a dependency you don't control.

4. Migration Is an Evaluation Problem: Diff, Canary, Rollback

What indirection does not solve is behavior. Successor models are not drop-in equivalents, and a find-and-replace ships those differences straight to production. The working sequence for one alias looks like this:

1. The application calls prod-coding-agent, never a provider model ID. The virtual model initially routes 100% to the incumbent.
2. Diff. Before any traffic moves, run the incumbent and the candidate offline against your own evaluation set — your prompts, your tool schemas, your acceptance criteria.
3. Canary. Configure a nominal 95/5 allocation on the same alias. For multi-turn workloads, configure sticky routing keyed by a conversation, user, or tenant identifier so a session does not alternate between incumbent and candidate mid-conversation — an important correctness detail for agents and chat, not optional polish. With sticky routing, the initial session assignment follows the weighted policy while subsequent requests stay pinned, so observed request volume can differ from exactly 95/5 when session lengths vary.
4. Judge the canary using two evidence streams. Apply workload-specific quality gates through your evaluation system. In parallel, compare operational measures per backing model in the Metrics Dashboard: error rate and class, latency percentiles (TTFT, ITL, TPOT, P50–P99), request volume, and cost of inference (Metrics Dashboard docs).
5. Advance the candidate to 30%, then 100%. Rollback: before the incumbent's shutdown date, rollback restores its previous weight — a routing-only change that requires no client redeploy, provided the prior target remains available and the request contract is unchanged. After shutdown, the incumbent is inaccessible, so rollback means routing to another active model already validated for the workload.
6. Finalize before shutdown. Set the retiring target's weight to zero and either remove it from the virtual model or set fallback_candidate: false, so the gateway never attempts the inaccessible model on a fallback path. Configure a separate active, evaluated fallback, then use Model Metrics and request logs to confirm that no gateway-mediated traffic still resolves to the retiring model — and separately inspect provider-side usage and repositories for traffic that may bypass the gateway or call the provider directly.

That rollback boundary is worth planning around: the incumbent remains a valid rollback target only until its provider shutdown date, so the canary needs to complete — with margin — before that date. A migration begun close to the shutdown date leaves little time to observe the canary and still roll back to the incumbent.

The configuration below shows the documented shape of that canary, with field names taken from TrueFoundry's virtual-model documentation. One compatibility detail matters here: gpt-5.1-codex is available through OpenAI's Responses API only, and every target behind a virtual model must support the operation associated with its configured model type — so this virtual model is created with model type responses, which GPT-5.5 also serves. Provider-group names vary by deployment; substitute the catalog identifiers configured in your gateway.

Virtual model routing_config — nominal 95/5 canary with sticky sessions

# prod-coding-agent (model type: responses — the incumbent is Responses-only)
routing_config:
  type: weight-based-routing
  sticky_routing:
    ttl_seconds: 3600
    session_identifiers:
      - key: x-conversation-id
        source: headers
  load_balance_targets:
    - target: <openai-provider-group>/gpt-5.1-codex          # incumbent alias — shuts down Jul 23
      weight: 95
      fallback_candidate: true
    - target: <openai-provider-group>/gpt-5.5-2026-04-23     # candidate — pinned dated snapshot
      weight: 5
      fallback_candidate: true

The candidate deliberately targets the dated snapshot gpt-5.5-2026-04-23 rather than the gpt-5.5 alias, per the pinning discipline above. The incumbent illustrates why that discipline exists: OpenAI's current model page lists gpt-5.1-codex as a Responses-only name whose underlying snapshot is regularly updated, and it does not list a separately selectable dated snapshot — exactly the kind of provider-controlled name this migration is escaping.

Sticky sessions pin requests sharing the same session key to one target for the configured ttl_seconds window; if the pinned target fails, healthy fallback candidates are tried and the session stays on the working target for the rest of the window. Every request must include the configured session identifier: if x-conversation-id is missing, it contributes an empty string to the session key, so requests missing the header can collapse into the same session. Size ttl_seconds to cover the expected conversation or workflow duration; once the window expires, the session is re-evaluated and may be assigned to a different target. During the canary, promotion and pre-shutdown rollback are weight changes. Before the incumbent's shutdown, remove or disable the retiring target and retain at least one active, evaluated fallback.

Two documented observability mechanisms close the audit loop. Per request, the gateway returns the actual backing model that served the call in the x-tfy-resolved-model response header, and — when request logging is enabled (configurable as HEADER_CONTROLLED, ALWAYS, or NEVER) — logged requests can be inspected in the Requests view, subject to the configured data-access rules (request logging docs). In aggregate, the Metrics and Routing dashboards provide model and virtual-model groupings of volume, failure rates by error class, cost, latency percentiles, and routing-rule target breakdowns. So when someone asks in November whether the October 23 cutover coincided with a quality dip a customer reported, the dashboards can establish whether the cutover coincided with changes in latency, errors, traffic, or cost; establishing a task-quality regression still requires evaluation results or request-level trace analysis.

A note on evaluation tooling: OpenAI deprecated its Evals platform on June 3 — existing evals become read-only October 31, and the dashboard and API are scheduled to shut down November 30. That retirement reinforces the value of keeping evaluation datasets, scoring logic, and promotion criteria portable across providers rather than coupled to any one vendor's tooling. Online evaluation at the gateway — where a sampled subset of live responses is scored asynchronously over time — is one implementation pattern for this; we describe the architecture in a separate post.

5. Boundaries, Stated Plainly

Dates and model lists above are from the providers' own deprecation pages as of mid-July 2026. Deprecation schedules change, occasionally in the customer's favor, and readers executing a migration should treat the primary pages as authoritative over any secondary summary, this one included. Indirection moves the work of deprecation to a control plane; it does not delete the judgment — choosing successors, defining evaluation criteria, and deciding what quality regression is acceptable remain your team's calls, and a virtual model pointed at a bad successor fails everywhere at once, which is why the canary and evaluation stages carry the weight they do here. The argument is narrower than "avoid the treadmill," which no architecture can: when a dependency's lifetime is set by someone else's roadmap, the caller's side of the interface should be a name you own. TrueFoundry's documented virtual-model routing, sticky sessions, retries and fallbacks, and model-level observability implement this operating pattern for supported gateway-mediated workloads.

References

• OpenAI — API deprecations page (primary source: the July 23, August 26, October 23, December 1, and December 11 shutdown lists; the Evals, Agent Builder, and reusable-prompt timelines; DALL·E replacement mappings; deprecated-vs-shut-down semantics; notice policy); GPT-5.1-Codex model page (Responses-API-only availability; regularly updated underlying snapshot); GPT-5.5 model page (endpoints; the gpt-5.5-2026-04-23 dated snapshot).
• Anthropic — model deprecations (Claude Opus 4.1 retirement, August 5, 2026; 60-day notice policy; usage-audit guidance).
• Google — Gemini deprecations (Gemini 2.5 Pro/Flash/Flash-Lite earliest shutdown, October 16, 2026; gemini-3.1-flash-lite-preview lifecycle).
• DeepSeek — models and pricing (deprecation of the deepseek-chat and deepseek-reasoner aliases on July 24, 2026, and their mapping to deepseek-v4-flash modes).
• TrueFoundry documentation — virtual models (routing strategies, sticky routing, retries and fallbacks, Batch API exclusion, x-tfy-resolved-model); AI Gateway introduction (unified API); request logging (logging modes, Requests view); Metrics Dashboard (model and virtual-model metrics, latency percentiles, cost, routing breakdowns).
• This blog — online evaluation at the gateway (architectural pattern); self-hosting open-weight models behind the gateway; real-time cost attribution.

All schedule details are paraphrased from the providers' public deprecation pages, current as of publication; readers should verify against the primary pages before acting. The migration methodology in Sections 2–4 cites TrueFoundry's public documentation; the configuration example reproduces the documented routing schema; the dashboard image is TrueFoundry's own documentation asset, reproduced with attribution. None of the cited providers evaluates or endorses TrueFoundry.

‍

‍