Migrate to Gemini 3.5 Flash: Three Gotchas Nobody Else Covers

Gemini 3.5 Flash went generally available on May 19, 2026 at Google I/O with stable model ID gemini-3.5-flash, replacing the gemini-3-flash-preview identifier used during the December 2025 to May 2026 preview window. This migration playbook covers the code-level diffs, the pricing math across four migration paths, and the three breaking-change gotchas that no other coverage is publishing — starting with the fact that Computer Use does not migrate to 3.5 Flash.

The stakes are compressed by hard deadlines. gemini-2.0-flashshuts down on June 1, 2026 — eight days from this post's publish date. If your codebase still references gemini-2.0-flash, it stops working next week. On the other end, gemini-2.5-pro has until October 16, 2026 before its shutdown, giving those teams a five-month runway — but the pricing math may make an earlier migration worthwhile. And for Gemini 3 Pro users: that model shut down on March 9, 2026, so anyone on gemini-3-pro-preview has already migrated to gemini-3.1-pro-preview. Gemini 3.5 Flash is now a third option for those teams — a capability downshift in exchange for meaningfully lower cost.

This guide covers the deprecation timeline and urgency, the proprietary pricing matrix across four predecessor models, the SDK and package rename, the three breaking-change gotchas (thinking_level enum, Computer Use, function-calling id requirement), the model routing decision matrix, the Managed Agents API context, and a cost-per-task analysis across five agentic workloads. For benchmark numbers, see the sibling deep-dive: Gemini 3.5 Flash: Benchmarks, Thinking and API Guide— this post does not duplicate that table.

Before choosing a migration path, orient against the actual shutdown dates. These are sourced verbatim from the Gemini deprecations page (retrieved 2026-05-24), not from third-party coverage:

gemini-2.0-flash — shutdown June 1, 2026. Eight days from this post's publish date. Replacement: gemini-2.5-flash. This is the most urgent migration in the Gemini family right now. If you're on 2.0 Flash for a cost-first pipeline — it was priced at $0.10 input / $0.40 output per Mtok — the cost math changes dramatically regardless of which model you move to. See the pricing matrix in Section 02.

gemini-3-pro-preview — shut down March 9, 2026. Already gone. The gemini-pro-latest alias moved to gemini-3.1-pro-preview on March 6, 2026, and Gemini 3 Pro Preview was shut down three days later. If you were on Gemini 3 Pro, you have already completed one forced migration — to gemini-3.1-pro-preview. Gemini 3.5 Flash is now a potential second step: a capability downshift (from Pro-class to Flash-class) in exchange for lower cost. Whether that tradeoff makes sense for your workload is what Section 07's routing decision matrix is designed to answer. For context on the March migration, see the Gemini 3 Pro to 3.1 Deep Think migration playbook.

gemini-2.5-pro — shutdown October 16, 2026. Replacement: gemini-3.1-pro-preview. Five-month runway. This is the longest-runway migration in the current Gemini deprecation schedule. Teams on 2.5 Pro can evaluate 3.5 Flash as a cost-reduction option without urgency pressure. Gemini 3.5 Flash is approximately 17% cheaper on input than 2.5 Pro for prompts under 200k tokens ($1.50 vs $1.25 — note: 2.5 Pro is $1.25 input at ≤200k but $10.00 output vs 3.5 Flash's $9.00; the output saving is real). For deeper benchmarks and capability comparisons, see Gemini 3.1 Pro benchmarks and pricing guide.

gemini-3-flash-preview — no shutdown date announced. This is intentional on Google's part because Computer Use is supported on gemini-3-flash-preview and not on gemini-3.5-flash. Until Google ships Computer Use support on a stable-ID model, gemini-3-flash-preview will remain the only live path for browser- and desktop-control agents.

Every other Gemini 3.5 Flash pricing post compares against a single predecessor. Below is the matrix across all four active predecessor paths, with per-Mtok input/output pricing sourced from the Gemini API pricing page (retrieved 2026-05-24) and a routing recommendation for each path. Gemini 3.5 Flash standard pricing: $1.50 input / $9.00 output per Mtok; $0.15 cached; Batch API 50% off ($0.75 / $4.50). These figures were current as of May 24, 2026 — always verify against the live pricing page before making budget commitments.

One pattern stands out across all four paths: the only migration where cost goes downon both input and output is the 2.5 Pro migration at large context (>200k tokens) — where 3.5 Flash saves 40% on both dimensions. For all other paths, migrating to 3.5 Flash represents a capability upgrade bought at higher cost. Budget models (2.0 Flash, 3-flash-preview) that migrate to 3.5 Flash see dramatic cost increases. Plan accordingly.

Before touching model IDs or API parameters, ensure you are on the current Google GenAI SDK. The old package names are the legacy SDK and will not receive new Gemini 3.x features. The Gemini SDK migration guide (retrieved 2026-05-24) documents the full package transition:

Python — package rename:

# LEGACY (do NOT use for new work)
pip install google-generativeai
import google.generativeai as genai

# CURRENT
pip install -U -q "google-genai"
from google import genai

JavaScript / TypeScript — package rename:

// LEGACY (do NOT use for new work)
// npm install @google/generative-ai
import { GoogleGenerativeAI } from "@google/generative-ai";

// CURRENT
// npm install @google/genai
import { GoogleGenAI } from "@google/genai";

Go — module rename: was github.com/google/generative-ai-go, now google.golang.org/genai.

Client initialization after the rename:

# Python (new SDK)
client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Summarize this document."
)
print(response.text)

