Gemini 2.5 migration: validate before the December 1 API reroute

1. Two dates, two replacement paths

The Gemini API release notes dated November 2, 2026 say that Gemini 2.5 Pro and 2.5 Flash are deprecated and no longer selectable in Google AI Studio. The API change is scheduled for December 1: requests to gemini-2.5-pro will route to gemini-3.8-flash; requests to gemini-2.5-flash will route to gemini-3.5-flash-lite, billed at the replacement model's rates.

As of this article's November 4 review, legacy API access is restricted to users who actively used those models previously. The separately named gemini-2.5-flash-lite is not covered by that deprecation. Do not treat a successful old-model request today as evidence that its behavior will remain unchanged after the deadline. The notice does not specify an exact cutoff time or timezone.

These are Gemini Developer API and AI Studio statements. They do not establish identical schedules for the Gemini consumer app, a subscription entitlement or every Vertex AI deployment. Put the service surface and project owner next to each migration ticket before assigning a replacement.

Google: November 2 Gemini API release notes · Google: deprecation, access and rerouting schedule

2. Inventory the contract before changing the model string

Search application configuration, background workers, notebooks, batch jobs and your own gateway aliases. An environment variable may say 'pro' while a gateway or task runner resolves it differently. Record the configured model and any model identity exposed by the response; an HTTP 200 alone cannot tell you whether the intended route was exercised.

Keep model migration separate from endpoint migration. Google still supports GenerateContent; Interactions is the recommended interface for new projects. Changing the model, SDK, endpoint, prompt and tool protocol in one release makes a failed replay hard to explain. First freeze a reproducible baseline, then move one axis at a time.

• Record endpoint, model ID, SDK version, prompt version, tool-schema digest and request defaults for every entry point.
• Identify state ownership: SDK chat history, application-managed content parts, stored Interactions or stateless step replay.
• Separate read-only work from actions that send messages, update records or incur charges; use mocked effects during replay.
• Assign a task owner, an acceptance rubric and an approved data set. Do not copy customer credentials or unredacted conversations into the migration repository.

Google: Interactions state, per-turn settings and storage · Google: API key, project and credential boundaries

3. Replace assumptions with a request-compatibility matrix

The current migration guides describe request changes as well as model replacement. Some deprecated sampling parameters are ignored on the documented generation and may become errors on later generations; that is different from claiming that every such request already fails. Remove them deliberately and validate the behavior that previously depended on them.

This matrix is a proposed application review. A valid request is only the first gate: it does not prove stable business output, equivalent reasoning effort or lower total spend. Keep a failure fixture for each removed assumption so a future shared-wrapper change cannot silently reintroduce it.

Google: Gemini 3.8 Flash migration checklist · Google: Gemini 3.6 / 3.5 Flash-Lite API changes

4. Make thinking effort explicit, then test it

Gemini 3.8 Flash accepts low, medium and high thinking levels; medium is the default, and minimal is unsupported. Do not reuse a Flash-Lite setting indiscriminately. A router must validate a model-and-level pair rather than append the same configuration to every model.

The following is an unexecuted Interactions REST request body for a synthetic read-only case, sent to POST https://generativelanguage.googleapis.com/v1beta/interactions with a server-side API key. It illustrates request shape, not a production configuration or measured result. store=false avoids stored interaction chaining; it is incompatible with background execution and later previous_interaction_id continuation. It is not a universal promise of zero provider retention.

Compare low and medium against the same acceptance cases before escalating effort. Keep output limits, timeouts and tool-call budgets as separate controls. A short maximum output can truncate the deliverable; it should not be used as a substitute for choosing reasoning effort.

{
  "model": "gemini-3.8-flash",
  "store": false,
  "input": "Synthetic fixture: list the duplicate IDs in [7, 3, 7]. Do not call external tools.",
  "generation_config": {
    "thinking_level": "low"
  }
}

Google: Gemini 3.8 Flash migration checklist · Google: Interactions state, per-turn settings and storage · Google: November 3 cost-per-task routing experiment

5. Preserve signatures across actual tool turns

A thought signature is opaque protocol state. It is not an answer, an instruction to obey or a readable reasoning transcript. In GenerateContent, signatures can be attached to content parts. In Interactions, thought steps and certain built-in-tool steps carry the relevant state. Rebuilding history from visible text discards information that the next turn may need.

