Gemini Deep Research Agent Migration Tutorial: Update Before October 23

Google has set October 23, 2026, as the shutdown date for the older Deep Research agent version deep-research-pro-preview-12-2025. Developers who still call that agent through the Gemini Interactions API need to select a supported replacement before the deadline. This tutorial walks through the migration, explains how to choose between the newer agents, and shows what to test before switching a production research workflow.

Why the old Deep Research agent needs replacing

Google's Gemini API release notes dated October 8, 2026, identify deep-research-pro-preview-12-2025 as deprecated and schedule its shutdown for October 23. After shutdown, applications that depend on that agent identifier should not expect their existing requests to keep working. Updating the identifier is the immediate migration step, but developers should also check the surrounding request and response handling instead of assuming that a model change cannot affect their application.

Deep Research agents are designed to investigate a question through multiple research steps and synthesize the findings into a response. That makes them useful for tasks such as preparing a market overview, comparing technical approaches, or collecting evidence for an internal report. Because these jobs can take longer than an ordinary text-generation request, a migration must preserve the application's handling of long-running work, progress updates, errors, and final results.

Choose the replacement that matches your research workflow

Google identifies two replacement options: deep-research-preview-04-2026 and deep-research-max-preview-04-2026. The first is designed for speed and efficiency, particularly when results need to be streamed to a user interface. The second is intended for more comprehensive research and synthesis. These descriptions indicate different priorities, not a guarantee that one agent will outperform the other on every question.

For an application that needs to show users progress and return findings promptly, start by evaluating the standard replacement. If the job requires broader evidence gathering and a more comprehensive final report, test the Max option against the same questions. Compare the completeness of the evidence, factual accuracy, response time, and total usage cost before choosing a default.

Find every reference to the deprecated agent

Start by searching your application repository, environment configuration, deployment settings, and scheduled jobs for the exact string deep-research-pro-preview-12-2025. The identifier may appear in a server-side API wrapper rather than in the code that directly handles the user interface. It may also exist in a configuration file used by a background worker, so changing only the main application's default setting can leave an overlooked integration behind.

Record each location where the old identifier is used and determine whether it represents an active production workflow, a development example, or an unused configuration. Keep the migration limited to the affected agent selection wherever possible. A focused change is easier to review and roll back than a broad rewrite of the research integration.

Update the agent identifier in your API request

Google recommends updating the agent value in requests to interactions.create from the deprecated identifier to one of the replacement identifiers. The following Python example illustrates the relevant configuration change using the Google Gen AI SDK. It assumes that you already have a working client and that the installed SDK version supports the Interactions API.

from google import genai

client = genai.Client()

response = client.interactions.create(
 agent="deep-research-preview-04-2026",
 input="Compare the main approaches to reducing API latency."
)

print(response)

The important change is the agent identifier; the research question is included only as an example. Check the current SDK documentation for the exact method signature, supported response options, and authentication setup for your installed version. If your existing integration uses a different client library or direct REST requests, update the equivalent field in that implementation rather than copying a Python-specific example into another environment.

Check how your application receives the research result

A successful request is only the first check. Research workflows may run for longer than a typical model response, and an application must distinguish a request that has been accepted from one whose research has finished. If your interface streams progress, verify that the new agent's supported execution mode works with your event-handling code. If your backend runs research in a worker, confirm that timeouts and retry rules do not accidentally start duplicate jobs.

Inspect the final response using the fields documented for the SDK or API version you actually use. Avoid assuming that printing the response object is sufficient for a production integration, because a user-facing report may need the final text, status information, and any available research metadata. Keep error messages useful for debugging without exposing API credentials, internal prompts, or private source material.

Run the same research tests against both versions

Before switching production traffic, prepare a small evaluation set drawn from the kinds of questions your application actually receives. Include a straightforward factual question, a question requiring comparison across several sources, and a more involved research task with multiple constraints. Run those questions through the replacement agent and inspect the results against your existing expectations, paying attention to unsupported claims and missing evidence as well as answer quality.

Measure elapsed time and usage for each run, and record any differences in the response structure that your application depends on. A faster result is not an improvement if it omits an important qualification, while a longer report is not necessarily better if it repeats evidence without answering the question. Keep the test prompts and evaluation criteria fixed so that differences between runs are easier to interpret.

Deploy the change before the shutdown date

Once the replacement passes testing, deploy the configuration change to a staging environment and run a complete research request from the user interface through to the final report. Check production logs for requests that still contain the deprecated identifier, including calls from background workers and older application instances. The October 23 deadline makes it worth completing this check ahead of time rather than waiting for an outage to reveal an overlooked reference.

Finally, retain the selected replacement identifier in a centralized configuration setting and document who owns future model migrations. Google can retire preview agents on a different schedule from stable products, so a working integration today is not proof that its identifier will remain available indefinitely. A small, repeatable migration test is a better safeguard than relying on a successful manual request made once during development.