Gemini 3 in Google's API requires migration for agents still running on 1.5 or 2.0

The changelog nobody reads (but should)

Google maintains, within the Gemini API documentation (ai.google.dev/gemini-api/docs/changelog), a chronological record of everything that changes in the API: new models, removed parameters, discontinued endpoints. It's a tedious document to read, but it's where the real breaking changes show up, the ones that take down production pipelines without any headline warning. Combing through that changelog closely, you can put together a migration roadmap for anyone who built agents or RAG on Gemini 1.5 or 2.x and now needs to decide whether (and how) to move up to the 3.x family.

Gone: temperature, top_p, and top_k

The quietest and most dangerous change is recorded in the entry from July 21, 2026, alongside the GA release of Gemini 3.6 Flash: the sampling parameters temperature, top_p, and top_k were marked as deprecated (the changelog doesn't state that support was actually removed, only that it was deprecated). The token-efficiency improvement that the changelog itself links to resolving developer feedback about output verbosity is attributed to the Gemini 3.6 Flash model itself, not to this specific parameter deprecation, but the practical effect of deprecating these controls is bigger than it looks.

Anyone building RAG usually pins temperature=0 precisely to reduce variation and force the model to stick to the retrieved context instead of "creating." If that control actually stops working down the line (deprecation usually precedes removal), every regression test that compared response determinism against a fixed-temperature baseline loses its reference point. Before swapping the model, it's worth running the same battery of validation prompts against the new model and comparing response variance yourself, because the documentation doesn't spell out what sampling behavior became the default.

Gemini 2.0 is the past, with a firm deadline

The changelog is blunt: gemini-2.0-flash, gemini-2.0-flash-001, gemini-2.0-flash-lite, and gemini-2.0-flash-lite-001 were discontinued on June 1, 2026, with an explicit recommendation to migrate to gemini-3.5-flash or gemini-3.1-flash-lite. This isn't a warning about some eventual deprecation, it's a model that's already been pulled offline.

For anyone with agents in production, the first practical step is to grep the codebase for hardcoded model IDs. Aliases like gemini-flash-latest hide exactly this kind of version swap under the hood, so teams that pinned the explicit version for predictability now have to actively decide when to migrate, instead of getting the change for free (and without warning) via the alias.

Tool calling gets a dedicated path

Two changelog entries matter directly to anyone relying on function calling. On February 19, 2026, Google launched a separate endpoint, gemini-3.1-pro-preview-customtools, built for people who mix bash execution with custom tools and need the model to better prioritize its own tools instead of falling back to the native execution environment. Then, on March 18, 2026, came the ability to combine Gemini's native tools (search grounding, Google Maps) with custom function calling in a single call.

In practice, this removes a classic agent-architecture limitation: previously, if you needed search grounding as well as your own database tool, that often meant two separate calls or orchestration logic in your own code to decide which one to use. Now you can declare both in the same payload and let the model choose. It's worth rereading the schema definition of the tools already in your agent, because mixing a native tool with a custom tool can change the priority order the model applies when deciding which one to call first.

Agents running in Google's own sandbox

On May 19, 2026, the Managed AI Agents feature entered public preview on the Gemini API: autonomous, stateful agents running in Google-hosted Linux sandbox environments, isolated from the rest of the developer's infrastructure. Alongside it came the Antigravity Agent, a general-purpose agent capable of planning, writing and executing code, managing files, and browsing the web, all inside the managed container itself.

For teams that currently maintain their own sandbox infrastructure (ephemeral Docker containers, shell permission policies, resource limits) to run agents safely, this is an alternative worth evaluating: outsourcing isolation to the model provider instead of operating it in-house. The obvious trade-off is that the feature is still in preview, not GA, so it's not prudent to bet critical production SLAs on it before Google confirms stability.

Cost and latency: new levers, no published benchmark

The editor's request for latency and cost-per-token figures runs into a real limit of the source: the changelog documents what changed, not by how much. On April 1, 2026, the Flex and Priority inference tiers arrived, meant to optimize for cost or latency depending on the need, but without any comparison table published there. The Flash-Lite family (gemini-3.1-flash-lite, GA on May 7; gemini-3.5-flash-lite, GA on July 21) was designed as a cheap, low-latency sub-agent for high-volume automation, but again, the changelog didn't pin down any reference numbers.

The honest path here is to test it yourself, comparing the same prompt against the old and new model and reading the usageMetadata that the API response already returns:

import time
from google import genai

client = genai.Client()

for model in ["gemini-2.0-flash", "gemini-3.5-flash"]:
    start = time.time()
    resp = client.models.generate_content(
        model=model,
        contents="Resuma este contexto de RAG em 3 pontos: ..."
    )
    elapsed = time.time() - start
    print(model, elapsed, resp.usage_metadata.total_token_count)

Running this against your own set of production prompts (not a generic benchmark), the number you get out is worth more than any marketing claim, because it reflects your real context, your prompt size, and your tool-calling rate.

RAG gets multimodal search, and video gets cheaper in tokens

Two entries directly affect anyone maintaining a RAG pipeline. On May 5, 2026, File Search started supporting multimodal search: images can now be indexed natively with the gemini-embedding-2 model, and grounding metadata now includes media_id to cite the visual source and page_numbers indicating where the information was found. This closes a common gap in RAG that mixes PDF with images: previously, citing the exact page a response grounded in visual content came from required your own custom logic.

On September 1, 2026, came Agentic Video Understanding for the Gemini 3.7 Flash, 3.6 Flash, and 3.5 Flash-Lite models: instead of processing an entire video frame by frame, the model dynamically navigates the timeline and requests transcript, frame, or audio track only when it needs to, cutting token consumption by up to 88% for long-form content. For anyone indexing corporate video or meeting recordings as a RAG source, this is the change that actually lowers cost, more than any single text-model swap.

What's still left hanging

The Interactions API schema change (from outputs to steps), which became the default on May 26, 2026, with the old version removed on June 8, is a hard break for anyone parsing an agent's step-by-step output: any code that read outputs directly breaks without warning at runtime, not at build time. The changelog points to a migration guide but doesn't publish the schema diff there itself, so it's worth testing against a staging environment before touching production. With the release cadence going from 3.1 to 3.8 in a few months, pinning the explicit model version and revalidating on every swap stopped being a best practice and became a condition for the pipeline's survival.