For stored Interactions, previous_interaction_id lets the server manage that state. With stateless replay, resend the returned thought steps unchanged, including relevant built-in-tool signatures. Keep the two representations separate; do not invent a universal signature field or translate, summarize or reconstruct an opaque value.

• Replay at least a user request, a model tool call, a tool result and a final answer; a one-turn greeting cannot validate state continuity.
• Test streaming and non-streaming independently. Preserve completed protocol events, including the signature delta; visible text arriving does not establish a complete turn.
• Add negative fixtures for a dropped thought step, a truncated signature and a serializer that strips unknown fields. Record the actual error or incorrect continuation rather than assuming one HTTP status across all APIs.

Google: thinking, signatures and streaming state

6. Match tool results and stop duplicate side effects

In the Interactions protocol, a function_result identifies the matching function call through call_id and the function name. Give every call exactly one matching result in your adapter, including explicit failure results. Do not match parallel results solely by array position: two calls may have the same function name but different arguments.

Correct protocol matching does not provide business idempotency. If a write succeeded but the network response was lost, retrying the whole agent turn can repeat the action. Maintain a separate business operation key and an effect ledger; a model-generated call ID alone is not a durable transaction identity. For a migration replay, replace writes with a stub that records intended effects and rejects duplicates.

With Interactions, tools, system_instruction and generation_config are interaction-scoped even when history is chained. Reapply the intended policy and configuration on each turn. A preserved conversation is not proof that a previous turn's tool permissions or thinking setting were inherited.

Google: function calling and matching tool results · Google: Interactions state, per-turn settings and storage

7. Validate the output contract and every modality

Structured output constrains shape, not the truth of a value. Keep client validation for identifiers, dates, arithmetic, allowed enums and business relationships. The documented schema subset does not enforce every JSON Schema constraint, so an application must not delegate all length or uniqueness checks to constrained decoding.

Both target model references list text, image, video, audio and PDF inputs with text output. Reading audio is not generating speech, and reading an image is not generating an image. A migration for a Live, speech-generation or image-generation endpoint needs its own model-specific review rather than these text-model replacements.

• For documents, use a known page and answer key; require the value and its evidence location rather than fluent prose alone.
• For charts, include an ambiguous axis or unit and accept an explicit uncertainty response instead of a guessed number.
• For JSON extraction, test missing data, duplicate IDs and extra fields; validate both serialization and domain rules.
• For tool-supplied media, verify that the adapter preserves the correct content type and payload, not merely a filename or text description.

Google: structured outputs and schema limitations · Google: Gemini 3.8 Flash model capabilities · Google: Gemini 3.5 Flash-Lite model capabilities

8. Build a replay suite that can reject a plausible answer

Use synthetic or approved de-identified cases with fixed tool responses, then keep a separate held-out set that nobody uses to tune the prompt. Store each case's expected outcome and the reason it matters. Grade an evidence-backed answer, a correctly rejected request and a safe handoff as distinct outcomes; do not count every completed response as a successful task.

The matrix below is an original test design, not a report of tests we ran. Select release thresholds before seeing candidate results. Report results by workflow and failure severity so easy extraction cases cannot hide a duplicate payment, a leaked identifier or a failed multi-step tool sequence.

Google: thinking, signatures and streaming state · Google: function calling and matching tool results · Google: structured outputs and schema limitations

9. Count accepted work, including failed attempts

Google's November 3 engineering article examines routing by cost per successful task. Its 50-prompt, single-run-per-setup experiment is a vendor-published case study with limited grading, not our benchmark or a production guarantee. Its useful prompt for engineering is to compare the whole task rather than only a token price.

For your own evaluation, sum actual billed model usage, router calls, retries, external tools and any separately metered infrastructure for the evaluation window. Divide by tasks that pass the independent acceptance rubric. If none pass, report 'no accepted tasks' and the spend; do not divide by zero or silently remove those attempts. Avoid double-counting thinking tokens already included in a billing total.

