Repository Public
1The Gemini Deep Research agent autonomously plans, executes, and synthesizes2multi-step research tasks. Powered by Gemini, it navigates complex3information landscapes to produce detailed, cited reports. New4capabilities allow you to collaboratively plan with the agent, connect to5external tools using MCP servers, include6visualizations (like charts and graphs), and provide documents directly7as input.89Research tasks involve iterative searching and reading and can take several minutes to complete. You must use [background execution](https://ai.google.dev/gemini-api/docs/background-execution) (set `background=true`)10to run the agent asynchronously and poll for results or stream updates. See11[Handling long-running tasks](https://ai.google.dev/gemini-api/docs/deep-research#long-running-tasks) for more details.1213> [!WARNING]14> **Preview:** The Gemini Deep Research agent is currently in preview. The Deep Research agent is exclusively available using the [Interactions15> API](https://ai.google.dev/gemini-api/docs). You cannot access it through `generate_content`.1617The following example shows how to start a research task in the background18and poll for results.1920### Python2122 import time23 from google import genai2425 client = genai.Client()2627 interaction = client.interactions.create(28 input="Research the history of Google TPUs.",29 agent="deep-research-preview-04-2026",30 background=True,31 )3233 print(f"Research started: {interaction.id}")3435 while True:36 interaction = client.interactions.get(interaction.id)37 if interaction.status == "completed":38 print(interaction.steps[-1].content[0].text)39 break40 elif interaction.status == "failed":41 print(f"Research failed: {interaction.error}")42 break43 time.sleep(10)4445### JavaScript4647 import { GoogleGenAI } from '@google/genai';4849 const client = new GoogleGenAI({});5051 const interaction = await client.interactions.create({52 input: 'Research the history of Google TPUs.',53 agent: 'deep-research-preview-04-2026',54 background: true55 });5657 console.log(`Research started: ${interaction.id}`);5859 while (true) {60 const result = await client.interactions.get(interaction.id);61 if (result.status === 'completed') {62 console.log(result.steps.at(-1).content[0].text);63 break;64 } else if (result.status === 'failed') {65 console.log(`Research failed: ${result.error}`);66 break;67 }68 await new Promise(resolve => setTimeout(resolve, 10000));69 }7071### Java7273 import com.google.genai.Client;74 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;75 import com.google.genai.gaos.models.interactions.Interaction;76 import com.google.genai.gaos.models.interactions.InteractionStatus;77 import com.google.genai.gaos.models.interactions.InteractionsInput;78 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;79 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;80 import java.util.Collections;8182 Client client = new Client();8384 CreateAgentInteraction params =85 CreateAgentInteraction.builder()86 .agent("deep-research-preview-04-2026")87 .input(InteractionsInput.of("Research the history of Google TPUs."))88 .background(true)89 .build();9091 Interaction interaction =92 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();9394 System.out.println("Research started: " + interaction.id().orElse(""));9596 while (true) {97 interaction =98 client.interactions99 .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())100 .interaction()101 .get();102 if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {103 System.out.println(interaction.outputText().orElse(""));104 break;105 } else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {106 System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));107 break;108 }109 Thread.sleep(10000);110 }111112### REST113114 # 1. Start the research task115 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \116 -H "Content-Type: application/json" \117 -H "x-goog-api-key: $GEMINI_API_KEY" \118 -d '{119 "input": "Research the history of Google TPUs.",120 "agent": "deep-research-preview-04-2026",121 "background": true122 }'123124 # 2. Poll for results (Replace INTERACTION_ID)125 # curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \126 # -H "x-goog-api-key: $GEMINI_API_KEY"127128## Supported versions129130The Deep Research agent comes in two versions:131132- **Deep Research** (`deep-research-preview-04-2026`): Designed for speed and efficiency, ideal to be streamed back to a client UI.133- **Deep Research Max** (`deep-research-max-preview-04-2026`): Maximum comprehensiveness for automated context gathering and synthesis.134135## Collaborative planning136137Collaborative planning gives you control over the research direction before the138agent starts its work by letting you review and refine the research plan before139execution. When enabled, the agent returns a proposed research plan instead of140executing immediately. You can then review, modify, or approve the plan through141multi-turn interactions.142143### Step 1: Request a plan144145Set `collaborative_planning=True` in the first interaction. The agent146returns a research plan instead of a full report.147148### Python149150 from google import genai151152 client = genai.Client()153154 # First interaction: request a research plan155 plan_interaction = client.interactions.create(156 agent="deep-research-preview-04-2026",157 input="Do some research on Google TPUs.",158 agent_config={159 "type": "deep-research",160 "thinking_summaries": "auto",161 "collaborative_planning": True,162 },163 background=True,164 )165166 # Wait for and retrieve the plan167 while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":168 time.sleep(5)169 print(result.steps[-1].content[0].text)170171### JavaScript172173 const planInteraction = await client.interactions.create({174 agent: 'deep-research-preview-04-2026',175 input: 'Do some research on Google TPUs.',176 agent_config: {177 type: 'deep-research',178 thinking_summaries: 'auto',179 collaborative_planning: true180 },181 background: true182 });183184 let result;185 while ((result = await client.interactions.get(planInteraction.id)).status !== 'completed') {186 await new Promise(r => setTimeout(r, 5000));187 }188 console.log(result.steps.at(-1).content[0].text);189190### Java191192 import com.google.genai.Client;193 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;194 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;195 import com.google.genai.gaos.models.interactions.Interaction;196 import com.google.genai.gaos.models.interactions.InteractionStatus;197 import com.google.genai.gaos.models.interactions.InteractionsInput;198 import com.google.genai.gaos.models.interactions.ThinkingSummaries;199 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;200 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;201202 Client client = new Client();203204 // First interaction: request a research plan205 CreateAgentInteraction params =206 CreateAgentInteraction.builder()207 .agent("deep-research-preview-04-2026")208 .input(InteractionsInput.of("Do some research on Google TPUs."))209 .agentConfig(210 DeepResearchAgentConfig.builder()211 .thinkingSummaries(ThinkingSummaries.AUTO)212 .collaborativePlanning(true)213 .build())214 .background(true)215 .build();216217 Interaction planInteraction =218 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();219220 // Wait for and retrieve the plan221 Interaction result;222 while (true) {223 result =224 client.interactions225 .get(GetInteractionByIdRequest.builder().id(planInteraction.id().get()).build())226 .interaction()227 .get();228 if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {229 break;230 }231 Thread.sleep(5000);232 }233 System.out.println(result.outputText().orElse(""));234235### REST236237 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \238 -H "Content-Type: application/json" \239 -H "x-goog-api-key: $GEMINI_API_KEY" \240 -d '{241 "agent": "deep-research-preview-04-2026",242 "input": "Do some research on Google TPUs.",243 "agent_config": {244 "type": "deep-research",245 "thinking_summaries": "auto",246 "collaborative_planning": true247 },248 "background": true249 }'250251### Step 2: Refine the plan (optional)252253Use `previous_interaction_id` to continue the conversation and iterate254on the plan. Keep `collaborative_planning=True` to stay in planning255mode.256257### Python258259 # Second interaction: refine the plan260 refined_plan = client.interactions.create(261 agent="deep-research-preview-04-2026",262 input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",263 agent_config={264 "type": "deep-research",265 "thinking_summaries": "auto",266 "collaborative_planning": True,267 },268 previous_interaction_id=plan_interaction.id,269 background=True,270 )271272 while (result := client.interactions.get(id=refined_plan.id)).status != "completed":273 time.sleep(5)274 print(result.steps[-1].content[0].text)275276### JavaScript277278 const refinedPlan = await client.interactions.create({279 agent: 'deep-research-preview-04-2026',280 input: 'Focus more on the differences between Google TPUs and competitor hardware, and less on the history.',281 agent_config: {282 type: 'deep-research',283 thinking_summaries: 'auto',284 collaborative_planning: true285 },286 previous_interaction_id: planInteraction.id,287 background: true288 });289290 let result;291 while ((result = await client.interactions.get(refinedPlan.id)).status !== 'completed') {292 await new Promise(r => setTimeout(r, 5000));293 }294 console.log(result.steps.at(-1).content[0].text);295296### Java297298 import com.google.genai.Client;299 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;300 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;301 import com.google.genai.gaos.models.interactions.Interaction;302 import com.google.genai.gaos.models.interactions.InteractionStatus;303 import com.google.genai.gaos.models.interactions.InteractionsInput;304 import com.google.genai.gaos.models.interactions.ThinkingSummaries;305 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;306 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;307308 Client client = new Client();309 String planInteractionId = "PLAN_INTERACTION_ID";310311 // Second interaction: refine the plan312 CreateAgentInteraction params =313 CreateAgentInteraction.builder()314 .agent("deep-research-preview-04-2026")315 .input(316 InteractionsInput.of(317 "Focus more on the differences between Google TPUs and competitor hardware, and less on the history."))318 .agentConfig(319 DeepResearchAgentConfig.builder()320 .thinkingSummaries(ThinkingSummaries.AUTO)321 .collaborativePlanning(true)322 .build())323 .previousInteractionId(planInteractionId)324 .background(true)325 .build();326327 Interaction refinedPlan =328 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();329330 Interaction result;331 while (true) {332 result =333 client.interactions334 .get(GetInteractionByIdRequest.builder().id(refinedPlan.id().get()).build())335 .interaction()336 .get();337 if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {338 break;339 }340 Thread.sleep(5000);341 }342 System.out.println(result.outputText().orElse(""));343344### REST345346 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \347 -H "Content-Type: application/json" \348 -H "x-goog-api-key: $GEMINI_API_KEY" \349 -d '{350 "agent": "deep-research-preview-04-2026",351 "input": "Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",352 "agent_config": {353 "type": "deep-research",354 "thinking_summaries": "auto",355 "collaborative_planning": true356 },357 "previous_interaction_id": "PREVIOUS_INTERACTION_ID",358 "background": true359 }'360361### Step 3: Approve and execute362363Set `collaborative_planning=False` (or omit it) to approve the plan and364start the research.365366### Python367368 # Third interaction: approve the plan and kick off research369 final_report = client.interactions.create(370 agent="deep-research-preview-04-2026",371 input="Plan looks good!",372 agent_config={373 "type": "deep-research",374 "thinking_summaries": "auto",375 "collaborative_planning": False,376 },377 previous_interaction_id=refined_plan.id,378 background=True,379 )380381 while (result := client.interactions.get(id=final_report.id)).status != "completed":382 time.sleep(5)383 print(result.steps[-1].content[0].text)384385### JavaScript386387 const finalReport = await client.interactions.create({388 agent: 'deep-research-preview-04-2026',389 input: 'Plan looks good!',390 agent_config: {391 type: 'deep-research',392 thinking_summaries: 'auto',393 collaborative_planning: false394 },395 previous_interaction_id: refinedPlan.id,396 background: true397 });398399 let result;400 while ((result = await client.interactions.get(finalReport.id)).status !== 'completed') {401 await new Promise(r => setTimeout(r, 5000));402 }403 console.log(result.steps.at(-1).content[0].text);404405### Java406407 import com.google.genai.Client;408 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;409 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;410 import com.google.genai.gaos.models.interactions.Interaction;411 import com.google.genai.gaos.models.interactions.InteractionStatus;412 import com.google.genai.gaos.models.interactions.InteractionsInput;413 import com.google.genai.gaos.models.interactions.ThinkingSummaries;414 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;415 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;416417 Client client = new Client();418 String refinedPlanId = "REFINED_PLAN_ID";419420 // Third interaction: approve the plan and kick off research421 CreateAgentInteraction params =422 CreateAgentInteraction.builder()423 .agent("deep-research-preview-04-2026")424 .input(InteractionsInput.of("Plan looks good!"))425 .agentConfig(426 DeepResearchAgentConfig.builder()427 .thinkingSummaries(ThinkingSummaries.AUTO)428 .collaborativePlanning(false)429 .build())430 .previousInteractionId(refinedPlanId)431 .background(true)432 .build();433434 Interaction finalReport =435 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();436437 Interaction result;438 while (true) {439 result =440 client.interactions441 .get(GetInteractionByIdRequest.builder().id(finalReport.id().get()).build())442 .interaction()443 .get();444 if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {445 break;446 }447 Thread.sleep(5000);448 }449 System.out.println(result.outputText().orElse(""));450451### REST452453 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \454 -H "Content-Type: application/json" \455 -H "x-goog-api-key: $GEMINI_API_KEY" \456 -d '{457 "agent": "deep-research-preview-04-2026",458 "input": "Plan looks good!",459 "agent_config": {460 "type": "deep-research",461 "thinking_summaries": "auto",462 "collaborative_planning": false463 },464 "previous_interaction_id": "PREVIOUS_INTERACTION_ID",465 "background": true466 }'467468## Visualization469470When `visualization` is set to `"auto"`, the agent can generate charts,471graphs, and other visual elements to support its research findings.472Generated images are included in the response steps and streamed as473`image` deltas. For best results, explicitly ask for visuals in your474query --- for example, "Include charts showing trends over time" or475"Generate graphics comparing market share." Setting `visualization` to476`"auto"` enables the capability, but the agent generates visuals only477when the prompt requests them.478479### Python480481 import base64482 import time483484 from google import genai485486 client = genai.Client()487488 interaction = client.interactions.create(489 agent="deep-research-preview-04-2026",490 input="Analyze global semiconductor market trends. Include graphics showing market share changes.",491 agent_config={492 "type": "deep-research",493 "visualization": "auto",494 },495 background=True,496 )497498 print(f"Research started: {interaction.id}")499500 while (result := client.interactions.get(id=interaction.id)).status != "completed":501 time.sleep(5)502503 for step in result.steps:504 if step.type == "model_output":505 for content_item in step.content:506 if content_item.type == "text":507 print(content_item.text)508 elif content_item.type == "image" and content_item.data:509 image_bytes = base64.b64decode(content_item.data)510 print(f"Received image: {len(image_bytes)} bytes")511512### JavaScript513514 import { GoogleGenAI } from '@google/genai';515516 const client = new GoogleGenAI({});517518 const interaction = await client.interactions.create({519 agent: 'deep-research-preview-04-2026',520 input: 'Analyze global semiconductor market trends. Include graphics showing market share changes.',521 agent_config: {522 type: 'deep-research',523 visualization: 'auto'524 },525 background: true526 });527528 console.log(`Research started: ${interaction.id}`);529530 let result;531 while ((result = await client.interactions.get(interaction.id)).status !== 'completed') {532 await new Promise(r => setTimeout(r, 5000));533 }534535 for (const step of result.steps) {536 if (step.type === 'model_output') {537 for (const contentItem of step.content) {538 if (contentItem.type === 'text') {539 console.log(contentItem.text);540 } else if (contentItem.type === 'image' && contentItem.data) {541 console.log(`[Image Output: ${contentItem.data.substring(0, 20)}...]`);542 }543 }544 }545 }546547### Java548549 import com.google.genai.Client;550 import com.google.genai.gaos.models.interactions.Content;551 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;552 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;553 import com.google.genai.gaos.models.interactions.ImageContent;554 import com.google.genai.gaos.models.interactions.Interaction;555 import com.google.genai.gaos.models.interactions.InteractionStatus;556 import com.google.genai.gaos.models.interactions.InteractionsInput;557 import com.google.genai.gaos.models.interactions.ModelOutputStep;558 import com.google.genai.gaos.models.interactions.Step;559 import com.google.genai.gaos.models.interactions.TextContent;560 import com.google.genai.gaos.models.interactions.Visualization;561 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;562 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;563 import java.util.Base64;564 import java.util.Collections;565566 Client client = new Client();567568 CreateAgentInteraction params =569 CreateAgentInteraction.builder()570 .agent("deep-research-preview-04-2026")571 .input(572 InteractionsInput.of(573 "Analyze global semiconductor market trends. Include graphics showing market share changes."))574 .agentConfig(DeepResearchAgentConfig.builder().visualization(Visualization.AUTO).build())575 .background(true)576 .build();577578 Interaction interaction =579 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();580581 System.out.println("Research started: " + interaction.id().orElse(""));582583 Interaction result;584 while (true) {585 result =586 client.interactions587 .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())588 .interaction()589 .get();590 if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {591 break;592 }593 Thread.sleep(5000);594 }595596 for (Step step : result.steps().orElse(Collections.emptyList())) {597 if (step instanceof ModelOutputStep) {598 for (Content contentItem : ((ModelOutputStep) step).content().orElse(Collections.emptyList())) {599 if (contentItem instanceof TextContent) {600 System.out.println(((TextContent) contentItem).text().orElse(""));601 } else if (contentItem instanceof ImageContent) {602 ImageContent img = (ImageContent) contentItem;603 if (img.data().isPresent()) {604 byte[] imageBytes = Base64.getDecoder().decode(img.data().get());605 System.out.println("Received image: " + imageBytes.length + " bytes");606 }607 }608 }609 }610 }611612### REST613614 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \615 -H "Content-Type: application/json" \616 -H "x-goog-api-key: $GEMINI_API_KEY" \617 -d '{618 "agent": "deep-research-preview-04-2026",619 "input": "Analyze global semiconductor market trends. Include graphics showing market share changes.",620 "agent_config": {621 "type": "deep-research",622 "visualization": "auto"623 },624 "background": true625 }'626627## Supported tools628629Deep Research supports multiple built-in and external tools. By default630(when no `tools` parameter is provided), the agent has access to Google631Search, URL Context, and Code Execution. You can explicitly632specify tools to restrict or extend the agent's capabilities.633634| Tool | Type value | Description |635|---|---|---|636| Google Search | `google_search` | Search the public web. Enabled by default. |637| URL Context | `url_context` | Read and summarize web page content. Enabled by default. |638| Code Execution | `code_execution` | Execute code to perform calculations and data analysis. Enabled by default. |639| MCP Server | `mcp_server` | Connect to remote MCP servers for external tool access. |640| File Search | `file_search` | Search your uploaded document corpora. |641642### Google Search643644Explicitly enable Google Search as the only tool:645646### Python647648 interaction = client.interactions.create(649 agent="deep-research-preview-04-2026",650 input="What are the latest developments in quantum computing?",651 tools=[{"type": "google_search"}],652 background=True,653 )654655### JavaScript656657 const interaction = await client.interactions.create({658 agent: 'deep-research-preview-04-2026',659 input: 'What are the latest developments in quantum computing?',660 tools: [{ type: 'google_search' }],661 background: true662 });663664### Java665666 import com.google.genai.Client;667 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;668 import com.google.genai.gaos.models.interactions.GoogleSearch;669 import com.google.genai.gaos.models.interactions.Interaction;670 import com.google.genai.gaos.models.interactions.InteractionsInput;671 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;672 import java.util.Arrays;673674 Client client = new Client();675676 CreateAgentInteraction params =677 CreateAgentInteraction.builder()678 .agent("deep-research-preview-04-2026")679 .input(InteractionsInput.of("What are the latest developments in quantum computing?"))680 .tools(Arrays.asList(GoogleSearch.builder().build()))681 .background(true)682 .build();683684 Interaction interaction =685 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();686687### REST688689 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \690 -H "Content-Type: application/json" \691 -H "x-goog-api-key: $GEMINI_API_KEY" \692 -d '{693 "agent": "deep-research-preview-04-2026",694 "input": "What are the latest developments in quantum computing?",695 "tools": [{"type": "google_search"}],696 "background": true697 }'698699### URL Context700701Give the agent the ability to read and summarize specific web pages:702703### Python704705 interaction = client.interactions.create(706 agent="deep-research-preview-04-2026",707 input="Summarize the content of https://www.wikipedia.org/.",708 tools=[{"type": "url_context"}],709 background=True,710 )711712### JavaScript713714 const interaction = await client.interactions.create({715 agent: 'deep-research-preview-04-2026',716 input: 'Summarize the content of https://www.wikipedia.org/.',717 tools: [{ type: 'url_context' }],718 background: true719 });720721### Java722723 import com.google.genai.Client;724 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;725 import com.google.genai.gaos.models.interactions.Interaction;726 import com.google.genai.gaos.models.interactions.InteractionsInput;727 import com.google.genai.gaos.models.interactions.URLContext;728 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;729 import java.util.Arrays;730731 Client client = new Client();732733 CreateAgentInteraction params =734 CreateAgentInteraction.builder()735 .agent("deep-research-preview-04-2026")736 .input(InteractionsInput.of("Summarize the content of https://www.wikipedia.org/."))737 .tools(Arrays.asList(URLContext.builder().build()))738 .background(true)739 .build();740741 Interaction interaction =742 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();743744### REST745746 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \747 -H "Content-Type: application/json" \748 -H "x-goog-api-key: $GEMINI_API_KEY" \749 -d '{750 "agent": "deep-research-preview-04-2026",751 "input": "Summarize the content of https://www.wikipedia.org/.",752 "tools": [{"type": "url_context"}],753 "background": true754 }'755756### Code Execution757758Allow the agent to execute code for calculations and data analysis:759760### Python761762 interaction = client.interactions.create(763 agent="deep-research-preview-04-2026",764 input="Calculate the 50th Fibonacci number.",765 tools=[{"type": "code_execution"}],766 background=True,767 )768769### JavaScript770771 const interaction = await client.interactions.create({772 agent: 'deep-research-preview-04-2026',773 input: 'Calculate the 50th Fibonacci number.',774 tools: [{ type: 'code_execution' }],775 background: true776 });777778### Java779780 import com.google.genai.Client;781 import com.google.genai.gaos.models.interactions.CodeExecution;782 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;783 import com.google.genai.gaos.models.interactions.Interaction;784 import com.google.genai.gaos.models.interactions.InteractionsInput;785 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;786 import java.util.Arrays;787788 Client client = new Client();789790 CreateAgentInteraction params =791 CreateAgentInteraction.builder()792 .agent("deep-research-preview-04-2026")793 .input(InteractionsInput.of("Calculate the 50th Fibonacci number."))794 .tools(Arrays.asList(CodeExecution.builder().build()))795 .background(true)796 .build();797798 Interaction interaction =799 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();800801### REST802803 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \804 -H "Content-Type: application/json" \805 -H "x-goog-api-key: $GEMINI_API_KEY" \806 -d '{807 "input": "Calculate the 50th Fibonacci number.",808 "agent": "deep-research-preview-04-2026",809 "tools": [{"type": "code_execution"}],810 "background": true811 }'812813### MCP servers814815Connect to remote MCP servers to give the agent access to external tools and816services.817818Provide the server `name` and `url` in the tools configuration. You can also819pass authentication credentials and restrict which tools the agent can call.820821| Field | Type | Required | Description |822|---|---|---|---|823| `type` | `string` | Yes | Must be `"mcp_server"`. |824| `name` | `string` | No | A display name for the MCP server. |825| `url` | `string` | No | The full URL for the MCP server endpoint. |826| `headers` | `object` | No | Key-value pairs sent as HTTP headers with every request to the server (for example, authentication tokens). |827| `allowed_tools` | `array` | No | Restrict which tools from the server the agent may call. |828829#### Basic usage830831### Python832833 interaction = client.interactions.create(834 agent="deep-research-preview-04-2026",835 input="Check the status of my last server deployment.",836 tools=[837 {838 "type": "mcp_server",839 "name": "Deployment Tracker",840 "url": "https://mcp.example.com/mcp",841 "headers": {"Authorization": "Bearer my-token"},842 }843 ],844 background=True,845 )846847### JavaScript848849 const interaction = await client.interactions.create({850 agent: 'deep-research-preview-04-2026',851 input: 'Check the status of my last server deployment.',852 tools: [853 {854 type: 'mcp_server',855 name: 'Deployment Tracker',856 url: 'https://mcp.example.com/mcp',857 headers: { Authorization: 'Bearer my-token' }858 }859 ],860 background: true861 });862863### Java864865 import com.google.genai.Client;866 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;867 import com.google.genai.gaos.models.interactions.Interaction;868 import com.google.genai.gaos.models.interactions.InteractionsInput;869 import com.google.genai.gaos.models.interactions.MCPServer;870 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;871 import java.util.Arrays;872 import java.util.Collections;873874 Client client = new Client();875876 CreateAgentInteraction params =877 CreateAgentInteraction.builder()878 .agent("deep-research-preview-04-2026")879 .input(InteractionsInput.of("Check the status of my last server deployment."))880 .tools(881 Arrays.asList(882 MCPServer.builder()883 .name("Deployment Tracker")884 .url("https://mcp.example.com/mcp")885 .headers(Collections.singletonMap("Authorization", "Bearer my-token"))886 .build()))887 .background(true)888 .build();889890 Interaction interaction =891 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();892893### REST894895 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \896 -H "Content-Type: application/json" \897 -H "x-goog-api-key: $GEMINI_API_KEY" \898 -d '{899 "agent": "deep-research-preview-04-2026",900 "input": "Check the status of my last server deployment.",901 "tools": [902 {903 "type": "mcp_server",904 "name": "Deployment Tracker",905 "url": "https://mcp.example.com/mcp",906 "headers": {"Authorization": "Bearer my-token"}907 }908 ],909 "background": true910 }'911912### File Search913914Give the agent access to your own data by using the [File Search](https://ai.google.dev/gemini-api/docs/file-search) tool.915916### Python917918 import time919 from google import genai920921 client = genai.Client()922923 interaction = client.interactions.create(924 input="Compare our 2025 fiscal year report against current public web news.",925 agent="deep-research-preview-04-2026",926 background=True,927 tools=[928 {929 "type": "file_search",930 "file_search_store_names": ['fileSearchStores/my-store-name']931 }932 ]933 )934935### JavaScript936937 const interaction = await client.interactions.create({938 input: 'Compare our 2025 fiscal year report against current public web news.',939 agent: 'deep-research-preview-04-2026',940 background: true,941 tools: [942 { type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] },943 ]944 });945946### Java947948 import com.google.genai.Client;949 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;950 import com.google.genai.gaos.models.interactions.FileSearch;951 import com.google.genai.gaos.models.interactions.Interaction;952 import com.google.genai.gaos.models.interactions.InteractionsInput;953 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;954 import java.util.Arrays;955956 Client client = new Client();957958 CreateAgentInteraction params =959 CreateAgentInteraction.builder()960 .agent("deep-research-preview-04-2026")961 .input(962 InteractionsInput.of(963 "Compare our 2025 fiscal year report against current public web news."))964 .tools(965 Arrays.asList(966 FileSearch.builder()967 .fileSearchStoreNames(Arrays.asList("fileSearchStores/my-store-name"))968 .build()))969 .background(true)970 .build();971972 Interaction interaction =973 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();974975### REST976977 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \978 -H "Content-Type: application/json" \979 -H "x-goog-api-key: $GEMINI_API_KEY" \980 -d '{981 "input": "Compare our 2025 fiscal year report against current public web news.",982 "agent": "deep-research-preview-04-2026",983 "background": true,984 "tools": [985 {"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]},986 ]987 }'988989## Steerability and formatting990991You can steer the agent's output by providing specific formatting instructions992in your prompt. This allows you to structure reports into specific sections and993subsections, include data tables, or adjust tone for different audiences (e.g.,994"technical," "executive," "casual").995996Define the desired output format explicitly in your input text.997998### Python9991000 prompt = """1001 Research the competitive landscape of EV batteries.10021003 Format the output as a technical report with the following structure:1004 1. Executive Summary1005 2. Key Players (Must include a data table comparing capacity and chemistry)1006 3. Supply Chain Risks1007 """10081009 interaction = client.interactions.create(1010 input=prompt,1011 agent="deep-research-preview-04-2026",1012 background=True1013 )10141015### JavaScript10161017 const prompt = `1018 Research the competitive landscape of EV batteries.10191020 Format the output as a technical report with the following structure:1021 1. Executive Summary1022 2. Key Players (Must include a data table comparing capacity and chemistry)1023 3. Supply Chain Risks1024 `;10251026 const interaction = await client.interactions.create({1027 input: prompt,1028 agent: 'deep-research-preview-04-2026',1029 background: true,1030 });10311032### Java10331034 import com.google.genai.Client;1035 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1036 import com.google.genai.gaos.models.interactions.Interaction;1037 import com.google.genai.gaos.models.interactions.InteractionsInput;1038 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;10391040 Client client = new Client();10411042 String prompt =1043 "Research the competitive landscape of EV batteries.\n\n"1044 + "Format the output as a technical report with the following structure:\n"1045 + "1. Executive Summary\n"1046 + "2. Key Players (Must include a data table comparing capacity and chemistry)\n"1047 + "3. Supply Chain Risks";10481049 CreateAgentInteraction params =1050 CreateAgentInteraction.builder()1051 .agent("deep-research-preview-04-2026")1052 .input(InteractionsInput.of(prompt))1053 .background(true)1054 .build();10551056 Interaction interaction =1057 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();10581059### REST10601061 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1062 -H "Content-Type: application/json" \1063 -H "x-goog-api-key: $GEMINI_API_KEY" \1064 -d '{1065 "input": "Research the competitive landscape of EV batteries.\n\nFormat the output as a technical report with the following structure: \n1. Executive Summary\n2. Key Players (Must include a data table comparing capacity and chemistry)\n3. Supply Chain Risks",1066 "agent": "deep-research-preview-04-2026",1067 "background": true1068 }'10691070## Multimodal inputs10711072Deep Research supports multimodal inputs, including images and documents (PDFs), allowing1073the agent to analyze visual content and conduct web-based research1074contextualized by the provided inputs.10751076### Python10771078 import time1079 from google import genai10801081 client = genai.Client()10821083 prompt = """Analyze the interspecies dynamics and behavioral risks present1084 in the provided image of the African watering hole. Specifically, investigate1085 the symbiotic relationship between the avian species and the pachyderms1086 shown, and conduct a risk assessment for the reticulated giraffes based on1087 their drinking posture relative to the specific predator visible in the1088 foreground."""10891090 interaction = client.interactions.create(1091 input=[1092 {"type": "text", "text": prompt},1093 {1094 "type": "image",1095 "mime_type": "image/jpeg",1096 "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"1097 }1098 ],1099 agent="deep-research-preview-04-2026",1100 background=True1101 )11021103 print(f"Research started: {interaction.id}")11041105 while True:1106 interaction = client.interactions.get(interaction.id)1107 if interaction.status == "completed":1108 print(interaction.steps[-1].content[0].text)1109 break1110 elif interaction.status == "failed":1111 print(f"Research failed: {interaction.error}")1112 break1113 time.sleep(10)11141115### JavaScript11161117 import { GoogleGenAI } from '@google/genai';11181119 const client = new GoogleGenAI({});11201121 const prompt = `Analyze the interspecies dynamics and behavioral risks present1122 in the provided image of the African watering hole. Specifically, investigate1123 the symbiotic relationship between the avian species and the pachyderms1124 shown, and conduct a risk assessment for the reticulated giraffes based on1125 their drinking posture relative to the specific predator visible in the1126 foreground.`;11271128 const interaction = await client.interactions.create({1129 input: [1130 { type: 'text', text: prompt },1131 {1132 type: 'image',1133 mime_type: "image/jpeg",1134 uri: 'https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg'1135 }1136 ],1137 agent: 'deep-research-preview-04-2026',1138 background: true1139 });11401141 console.log(`Research started: ${interaction.id}`);11421143 while (true) {1144 const result = await client.interactions.get(interaction.id);1145 if (result.status === 'completed') {1146 console.log(result.steps.at(-1).content[0].text);1147 break;1148 } else if (result.status === 'failed') {1149 console.log(`Research failed: ${result.error}`);1150 break;1151 }1152 await new Promise(resolve => setTimeout(resolve, 10000));1153 }11541155### Java11561157 import com.google.genai.Client;1158 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1159 import com.google.genai.gaos.models.interactions.ImageContent;1160 import com.google.genai.gaos.models.interactions.ImageContentMimeType;1161 import com.google.genai.gaos.models.interactions.Interaction;1162 import com.google.genai.gaos.models.interactions.InteractionStatus;1163 import com.google.genai.gaos.models.interactions.InteractionsInput;1164 import com.google.genai.gaos.models.interactions.TextContent;1165 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1166 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;1167 import java.util.Arrays;1168 import java.util.Collections;11691170 Client client = new Client();11711172 String prompt =1173 "Analyze the interspecies dynamics and behavioral risks present "1174 + "in the provided image of the African watering hole. Specifically, investigate "1175 + "the symbiotic relationship between the avian species and the pachyderms "1176 + "shown, and conduct a risk assessment for the reticulated giraffes based on "1177 + "their drinking posture relative to the specific predator visible in the "1178 + "foreground.";11791180 CreateAgentInteraction params =1181 CreateAgentInteraction.builder()1182 .agent("deep-research-preview-04-2026")1183 .input(1184 InteractionsInput.ofContent(1185 Arrays.asList(1186 TextContent.builder().text(prompt).build(),1187 ImageContent.builder()1188 .mimeType(ImageContentMimeType.IMAGE_JPEG)1189 .uri(1190 "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg")1191 .build())))1192 .background(true)1193 .build();11941195 Interaction interaction =1196 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();11971198 System.out.println("Research started: " + interaction.id().orElse(""));11991200 while (true) {1201 interaction =1202 client.interactions1203 .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())1204 .interaction()1205 .get();1206 if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {1207 System.out.println(interaction.outputText().orElse(""));1208 break;1209 } else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {1210 System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));1211 break;1212 }1213 Thread.sleep(10000);1214 }12151216### REST12171218 # 1. Start the research task with image input1219 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1220 -H "Content-Type: application/json" \1221 -H "x-goog-api-key: $GEMINI_API_KEY" \1222 -d '{1223 "input": [1224 {"type": "text", "text": "Analyze the interspecies dynamics and behavioral risks present in the provided image of the African watering hole. Specifically, investigate the symbiotic relationship between the avian species and the pachyderms shown, and conduct a risk assessment for the reticulated giraffes based on their drinking posture relative to the specific predator visible in the foreground."},1225 {"type": "image", "mime_type": "image/jpeg", "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"}1226 ],1227 "agent": "deep-research-preview-04-2026",1228 "background": true1229 }'12301231 # 2. Poll for results (Replace INTERACTION_ID)1232 # curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \1233 # -H "x-goog-api-key: $GEMINI_API_KEY"12341235### Document understanding12361237Document understanding allows passing documents directly as multimodal input.1238The agent analyzes the1239provided documents and conducts research grounded in their content.12401241### Python12421243 from google import genai12441245 client = genai.Client()12461247 interaction = client.interactions.create(1248 agent="deep-research-preview-04-2026",1249 input=[1250 {"type": "text", "text": "What is this document about?"},1251 {1252 "type": "document",1253 "uri": "https://arxiv.org/pdf/1706.03762",1254 "mime_type": "application/pdf",1255 },1256 ],1257 background=True,1258 )12591260### JavaScript12611262 import { GoogleGenAI } from '@google/genai';12631264 const client = new GoogleGenAI({});12651266 const interaction = await client.interactions.create({1267 agent: 'deep-research-preview-04-2026',1268 input: [1269 { type: 'text', text: 'What is this document about?' },1270 {1271 type: 'document',1272 uri: 'https://arxiv.org/pdf/1706.03762',1273 mime_type: 'application/pdf'1274 }1275 ],1276 background: true1277 });12781279### Java12801281 import com.google.genai.Client;1282 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1283 import com.google.genai.gaos.models.interactions.DocumentContent;1284 import com.google.genai.gaos.models.interactions.DocumentContentMimeType;1285 import com.google.genai.gaos.models.interactions.Interaction;1286 import com.google.genai.gaos.models.interactions.InteractionsInput;1287 import com.google.genai.gaos.models.interactions.TextContent;1288 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1289 import java.util.Arrays;12901291 Client client = new Client();12921293 CreateAgentInteraction params =1294 CreateAgentInteraction.builder()1295 .agent("deep-research-preview-04-2026")1296 .input(1297 InteractionsInput.ofContent(1298 Arrays.asList(1299 TextContent.builder().text("What is this document about?").build(),1300 DocumentContent.builder()1301 .uri("https://arxiv.org/pdf/1706.03762")1302 .mimeType(DocumentContentMimeType.APPLICATION_PDF)1303 .build())))1304 .background(true)1305 .build();13061307 Interaction interaction =1308 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();13091310### REST13111312 # 1. Start the research task with document input1313 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1314 -H "Content-Type: application/json" \1315 -H "x-goog-api-key: $GEMINI_API_KEY" \1316 -d '{1317 "agent": "deep-research-preview-04-2026",1318 "input": [1319 {"type": "text", "text": "What is this document about?"},1320 {"type": "document", "uri": "https://arxiv.org/pdf/1706.03762", "mime_type": "application/pdf"}1321 ],1322 "background": true1323 }'13241325## Handling long-running tasks13261327Deep Research is a multi-step process involving planning, searching, reading,1328and writing. This cycle typically exceeds the standard timeout limits of1329synchronous API calls.13301331Agents are required to use `background=True`. The API returns a partial1332`Interaction` object immediately. You can use the `id` property to retrieve an1333interaction for polling. The interaction state will transition from1334`in_progress` to `completed` or `failed`. For a comprehensive guide on managing background tasks, see [Background execution](https://ai.google.dev/gemini-api/docs/background-execution).13351336### Streaming13371338Deep Research supports streaming to receive real-time updates on the research1339progress including thought summaries, text output, and generated images.1340You must set `stream=True` and `background=True`.13411342To receive intermediate reasoning steps (thoughts) and progress updates,1343you must enable **thinking summaries** by setting `thinking_summaries` to1344`"auto"` in the `agent_config`. Without this, the stream may only provide the1345final results.13461347> [!NOTE]1348> **Note:** The streaming connection can drop or expire. Since Deep Research tasks can run longer, your application should check the interaction status and reconnect as shown in the examples below.13491350#### Stream event types13511352| Event type | Delta type | Description |1353|---|---|---|1354| `step.delta` | `thought` | Intermediate reasoning step from the agent. |1355| `step.delta` | `text` | Part of the final text output. |1356| `step.delta` | `image` | A generated image (base64-encoded). |13571358The following example starts a research task and processes the stream with1359automatic reconnection. It tracks the `interaction_id` and `last_event_id` so1360that if the connection drops (for example, after the 600-second timeout), it can1361resume from where it left off.13621363### Python13641365 from google import genai13661367 client = genai.Client()13681369 interaction_id = None1370 last_event_id = None1371 is_complete = False13721373 def process_stream(stream):1374 global interaction_id, last_event_id, is_complete1375 for event in stream:1376 if event.event_type == "interaction.created":1377 interaction_id = event.interaction.id1378 if event.event_id:1379 last_event_id = event.event_id1380 if event.event_type == "step.delta":1381 if event.delta.type == "text":1382 print(event.delta.text, end="", flush=True)1383 elif event.delta.type == "thought":1384 print(f"Thought: {event.delta.text}", flush=True)1385 elif event.event_type in ("interaction.completed", "interaction.error"):1386 is_complete = True13871388 stream = client.interactions.create(1389 input="Research the history of Google TPUs.",1390 agent="deep-research-preview-04-2026",1391 background=True,1392 stream=True,1393 agent_config={"type": "deep-research", "thinking_summaries": "auto"},1394 )1395 process_stream(stream)13961397 # Reconnect if the connection drops1398 while not is_complete and interaction_id:1399 status = client.interactions.get(interaction_id)1400 if status.status != "in_progress":1401 break1402 stream = client.interactions.get(1403 id=interaction_id, stream=True, last_event_id=last_event_id,1404 )1405 process_stream(stream)14061407### JavaScript14081409 import { GoogleGenAI } from '@google/genai';14101411 const client = new GoogleGenAI({});14121413 let interactionId;1414 let lastEventId;1415 let isComplete = false;14161417 async function processStream(stream) {1418 for await (const event of stream) {1419 if (event.type === 'interaction.created') {1420 interactionId = event.interaction.id;1421 }1422 if (event.event_id) lastEventId = event.event_id;1423 if (event.type === 'step.delta') {1424 if (event.delta.type === 'text') {1425 process.stdout.write(event.delta.text);1426 } else if (event.delta.type === 'thought') {1427 console.log(`Thought: ${event.delta.text}`);1428 }1429 } else if (['interaction.completed', 'interaction.error'].includes(event.type)) {1430 isComplete = true;1431 }1432 }1433 }14341435 const stream = await client.interactions.create({1436 input: 'Research the history of Google TPUs.',1437 agent: 'deep-research-preview-04-2026',1438 background: true,1439 stream: true,1440 agent_config: { type: 'deep-research', thinking_summaries: 'auto' },1441 });1442 await processStream(stream);14431444 // Reconnect if the connection drops1445 while (!isComplete && interactionId) {1446 const status = await client.interactions.get(interactionId);1447 if (status.status !== 'in_progress') break;1448 const resumeStream = await client.interactions.get(interactionId, {1449 stream: true, last_event_id: lastEventId,1450 });1451 await processStream(resumeStream);1452 }14531454### Java14551456 import com.google.genai.Client;1457 import com.google.genai.gaos.models.interactions.Content;1458 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1459 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;1460 import com.google.genai.gaos.models.interactions.ErrorEvent;1461 import com.google.genai.gaos.models.interactions.Interaction;1462 import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;1463 import com.google.genai.gaos.models.interactions.InteractionCreatedEvent;1464 import com.google.genai.gaos.models.interactions.InteractionSSEEvent;1465 import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;1466 import com.google.genai.gaos.models.interactions.InteractionStatus;1467 import com.google.genai.gaos.models.interactions.InteractionsInput;1468 import com.google.genai.gaos.models.interactions.StepDelta;1469 import com.google.genai.gaos.models.interactions.TextContent;1470 import com.google.genai.gaos.models.interactions.TextDelta;1471 import com.google.genai.gaos.models.interactions.ThinkingSummaries;1472 import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;1473 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1474 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;1475 import com.google.genai.gaos.utils.EventStream;14761477 class StreamProcessor {1478 String interactionId = null;1479 String lastEventId = null;1480 boolean isComplete = false;14811482 void processStream(EventStream<InteractionSSEStreamEvent> stream) {1483 for (InteractionSSEStreamEvent streamEvent : stream) {1484 InteractionSSEEvent event = streamEvent.data().orElse(null);1485 if (event instanceof InteractionCreatedEvent) {1486 InteractionCreatedEvent created = (InteractionCreatedEvent) event;1487 interactionId = created.interaction().flatMap(i -> i.id()).orElse(null);1488 if (created.eventId().isPresent()) {1489 lastEventId = created.eventId().get();1490 }1491 } else if (event instanceof StepDelta) {1492 StepDelta stepDelta = (StepDelta) event;1493 if (stepDelta.eventId().isPresent()) {1494 lastEventId = stepDelta.eventId().get();1495 }1496 if (stepDelta.delta().isPresent()) {1497 if (stepDelta.delta().get() instanceof TextDelta) {1498 System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));1499 System.out.flush();1500 } else if (stepDelta.delta().get() instanceof ThoughtSummaryDelta) {1501 ThoughtSummaryDelta thought = (ThoughtSummaryDelta) stepDelta.delta().get();1502 Content content = thought.content().orElse(null);1503 if (content instanceof TextContent) {1504 System.out.println("Thought: " + ((TextContent) content).text().orElse(""));1505 }1506 }1507 }1508 } else if (event instanceof InteractionCompletedEvent || event instanceof ErrorEvent) {1509 isComplete = true;1510 }1511 }1512 }1513 }15141515 Client client = new Client();1516 StreamProcessor processor = new StreamProcessor();15171518 CreateAgentInteraction params =1519 CreateAgentInteraction.builder()1520 .agent("deep-research-preview-04-2026")1521 .input(InteractionsInput.of("Research the history of Google TPUs."))1522 .background(true)1523 .stream(true)1524 .agentConfig(1525 DeepResearchAgentConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())1526 .build();15271528 try (EventStream<InteractionSSEStreamEvent> stream =1529 client.interactions.create(CreateInteractionRequestBody.of(params)).events()) {1530 processor.processStream(stream);1531 }15321533 // Reconnect if the connection drops1534 while (!processor.isComplete && processor.interactionId != null) {1535 Interaction status =1536 client.interactions1537 .get(GetInteractionByIdRequest.builder().id(processor.interactionId).build())1538 .interaction()1539 .get();1540 if (!InteractionStatus.IN_PROGRESS.equals(status.status().orElse(null))) {1541 break;1542 }1543 try (EventStream<InteractionSSEStreamEvent> stream =1544 client.interactions1545 .get(1546 GetInteractionByIdRequest.builder()1547 .id(processor.interactionId)1548 .stream(true)1549 .lastEventId(processor.lastEventId)1550 .build())1551 .events()) {1552 processor.processStream(stream);1553 }1554 }15551556### REST15571558 # 1. Start the stream (save the INTERACTION_ID from the interaction.start event1559 # and the last "event_id" you receive)1560 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1561 -H "Content-Type: application/json" \1562 -H "x-goog-api-key: $GEMINI_API_KEY" \1563 -d '{1564 "input": "Research the history of Google TPUs.",1565 "agent": "deep-research-preview-04-2026",1566 "background": true,1567 "stream": true,1568 "agent_config": {1569 "type": "deep-research",1570 "thinking_summaries": "auto"1571 }1572 }'15731574 # 2. If the connection drops, reconnect with your saved IDs1575 curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID" \1576 -H "x-goog-api-key: $GEMINI_API_KEY"15771578## Follow-up questions and interactions15791580You can continue the conversation after the agent returns the final report by1581using the `previous_interaction_id`. This lets you to ask for clarification,1582summarization or elaboration on specific sections of the research without1583restarting the entire task.15841585### Python15861587 import time1588 from google import genai15891590 client = genai.Client()15911592 interaction = client.interactions.create(1593 input="Can you elaborate on the second point in the report?",1594 model="gemini-3.1-pro-preview",1595 previous_interaction_id="COMPLETED_INTERACTION_ID"1596 )15971598 print(interaction.steps[-1].content[0].text)15991600### JavaScript16011602 const interaction = await client.interactions.create({1603 input: 'Can you elaborate on the second point in the report?',1604 model: 'gemini-3.1-pro-preview',1605 previous_interaction_id: 'COMPLETED_INTERACTION_ID'1606 });1607 console.log(interaction.steps.at(-1).content[0].text);16081609### Java16101611 import com.google.genai.Client;1612 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1613 import com.google.genai.gaos.models.interactions.Interaction;1614 import com.google.genai.gaos.models.interactions.InteractionsInput;1615 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;16161617 Client client = new Client();16181619 CreateModelInteraction params =1620 CreateModelInteraction.builder()1621 .model("gemini-3.1-pro-preview")1622 .input(InteractionsInput.of("Can you elaborate on the second point in the report?"))1623 .previousInteractionId("COMPLETED_INTERACTION_ID")1624 .build();16251626 Interaction interaction =1627 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();16281629 System.out.println(interaction.outputText().orElse(""));16301631### REST16321633 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1634 -H "Content-Type: application/json" \1635 -H "x-goog-api-key: $GEMINI_API_KEY" \1636 -d '{1637 "input": "Can you elaborate on the second point in the report?",1638 "model": "gemini-3.1-pro-preview",1639 "previous_interaction_id": "COMPLETED_INTERACTION_ID"1640 }'16411642## When to use Gemini Deep Research agent16431644Deep Research is an **agent**, not just a model. It is best suited for workloads1645that require an "analyst-in-a-box" approach rather than low-latency chat.16461647| Feature | Standard Gemini Models | Gemini Deep Research agent |1648|---|---|---|1649| **Latency** | Seconds | Minutes (Async/Background) |1650| **Process** | Generate -\> Output | Plan -\> Search -\> Read -\> Iterate -\> Output |1651| **Output** | Conversational text, code, short summaries | Detailed reports, long-form analysis, comparative tables |1652| **Best For** | Chatbots, extraction, creative writing | Market analysis, due diligence, literature reviews, competitive landscaping |16531654## Agent configuration16551656Deep Research uses the `agent_config` parameter to control behavior.1657Pass it as a dictionary with the following fields:16581659| Field | Type | Default | Description |1660|---|---|---|---|1661| `type` | `string` | Required | Must be `"deep-research"`. |1662| `thinking_summaries` | `string` | `"none"` | Set to `"auto"` to receive intermediate reasoning steps during streaming. Set to `"none"` to disable. |1663| `visualization` | `string` | `"auto"` | Set to `"auto"` to enable agent-generated charts and images. Set to `"off"` to disable. |1664| `collaborative_planning` | `boolean` | `false` | Set to `true` to enable multi-turn plan review before research begins. |16651666### Python16671668 agent_config = {1669 "type": "deep-research",1670 "thinking_summaries": "auto",1671 "visualization": "auto",1672 "collaborative_planning": False,1673 }16741675 interaction = client.interactions.create(1676 agent="deep-research-preview-04-2026",1677 input="Research the competitive landscape of cloud GPUs.",1678 agent_config=agent_config,1679 background=True,1680 )16811682### JavaScript16831684 const interaction = await client.interactions.create({1685 agent: 'deep-research-preview-04-2026',1686 input: 'Research the competitive landscape of cloud GPUs.',1687 agent_config: {1688 type: 'deep-research',1689 thinking_summaries: 'auto',1690 visualization: 'auto',1691 collaborative_planning: false,1692 },1693 background: true,1694 });16951696### Java16971698 import com.google.genai.Client;1699 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1700 import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;1701 import com.google.genai.gaos.models.interactions.Interaction;1702 import com.google.genai.gaos.models.interactions.InteractionsInput;1703 import com.google.genai.gaos.models.interactions.ThinkingSummaries;1704 import com.google.genai.gaos.models.interactions.Visualization;1705 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;17061707 Client client = new Client();17081709 DeepResearchAgentConfig agentConfig =1710 DeepResearchAgentConfig.builder()1711 .thinkingSummaries(ThinkingSummaries.AUTO)1712 .visualization(Visualization.AUTO)1713 .collaborativePlanning(false)1714 .build();17151716 CreateAgentInteraction params =1717 CreateAgentInteraction.builder()1718 .agent("deep-research-preview-04-2026")1719 .input(InteractionsInput.of("Research the competitive landscape of cloud GPUs."))1720 .agentConfig(agentConfig)1721 .background(true)1722 .build();17231724 Interaction interaction =1725 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();17261727### REST17281729 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1730 -H "Content-Type: application/json" \1731 -H "x-goog-api-key: $GEMINI_API_KEY" \1732 -d '{1733 "input": "Research the competitive landscape of cloud GPUs.",1734 "agent": "deep-research-preview-04-2026",1735 "agent_config": {1736 "type": "deep-research",1737 "thinking_summaries": "auto",1738 "visualization": "auto",1739 "collaborative_planning": false1740 },1741 "background": true1742 }'17431744## Availability and pricing17451746You can access the Gemini Deep Research agent using the Interactions API in Google AI Studio and the Gemini API.17471748Pricing follows a [pay-as-you-go model](https://ai.google.dev/gemini-api/docs/pricing#pricing-for-agents) based on the underlying Gemini models and the specific tools the agent utilizes. Unlike standard chat requests, where a request leads to one output, a Deep Research task is an agentic workflow. A single request triggers an autonomous loop of planning, searching, reading, and reasoning.17491750### Estimated costs17511752Costs vary based on the depth of research required. The agent autonomously determines how much reading and searching is necessary to answer your prompt.17531754- **Deep Research** (`deep-research-preview-04-2026`): For a typical query requiring moderate analysis, the agent might use \~80 search queries, \~250k input tokens (\~50-70% cached), and \~60k output tokens.1755 - **Estimated total:** \~$1.00 -- $3.00 per task1756- **Deep Research Max** (`deep-research-max-preview-04-2026`): For deep competitive landscape analysis or extensive due diligence, the agent might use up to \~160 search queries, \~900k input tokens (\~50-70% cached), and \~80k output tokens.1757 - **Estimated total:** \~$3.00 -- $7.00 per task17581759> [!NOTE]1760> **Note:** These figures are estimates based on preview rates and are subject to change.17611762## Safety considerations17631764Giving an agent access to the web and your private files requires careful1765consideration of safety risks.17661767- **Prompt injection using files:** The agent reads the contents of the files you provide. Ensure that uploaded documents (PDFs, text files) come from trusted sources. A malicious file could contain hidden text designed to manipulate the agent's output.1768- **Web content risks:** The agent searches the public web. While we implement robust safety filters, there is a risk that the agent may encounter and process malicious web pages. We recommend reviewing the `citations` provided in the response to verify the sources.1769- **Exfiltration:** Be cautious when asking the agent to summarize sensitive internal data if you are also allowing it to browse the web.17701771## Best practices17721773- **Prompt for unknowns:** Instruct the agent on how to handle missing data. For example, add *"If specific figures for 2025 are not available,1774 explicitly state they are projections or unavailable rather than1775 estimating"* to your prompt.1776- **Provide context:** Ground the agent's research by providing background information or constraints directly in the input prompt.1777- **Use collaborative planning:** For complex queries, enable collaborative planning to review and refine the research plan before execution.1778- **Multimodal inputs:** Deep Research agent supports multi-modal inputs. Use cautiously, as this increases costs and risks context window overflow.17791780## Limitations17811782- **Custom tools:** You cannot currently provide custom Function Calling tools but you can use remote MCP (Model Context Protocol) servers with the Deep Research agent.1783- **Structured output:** The Deep Research agent currently doesn't support structured outputs.1784- **Max research time:** The Deep Research agent has a maximum research time of 60 minutes. Most tasks should complete within 20 minutes.1785- **Store requirement:** Agent execution using `background=True` requires `store=True`.1786- **Google search:** [Google1787 Search](https://ai.google.dev/gemini-api/docs/google-search) is enabled by default and [specific1788 restrictions](https://ai.google.dev/gemini-api/terms#use-restrictions2) apply to the grounded results.17891790## What's next17911792- Learn more about the [Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview).1793- Learn how to use your own data using the [File Search](https://ai.google.dev/gemini-api/docs/file-search) tool.