# Gemini 4 Hydrogen migration: test the agent contract, not just the model ID

> The Enterprise Agent Platform migration guide changes reasoning settings, tool transcripts and request fields. Here is a scoped test plan—and what the Gemini Developer API docs do not establish.

- Published: Nov 16, 2026
- Author: PiRouter Team, Engineering
- Tags: models, agents, coding-agents
- Models: [Gemini 4 Hydrogen](https://pirouter.ai/models/google/gemini-4-hydrogen)
- Canonical: https://pirouter.ai/blog/gemini-4-hydrogen-agent-migration

---
*Cover: Google's official launch artwork. [Image source](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/).*

Changing an agent from Gemini 3.8 Flash to Gemini 4 Hydrogen is not necessarily a one-line model-ID edit. Google's [Enterprise Agent Platform migration guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate) calls out reasoning settings, preserved thought signatures, tool-response matching, removed request fields and caching changes. **That is a test checklist for that platform, not proof that every rule or error code also applies to the Gemini Developer API.** A safe cutover exercises the actual endpoint and the whole agent transcript before moving production traffic.

Hydrogen is Google's November 12 release for what it calls a “daily driver for agentic workflows” ([Google's Hydrogen announcement](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/), updated November 13). The [Gemini API model specification](https://aistudio.google.com/docs/models/gemini-4-hydrogen) lists the stable model ID `gemini-4-hydrogen`. Those facts explain why a team might trial it. They do not say whether a particular agent's accumulated conversation, function-call dispatcher or retry loop survives a switch unchanged.

## One model ID, two documentation scopes

There are two official surfaces to read without collapsing them into one contract. The [Enterprise Agent Platform migration guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate) specifically describes moving `gemini-3.8-flash` to `gemini-4-hydrogen` on that platform. It provides explicit instructions for an agent that stores previous model turns and executes tools. Separately, the [Gemini API Hydrogen model page](https://aistudio.google.com/docs/models/gemini-4-hydrogen) describes a stable API model with text, image, audio, video and PDF input, text output, function calling, structured output, Batch API and implicit caching. Explicit caching is not listed as supported for Hydrogen.

The overlap is useful, but not a license to transfer every implementation detail. The [Gemini API latest-model page](https://aistudio.google.com/docs/latest-model) confirms the same four Hydrogen thinking levels. In the API pages checked for this article, we did not find a Developer API-specific Flash-to-Hydrogen guide proving that Enterprise's exact SDK minimums, `thinking_budget` HTTP status, or transcript-replay recipe apply identically. Treat those as **unknown until tested on the chosen API surface**, not as evidence of compatibility or incompatibility.

Keep the migration decision in one small matrix. The first two columns describe the documentation scope; the last is a proposed acceptance test, not a result we obtained.

| Boundary | Enterprise guide | Developer API status in this article | Minimum evidence before cutover |
|---|---|---|---|
| Reasoning and old fields | Explicit levels and removed-field rules | Valid levels documented; exact legacy rejection behavior not established here | The outgoing request is accepted and uses the intended level |
| Stored tool conversation | Signature preservation and call/response matching rules | Confirm the endpoint's representation and replay behavior | Plain, single-call, parallel-call and compacted histories all continue correctly |
| Context and caching | Migration advice for implicit caching | Model specification documents shared context and cache support | Measured usage shows the expected output limit and actual cache-hit tokens |

A passing request is not enough for the second row: the next tool action must also match the intended result, and retrying must not duplicate a write. Those conditions should be checked with stubs or isolated test resources, separately from model-quality evaluation.

This distinction matters most in an agent with a long-lived history. A stateless prompt may appear to work after an ID swap. A tool-using agent can fail on its fifth turn, when a compacted history is replayed or several function results arrive at once. A migration test that ends after the first response never reaches the code that is most likely to change.

## The default reasoning level is a behavior change, not a price change

Hydrogen exposes `low`, `medium`, `high` and `xhigh`, with **high as the default**, according to the [Gemini API thinking guide](https://aistudio.google.com/docs/thinking) and Google's announcement. The Enterprise migration guide says its older Flash configuration differs and advises explicitly selecting `MEDIUM` if the aim is to preserve its default reasoning setting. It also says that **on that platform**, legacy `thinking_budget` and `MINIMAL` cause an HTTP 400 for Hydrogen. The Developer API documentation checked here establishes Hydrogen's valid levels, but not the same specific error behavior for every old request.

For a coding agent, a default shift changes the workload before anyone judges output quality. The model may spend a different amount of time reasoning, emit a different number of billed output tokens including thinking, and take another path through its tools. The list price for a million tokens does not vary by thinking level on Google's [Hydrogen pricing table](https://aistudio.google.com/docs/pricing). **The number and type of tokens used to finish a job can vary.** That is why a bill from a single successful call is a poor comparison with a multi-step task.

Start with a fixed set of work rather than a vague claim that the new model is “better.” Include a small change with deterministic tests, a larger refactor with several file reads, and a task that requires multiple tool calls. Record accepted changes, wall-clock time, input and output tokens, tool calls, retries and human review. Compare the old configuration with explicit Hydrogen `medium` and `high`; add `low` or `xhigh` only where the task warrants them. This is a proposed validation design, not a result from our own agent fleet.

Independent scores help choose what to test, not what to ship. Artificial Analysis's [November 12 changelog](https://artificialanalysis.ai/changelog) gives Hydrogen Intelligence Index v5.0.1 scores of **27 at low, 41 at medium, 51 at high and 54 at xhigh**. This composite spans multiple evaluations. It does not predict that an individual repository's accepted-patch rate rises by the same number of points, or that xhigh is the cost-effective default. Google's separately reported **57% versus 18.2% on Terminal-Bench 4.1** compares Hydrogen with Gemini 3.8 Flash in Google's setup ([Google's Hydrogen announcement](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/)). The [evaluation methodology](https://deepmind.google/models/evals-methodology/gemini-4-hydrogen) identifies the Hydrogen result as **cheating-adjusted**, measured at high effort with a mini-swe-agent vision harness averaged over five attempts per task. Google's own overview also shows Hydrogen's **57.0% below another listed model's 63.9%** on that benchmark and its **51.4% below 59.9%** on Terminal-Bench-Science 0.1. This is not the Artificial Analysis index or an internal migration test; the chart does not show universal superiority.

![Google's Hydrogen benchmark overview, including the cheating-adjusted Terminal-Bench 4.1 row and results where Hydrogen does not lead](/blog/images/gemini-4-hydrogen-agent-migration-benchmark.png "Google's published benchmark comparison uses its stated test setups; it is not our migration test or proof of universal superiority. Source: [Google's Hydrogen announcement](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/)")

## Replay the transcript, not just the last prompt

The Enterprise guide's most consequential instructions concern the agent history. It says to retain `thought_signature` across prior turns, including function calls and final text; for a turn containing parallel function calls, place the signature only on the first `functionCall` part. Each function response must match its call's `id` and `name`, and there should be exactly one response for each call. If a harness edits or compacts history, the guide calls out `prefix_mismatch_behavior="DROP"` for that case ([Enterprise Agent Platform migration guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate)). These are **documented Enterprise instructions**. Their exact representation and behavior on the Developer API require confirmation against the endpoint in use.

A practical replay fixture should retain the full request and response structure, minus secrets and user data. Exercise at least four states: a plain conversation, a single tool call, two parallel tool calls whose results arrive in a different order, and a history compacted before the next request. For each fixture, assert more than “HTTP success.” Check whether the model can continue, whether it recognizes the expected tool result, whether the next call contains the intended arguments, and whether a retry produces a duplicate side effect. If a tool can write data, run the fixture with a stub or an isolated environment; a migration test should not mutate live systems.

The test is deliberately more demanding than Google's release benchmark. A benchmark can show a model navigating a tool-rich task under one harness. It cannot certify that *your* serialization layer preserves the information its own next turn needs. If your system drops unrecognized fields when logging, summarizing or restoring messages, inspect that boundary before trying to explain a failed agent turn as a model-quality regression.

## Request shape, context and caching need separate gates

For its Enterprise Agent Platform, Google specifies Python `google-genai` **2.34.0 or newer** or JavaScript `@google/genai` **2.32.0 or newer** for this migration. It instructs callers to remove legacy parameters such as `temperature`, `top_p`, `top_k`, `frequency_penalty`, `presence_penalty`, `candidate_count` above one and prefilled model turns. It also directs them away from explicit `cached_content` calls toward implicit caching, placing reusable static prefixes of at least 4,096 tokens first ([Enterprise Agent Platform migration guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate)). Do not silently apply those version floors or every rejection rule to a Developer API integration without testing its documentation and SDK version.

Make an inventory before changing requests. Which fields does your client send by default? Which are injected by an SDK or gateway? Does a test actually reach the same endpoint and API version as production? Rejecting a field is an early, visible failure. Silently changing a default can be harder to notice. Capture the outgoing request shape, compare it with the documented contract for your platform, and remove or deliberately map each old field. For the Developer API, mark unverified compatibility questions as such rather than “fixed” on the strength of the Enterprise guide.

Hydrogen's [API model page](https://aistudio.google.com/docs/models/gemini-4-hydrogen) gives a **1,048,576-token unified input-and-output context limit**. That is a shared budget, not a promise of a million ordinary output tokens after filling the prompt. The stated default synchronous maximum output is **65,536 tokens**; output up to 1,048,576 requires **long decode**. The [thinking documentation](https://aistudio.google.com/docs/thinking) warns that an overly small `max_output_tokens` setting can leave a response incomplete. In a migration test, a truncated answer should first trigger an inspection of request limits and reasoning settings, not a verdict that Hydrogen cannot finish the task. Do not turn on long decode merely because the model page mentions it; validate availability, behavior and your application's handling separately.

Caching deserves its own fixture too. “Implicit caching supported” does not mean an arbitrary sequence of changing tool transcripts will produce a hit. Put a stable prefix where the relevant guide advises, then inspect actual billed cache-hit tokens on the endpoint used. Compare invoices or usage objects under the same task mix. Neither the launch diagram nor a list price reveals the hit rate in a repository-specific workflow.

![Google's launch chart compares Hydrogen thinking levels by AA Index 5.0.1 score and evaluation-task cost](/blog/images/gemini-4-hydrogen-agent-migration-thinking.png "Google's presentation of evaluation scores and task costs does not validate transcript compatibility or predict your bill. Cover artwork also comes from Google's launch. Source: [Google's Hydrogen announcement](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/)")

## Budget for a completed job and a reversible rollout

As listed on November 16, Google's [Gemini API pricing page](https://aistudio.google.com/docs/pricing) prices Hydrogen at **$1.50 per million standard input tokens and $7.50 per million output tokens**, including thinking. Batch input/output are **$0.75/$3.75**; standard implicit cached input is **$0.075** per million. Those are Google API rates, not a quote for another service or a completed agent task. For a simple hypothetical request using 200,000 uncached input tokens and 20,000 output tokens, the token charge would be **$0.30 + $0.15 = $0.45** at standard rates. That arithmetic excludes grounding, other tools, retries, human review, taxes and any different contract; its input/output mix is an assumption, not a reported benchmark.

Do not anchor a long-term migration on today's neighboring-model price. The same official table lists Gemini 4 Carbon standard input/output at **$2/$10 through November 30, 2026**, rising to **$4/$20 on December 1**. Hydrogen has no corresponding introductory promotion listed. If the alternative is Carbon, use the correct time window and evaluate the work the models actually finish. “Cheaper per input token” is not equivalent to “cheaper per accepted pull request.”

A staged cutover can be small and still informative. Freeze a representative task set and a success rubric. Run the Enterprise-specific request and transcript checks on Enterprise, or independently verify the Developer API equivalents on that surface. Start shadow requests or an isolated test cohort, record the full-job metrics and failure modes, and set an explicit rollback trigger such as incorrect tool matching or a sustained drop in accepted changes. Only then widen traffic. This is a proposed operational sequence, not a claim that any such rollout has already succeeded.

The defensible conclusion today is conditional: **Hydrogen is available as a stable Gemini API model, and Google documents a concrete Enterprise agent migration path; the exact Developer API migration behavior still needs endpoint-level verification.** Treat high as a measured starting configuration, not an inherited optimization. Preserve the agent's transcript contract first. If that contract fails, a benchmark score cannot repair the next tool call.

---

## Sources

### blog.google

- [Image source](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/)

### docs.cloud.google.com

- [Enterprise Agent Platform migration guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate)

### aistudio.google.com

- [Gemini API model specification](https://aistudio.google.com/docs/models/gemini-4-hydrogen)
- [Gemini API latest-model page](https://aistudio.google.com/docs/latest-model)
- [Gemini API thinking guide](https://aistudio.google.com/docs/thinking)
- [Hydrogen pricing table](https://aistudio.google.com/docs/pricing)

### artificialanalysis.ai

- [November 12 changelog](https://artificialanalysis.ai/changelog)

### deepmind.google

- [evaluation methodology](https://deepmind.google/models/evals-methodology/gemini-4-hydrogen)