Record input, output, thinking and cached-token metrics as diagnostics alongside the reconciled charge. Compare current and announced future rate periods without assuming that an introductory rate lasts forever. Also report latency distribution, retry count, tool effects and handoffs: a low average bill can conceal a workflow that regularly needs manual repair.

cost_per_accepted_task = total_reconciled_task_cost / accepted_tasks

# Suggested evaluation record; application-defined, not Gemini API fields
case_id, model, endpoint, sdk_version, prompt_digest
thinking_level, state_mode, tool_schema_digest
accepted, failure_category, latency_ms, retry_count
reconciled_cost, rate_date, cache_condition, intended_effects

Google: Gemini Developer API pricing · Google: November 3 cost-per-task routing experiment

10. Add a router only when it beats a simpler baseline

First compare a small set of fixed policies: Flash-Lite for the full eligible workload, 3.8 Flash at low, and 3.8 Flash at medium. Retain quality requirements and the same test set. Only then compare a router that chooses among those supported combinations. Otherwise an elaborate router can look economical merely because the baseline was poorly configured.

A router should separate observable properties, such as whether a task needs sequential tool results or handles a write, from vague labels such as 'easy'. Route uncertain or high-consequence work to a verified path or human review. Do not let prompt length alone decide complexity: a short state simulation can require more reasoning than a long direct extraction.

Evaluate warm and cold context separately, and retain enough metadata to explain model switches. Routing can change the amount of reused context and the compatible conversation state. Test a switch mid-session rather than assuming that a successful fresh request proves continuity. The next model must accept the modalities already present in the conversation.

• Keep routing rules versioned and tune them on a development set, then freeze them before held-out evaluation.
• Include router expense, escalation retries and abandoned cheap-path work in the same task ledger.
• Use a bounded escalation path and a terminal handoff; two agents repeatedly asking each other to try again is not recovery.
• Adopt the router only if it preserves the predeclared acceptance level and improves the operational metric you actually need. No savings percentage is assumed.

Google: Interactions state, per-turn settings and storage · Google: November 3 cost-per-task routing experiment

11. Roll out with a fallback that survives December 1

Replay read-only work first, then run shadow comparisons with side effects disabled. A shadow path must not send the same email, update the same record or repeat a charge. Move a bounded cohort to the new configuration only after its specific acceptance suite passes; make the route and failure category observable.

After the announced reroute, changing the configuration back to gemini-2.5-pro or gemini-2.5-flash will not restore the former model. A real fallback is a currently supported configuration that has already passed the required cases, or an approved human queue. Keep the old adapter only as long as it remains useful and supported; do not present retained code as retained provider availability.

• Set stop conditions for duplicate effects, broken evidence links, persistent invalid requests and task-budget overruns.
• Test fallback with the same data restrictions and tool permissions; a rescue route must not quietly broaden access.
• Finish the migration before the deadline rather than betting on an undocumented cutoff timezone or extension.

Google: November 2 Gemini API release notes · Google: deprecation, access and rerouting schedule

12. Leave a release record another engineer can reproduce

A useful migration record contains the source-review date, affected routes, exact target configurations, fixture hashes, grading rules, failure examples and rollback owner. Separate measured results from planned checks. For this article, the documentation was reviewed on November 4, 2026; the request body, matrices and deployment flow are unexecuted examples, with no claim of account eligibility, quotas, latency or savings.

Use the following work brief with your own approved project. It asks for concrete artifacts and stops before live side effects. Replace any production transcript with synthetic fixtures unless your organization has approved another data route. Check the current official references again at implementation time because model schedules and supported request fields can change.

Review this application's Gemini 2.5 migration without calling paid APIs or changing production.
1. Inventory model IDs, endpoint, SDK version, prompts and tool adapters.
2. Map each affected route to an explicit supported target and thinking level.
3. Identify prefilled model turns, removed parameters and discarded protocol state.
4. Propose synthetic fixtures for sequential/parallel tools, partial streams and duplicate effects.
5. Produce an acceptance matrix, cost ledger and fallback-validation plan.
Label each item as verified from code, supported by dated official docs, inferred, or still unknown.

Google: November 2 Gemini API release notes · Google: Gemini 3.8 Flash migration checklist · Google: Gemini 3.6 / 3.5 Flash-Lite API changes · Google: API key, project and credential boundaries