This Gemini 4 Hydrogen migration checklist shows how to move a coding-agent harness off gemini-3.8-flash without breaking tool calls. Google describes Hydrogen as a major standalone upgrade for teams migrating from Gemini 3.8 Flash, yet thinking_budget and a MINIMAL thinking level return HTTP 400. The get-started guide pairs a model-ID change with an SDK upgrade, then covers token limits, thinking levels, caching, thought signatures, and sampling parameters Gemini 4 ignores.
Updated November 13, 2026
Key Takeaways
- Upgrade google-genai to 2.34.0+ and @google/genai to 2.32.0+.
- thinking_budget and MINIMAL thinking_level return HTTP 400 on Hydrogen.
- Preserve thought signatures on prior function-call and text parts.
- Unified budget is 1,048,576 tokens; one segment caps at 65,536 output.
What should you check before you migrate?
Google’s migration guide recommends thorough prompt testing before fully migrating, plus early InfoSec and compliance sign-off in regulated settings. Hydrogen is available on the global endpoint and in the us and eu multi-regions. Authenticate with an API key or application default credentials before the first generate call.
You may see higher reported token counts even when the prompt text is unchanged. Upgraded infrastructure now counts response schemas and function calling that the legacy system undercounted. Teams comparing coding-agent budgets should treat that rise as a counting change, not automatically as a quality regression.
Which request changes does the get-started guide list?
The Gemini 4 get-started guide lists the changes below for a move from gemini-3.8-flash. It puts the model-ID change with the SDK upgrade, and it lists temperature removal last. The Hydrogen model page documents the same limits and errors; it does not set a separate cutover sequence.
The quickstart example exports GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION=global, and GOOGLE_GENAI_USE_ENTERPRISE=True. Global is that example location, not the only supported one.
- Change the model ID from gemini-3.8-flash to gemini-4-hydrogen and upgrade the Google Gen AI SDK. Python needs google-genai 2.34.0 or later, via pip install –upgrade “google-genai>=2.34.0”. JavaScript and TypeScript need @google/genai 2.32.0 or later. Long decodes also list Go 1.77.0 or later and Java 1.80.0 or later.
- Account for the unified 1,048,576-token limit on GenerateContent, the Interactions API, and the OpenAI compatibility Chat Completions API. Output includes thinking, function calls, and the final response. One foreground segment generates up to 65,536 output tokens.
- Replace thinking_budget and thinking_level MINIMAL with thinking_level set to LOW, MEDIUM, HIGH, or XHIGH. HIGH is the default on gemini-4-hydrogen. Those retired fields return an HTTP 400 validation error.
- Remove explicit cached_content references. Implicit caching covers shared prefixes of 4,096 tokens or more, and durable caching is on by default. Put static content, such as a code repository, at the start of the prompt.
- Preserve thought_signature on every previous turn, on both functionCall parts and final text parts. On parallel tool-calling turns, keep it only on the first functionCall part. If the harness compacts or edits prior turns, set prefix_mismatch_behavior to DROP.
- Remove temperature, top_p, and top_k. Gemini 4 ignores custom values for them. Steer output with thinking_level and response_schema.
Turns past 65,536 output tokens can use long decodes up to 1,048,576 tokens minus input, on the Interactions API and GenerateContent v1beta1. With those SDK floors, max_output_tokens above 65,536 follows continuation_token across segments. Google notes that continuation_token is supported only on v1beta1, which the Google Gen AI SDK uses by default.
| Check | Hydrogen requirement |
|---|---|
| thinking_budget or MINIMAL | HTTP 400; use LOW, MEDIUM, HIGH, or XHIGH |
| temperature, top_p, top_k | Ignored; use thinking_level and response_schema |
| cached_content | Remove it; implicit cache from 4,096 tokens |
| thought_signature | Keep on prior turns; error if expected and missing |
| Output size | 65,536 per foreground segment; 1,048,576 unified |
How do you keep thought signatures intact?
The migrate guide says that for Gemini 3 Pro and later, a thought signature that is expected but missing returns an error, not a warning. History edits that drop those parts can fail the next turn for that reason. Do not copy the signature onto every sibling function call.
Layers that cut coding-agent spend still need to leave signature-bearing functionCall and final text parts in place when they shrink context. thought_signature belongs on earlier turns, and only on the first functionCall part of a parallel turn.
Which regression tests does the migration guide describe?
When upgrading, Google’s migration guide says you need three types of regression tests. It separately recommends thorough testing before fully migrating. Those are test types, not three passes that gate a cutover. Run code checks after the request-shape edits, not instead of them.
- Code regression tests, always required: after the SDK and model-ID change, confirm the code functions before you score answers.
- Model performance tests: offline checks in an experimentation environment, plus online evaluation if the app is critical or part of a larger user-facing real-time system. If tools, RAG, or prompt chains are not scored separately, add examples for each component.
- Load tests when the application uses Provisioned Throughput.
For breaking code changes, focus on the code first and wait until evaluation before rewriting prompts. Google’s introducing post prices Hydrogen flat at $1.50 per million input tokens and $7.50 per million output tokens across the 1 million-token window, so thinking tokens and function-call tokens inside the unified budget are the cost to watch.
Frequently asked questions
Which SDK versions does a Gemini 4 Hydrogen migration require?
Python needs google-genai 2.34.0 or later, and JavaScript or TypeScript needs @google/genai 2.32.0 or later. Long decodes also list Go 1.77.0 or later and Java 1.80.0 or later.
What happens if you send thinking_budget to Hydrogen?
The Hydrogen model page says thinking_budget or thinking_level set to MINIMAL returns an HTTP 400 validation error. Use thinking_level LOW, MEDIUM, HIGH, or XHIGH; HIGH is the default.
Do temperature, top_p, and top_k still change Gemini 4 output?
Gemini 4 models ignore custom temperature, top_p, and top_k values. Control output with thinking_level and structured output via response_schema.
Where must thought signatures sit on parallel tool calls?
Preserve thought_signature on earlier functionCall and final text parts, and keep it only on the first functionCall part of a parallel turn. Set prefix_mismatch_behavior to DROP if the harness compacts or edits history.