// JavaScript (new SDK)
const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Summarize this document.",
});
console.log(response.text);

Source: verbatim from Gemini text-generation docs, retrieved 2026-05-24. For workloads building full agentic pipelines on top of 3.5 Flash, the cross-vendor function-calling guide covers the SDK surface patterns across OpenAI, Anthropic, and Google simultaneously — useful context before the gotchas below.

This is the breaking change that silently misfires for teams that copy-paste code from Gemini 2.5 Pro examples into a 3.5 Flash context. The thinking_budget integer parameter used in earlier Gemini 2.x and some 3.x thinking-mode configurations is replaced by a thinking_level string enum on Gemini 3.5 Flash.

Accepted values: "minimal", "low", "medium" (default), "high". Source: Gemini thinking docs, retrieved 2026-05-24.

Important: Gemini 3.1 Pro does NOT support the "minimal" thinking level — that value is specific to 3.5 Flash. Gemini 3.5 Flash defaults to "medium" rather than the "high"dynamic default that 3.1 Pro uses. Google does not publish a per-thinking-level price discount — the pricing table does not tier on thinking level, so avoid inventing a "minimal-thinking discount" in your cost models.

Python — thinking config migration:

# LEGACY — Gemini 2.5 Pro style (thinking_budget integer)
# config = types.GenerateContentConfig(
#     thinking_config=types.ThinkingConfig(thinking_budget=8192)
# )

# CURRENT — Gemini 3.5 Flash (thinking_level enum)
from google import genai
from google.genai import types

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain this architecture diagram.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    )
)

JavaScript — thinking config migration:

// LEGACY — integer thinking_budget
// thinkingConfig: { thinkingBudget: 8192 }

// CURRENT — enum thinking_level
import { GoogleGenAI, ThinkingLevel } from "@google/genai";
const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Explain this architecture diagram.",
  config: {
    thinkingConfig: { thinkingLevel: ThinkingLevel.LOW },
  },
});

For the full thinking-capability context including benchmark implications, see Gemini 3.5 Flash: Benchmarks, Thinking and API Guide. This post focuses on the migration diff, not the capability depth.

This is the single most consequential gotcha in the entire Gemini 3.5 Flash migration, and it is not mentioned in any mainstream coverage of the I/O 2026 launch. The Gemini 3.5 Flash model page explicitly lists the following as unsupported on gemini-3.5-flash: Live API, Computer Use, Image generation, Audio generation. Retrieved 2026-05-24.

What this means in practice: any team running browser-control agents or desktop-automation agents via the Computer Use API on gemini-3-flash-preview must stay on that model. The stable-ID migration from gemini-3-flash-preview to gemini-3.5-flash is safe for most workloads — but it is a breaking change for Computer Use workloads. Your agent will not throw an error on the API call; it will simply stop executing browser actions.

The good news: gemini-3-flash-preview has no announced shutdown date as of 2026-05-24. Google is preserving it specifically because Computer Use has no migration path to a stable-ID model yet. You can keep Computer Use workloads on gemini-3-flash-preview indefinitely until Google ships Computer Use support on a stable-ID model.

For a broader view of the agentic AI landscape this week — including other Computer Use developments — see the Agentic AI week in review for May 19-23, 2026.

