Google Gemini 3 API updates for agents
A useful Google Developers read on thinking control, media resolution, thought signatures, and structured output with grounding.
Model APIs used to expose one knob: temperature. Gemini 3’s API exposes four controls that directly map to product decisions — how hard to think, how much image detail to spend tokens on, whether to preserve reasoning across tool calls, and whether to ground answers in live search.
Source
New Gemini API updates for Gemini 3
By: Google for Developers
Published: Nov 25 2025
Type: Engineering article
These API changes matter because they turn model behaviour into product controls. Every feature here — thinking depth, media resolution, thought signatures, grounded structured output — lets a developer make an explicit trade-off between cost, latency, and quality. That’s the transition from “call a model” to “configure an agent runtime.”
How Gemini 3’s API turns model behaviour into product dials
Thinking control is the simplest addition and possibly the most useful. A new thinking_level parameter sets the maximum depth of the model’s internal reasoning before it produces a response. Set it to high for complex tasks like strategic analysis or vulnerability scanning. Set it to low for latency-sensitive work like structured data extraction or summarisation. Gemini 3 treats these levels as relative guidelines rather than strict token guarantees, so the actual thinking budget varies by prompt complexity. The practical effect is one parameter that directly maps to a cost/quality/latency trade-off — no prompt engineering required.
Media resolution control addresses a cost problem that hits any system processing images, video, or documents. The media_resolution parameter configures how many tokens are used per visual input. You can set media_resolution_low, media_resolution_medium, or media_resolution_high per individual media part or globally. Higher resolution improves the model’s ability to read fine text or identify small details, but increases token usage and latency. If unspecified, the model picks optimal defaults by media type. This matters because visual inputs can dominate a request’s token budget — an agent processing screenshots or PDFs all day accumulates cost fast if every image gets maximum resolution.
Thought signatures solve a continuity problem in multi-turn agent workflows. Starting with Gemini 3, the API returns encrypted representations of the model’s internal thought process. When you pass these signatures back in subsequent calls, the model maintains its chain of reasoning across the conversation. Without them, each turn effectively starts from scratch — the model has to re-derive its plan from the conversation history. For function calling, validation is strict: missing signatures return a 400 error. For text/chat generation, it’s not enforced but omitting them degrades reasoning quality. Image generation also requires them. If you use the official SDKs with standard chat history, signatures are handled automatically.
Grounded structured output combines two capabilities that were previously separate. You can now use Grounding with Google Search and URL Context together with structured outputs. This means an agent can fetch live information from the web or specific pages and extract it into a precise JSON schema — sourced answers in a defined format, not free text that needs parsing. The pricing model also changed: grounding moved from a flat US$35 per 1,000 prompts to US$14 per 1,000 search queries, which better fits dynamic agent workflows where not every turn needs search.
The best practices section reveals how Gemini 3 Pro differs from previous models. It recommends keeping temperature at the default 1.0, notes that the model is less verbose by default (you have to explicitly ask for longer responses), and advises placing constraints at the top of the prompt while placing specific instructions at the end when working with large contexts. Google also published a system instructions template for agentic coding that improved performance on several benchmarks.
My take
What’s interesting is the direction, not just the features. Each of these controls removes a layer of prompt engineering. Instead of writing elaborate instructions to make the model think harder, you set thinking_level: high. Instead of compressing images before sending them, you set media_resolution_low. Instead of re-summarising the conversation to maintain reasoning context, you pass back thought signatures. The cumulative effect is that the API surface is absorbing what used to be application-level logic. That makes agents simpler to build but also couples them more tightly to one provider’s API shape — these parameters don’t exist on competing APIs, so code that depends on them doesn’t port easily.
Where this is useful
- When building agents that handle both simple and complex tasks in the same workflow —
thinking_levellets you dynamically trade cost for quality per request instead of picking one model for everything. - When processing high volumes of visual inputs (screenshots, PDFs, scanned documents) —
media_resolutionis a direct cost lever that doesn’t require preprocessing. - When building extraction agents that need both live web data and structured output — grounded structured output eliminates the parse-free-text step entirely.
Apply this: If your agent makes the same model call for both simple lookups and complex reasoning, add a routing layer that sets
thinking_levelby task type. The cost difference compounds fast.
What I want to remember
Remember: Agent APIs need controls that map to product decisions: how hard to reason, how much image detail to inspect, whether to preserve reasoning across turns, and what schema the output must follow. One parameter per trade-off is better than a page of prompt engineering.