pages/deep-research.txt

route: /gemini-api/docs/deep-research
title: Gemini Deep Research Agent
description: Deep Research is an agent designed to perform complex, long-running context gathering and synthesis tasks.

The Gemini Deep Research Agent autonomously plans, executes, and synthesizes
multi-step research tasks. Powered by Gemini, it navigates complex
information landscapes to produce detailed, cited reports. New
capabilities allow you to collaboratively plan with the agent, connect to
external tools using MCP servers, include
visualizations (like charts and graphs), and provide documents directly
as input.
Research tasks involve iterative searching and reading and can take several minutes to complete. You must use background execution (set background=true)
to run the agent asynchronously and poll for results or stream updates. See
Handling long-running tasks for more details.
Preview: The Gemini Deep Research Agent is currently in preview. The Deep
Research agent is exclusively available using the Interactions
API. You cannot access it through
generate_content.
The following example shows how to start a research task in the background
and poll for results.
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
input="Research the history of Google TPUs.",
agent="deep-research-preview-04-2026",
background=True,
)
print(f"Research started: {interaction.id}")
while True:
interaction = client.interactions.get(interaction.id)
if interaction.status == "completed":
print(interaction.steps[-1].content[0].text)
break
elif interaction.status == "failed":
print(f"Research failed: {interaction.error}")
break
time.sleep(10)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
input: 'Research the history of Google TPUs.',
agent: 'deep-research-preview-04-2026',
background: true
});
console.log(`Research started: ${interaction.id}`);
while (true) {
const result = await client.interactions.get(interaction.id);
if (result.status === 'completed') {
console.log(result.steps.at(-1).content[0].text);
break;
} else if (result.status === 'failed') {
console.log(`Research failed: ${result.error}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 10000));
}
REST
# 1. Start the research task
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the history of Google TPUs.",
"agent": "deep-research-preview-04-2026",
"background": true
}'
# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
Supported Versions
The Deep Research agent comes in two versions:
Deep Research (deep-research-preview-04-2026): Designed for speed and efficiency, ideal to be streamed back to a client UI.
Deep Research Max (deep-research-max-preview-04-2026): Maximum comprehensiveness for automated context gathering and synthesis.
Collaborative planning
Preview: Collaborative planning allows you to review and refine the research plan before execution.
Collaborative planning gives you control over the research direction
before the agent starts its work. When enabled, the agent returns a
proposed research plan instead of executing immediately. You can then
review, modify, or approve the plan through multi-turn interactions.
Step 1: Request a plan
Set collaborative_planning=True in the first interaction. The agent
returns a research plan instead of a full report.
Python
from google import genai
client = genai.Client()
# First interaction: request a research plan
plan_interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Do some research on Google TPUs.",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": True,
},
background=True,
)
# Wait for and retrieve the plan
while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const planInteraction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Do some research on Google TPUs.',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: true
},
background: true
});
let result;
while ((result = await client.interactions.get(planInteraction.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Do some research on Google TPUs.",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": true
},
"background": true
}'
Step 2: Refine the plan (optional)
Use previous_interaction_id to continue the conversation and iterate
on the plan. Keep collaborative_planning=True to stay in planning
mode.
Python
# Second interaction: refine the plan
refined_plan = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": True,
},
previous_interaction_id=plan_interaction.id,
background=True,
)
while (result := client.interactions.get(id=refined_plan.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const refinedPlan = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Focus more on the differences between Google TPUs and competitor hardware, and less on the history.',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: true
},
previous_interaction_id: planInteraction.id,
background: true
});
let result;
while ((result = await client.interactions.get(refinedPlan.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": true
},
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"background": true
}'
Step 3: Approve and execute
Set collaborative_planning=False (or omit it) to approve the plan and
start the research.
Python
# Third interaction: approve the plan and kick off research
final_report = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Plan looks good!",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": False,
},
previous_interaction_id=refined_plan.id,
background=True,
)
while (result := client.interactions.get(id=final_report.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const finalReport = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Plan looks good!',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: false
},
previous_interaction_id: refinedPlan.id,
background: true
});
let result;
while ((result = await client.interactions.get(finalReport.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
REST
curl -X POST "https://generativelanguage.googlea
…