All Gemini 3.x models generate a unique id for every function call they emit. When your code returns results manually via functionResponse, the response object must include the matching id from the original call. Source: Gemini function-calling docs, retrieved 2026-05-24.

If you are using the SDK's automatic tool-use mode, this is handled for you — the SDK reads the id from the model response and attaches it to the function response automatically. The breaking change only affects teams that construct functionResponse objects manually — a pattern common in multi-step agentic loops where the orchestration layer intercepts tool calls and routes them to external services.

Python — function response migration:

# LEGACY — Gemini 2.5 Pro style (no id required)
# function_response_part = types.Part(
#     function_response=types.FunctionResponse(
#         name="get_weather",
#         response={"result": "72°F, sunny"}
#     )
# )

# CURRENT — Gemini 3.x (id required — read it from the function call)
from google.genai import types

# First, capture the function call id from the model's response
function_call = response.candidates[0].content.parts[0].function_call
call_id = function_call.id  # e.g. "call_abc123"

# Then return the result with the matching id
function_response_part = types.Part(
    function_response=types.FunctionResponse(
        id=call_id,          # REQUIRED in Gemini 3.x
        name="get_weather",
        response={"result": "72°F, sunny"}
    )
)

Parallel function calling works identically across 3.x models: the model can return multiple function calls in one turn, and the results can come back in any order — the API maps each result to its originating call via the id. This makes parallel tool-use loops cleaner once you adopt the pattern.

With Gemini 3.5 Flash GA and Gemini 3.5 Pro arriving “next month” (June 2026, per the Gemini 3.5 launch blog), developers face up to four active routing options simultaneously. The matrix below uses capability and cost signals from the research above to assign each workload type to its recommended model.

Alongside Gemini 3.5 Flash GA, Google also released the Managed Agents API into public preview on May 19, 2026. The general-purpose agent identifier is antigravity-preview-05-2026. Source: Gemini API release notes, May 19, 2026 entry. This is the API that backs Antigravity 2.0 — which according to TechCrunch's I/O coverage, ships with gemini-3.5-flash as its default backing model. Developers building agentic loops on 3.5 Flash can route through Managed Agents (sandboxed Linux execution, web browsing) rather than self-hosting an orchestration harness.

Critical deadline for Managed Agents users: May 26, 2026. A breaking Interactions API schema change goes live on May 26, 2026 — three days from this post's publish date. The outputs field becomes steps and the response format config changes. The legacy schema is removed on June 8, 2026. Source: Gemini API release notes, May 6, 2026 entry. If you are building on the Managed Agents API today, this schema break must be in your sprint plan this week.

Gemini 3.5 Flash is also the default backing model for AI Mode in Google Search, which reportedly reaches 1 billion monthly active users as of May 19, 2026. That production scale is the strongest signal that the model's reliability and throughput have been validated at infrastructure scale, not just in benchmarks. For context on the broader I/O week, see our complete I/O 2026 announcement guide. For the post-I/O marketing operations playbook, see the agent-first marketing ops post-I/O playbook.

Pricing tables are abstract. The following analysis runs five representative agentic workloads through the per-Mtok pricing from the Gemini API pricing page (retrieved 2026-05-24) to produce monthly cost estimates. The caching row assumes a 30% cache-hit rate and a one-hour TTL at $0.15 per Mtok for cached input — these are illustrative assumptions, not guaranteed savings. All per-Mtok figures are sourced from ai.google.dev/gemini-api/docs/pricing. Verify live before committing budget.

Methodology: monthly cost = (queries per month) × (tokens per query) ÷ 1,000,000 × (price per Mtok). Cache saving = (30% of input tokens) × ($0.15 − standard input rate). Numbers are rounded to two significant figures. For the ROI framing on AI agent investments, see the sibling AI agent ROI calculator for enterprise business cases.

Two patterns emerge from the workload analysis. First, the only case where migrating to 3.5 Flash delivers clear cost savings versus 2.5 Pro is the long-context workload (800k+ token inputs) — where 3.5 Flash is approximately 39% cheaper because it does not apply 2.5 Pro's >200k surcharge. Second, for any workload that would run on gemini-3-flash-preview, migrating to 3.5 Flash is always a cost increase (the 3× input premium is consistent across all five workloads). The upgrade should be justified by quality requirements, not cost optimization. For teams managing AI agent budgets at scale, our AI transformation services include cost-optimization reviews that run this analysis against your actual production token volumes.