Generative AI Google Brain

gemini-deep-research-intro-deep-research

3 min read

Introduction to Gemini Deep Research Agent

Source notebook

Repo path: gemini/deep-research/intro_deep_research.ipynb · Open on GitHub · intermediate

Shows how to run Gemini Deep Research Agent with streaming, multimodal input/output, and grounding tools.

Summary

This notebook introduces the Deep Research Agent on Agent Platform as an autonomous research agent for multi-step research tasks. It demonstrates setting up the Google Gen AI SDK, creating background interactions, reconnecting to streams, handling text, PDF, HTML, image, and citation outputs, and grounding research with MCP servers, enterprise web search, and Agent Search.

Key code patterns

Create GenAI client

from google import genai
 
client = genai.Client(
    enterprise=True,
    project=PROJECT_ID,
    location="global",
)

Configures the enterprise Gen AI client for Agent Platform in the global location.

Start background interaction

interaction = client.interactions.create(
    agent=AGENT_ID,
    input=[UserInputStep(
        type="user_input",
        content=[TextContent(type="text", text=prompt)],
    )],
    background=True,
    tools=[],
)
interaction_id = interaction.id

Starts a long-running Deep Research task and preserves the interaction ID for retrieval.

Stream or reconnect results

stream = client.interactions.get(
    id=interaction_id,
    stream=True,
)
for event in stream:
    if content := getattr(event, "delta", getattr(event, "step", None)):
        render_content(content)

Streams progress and output, supporting recovery after network interruption or timeout.

PDF input

DocumentContent(
    type="document",
    mime_type="application/pdf",
    uri=http_url,
)

Adds a PDF from an HTTP URL or Cloud Storage URI as multimodal input.

Vertex AI Search retrieval

tools=[{
    "type": "retrieval",
    "retrieval_types": ["vertex_ai_search"],
    "vertex_ai_search_config": {
        "engine": engine_path,
        "datastores": [datastore_path],
    },
}]

Connects Deep Research Agent to an Agent Search data store for internal corpus grounding.

Models & APIs used

  • Models: Gemini 3.1 Pro
  • APIs / services: Vertex AI, Agent Platform, Agent Platform API, Google Search, Agent Search
  • SDKs / libraries: google-genai, beautifulsoup4

When to use this

Use this pattern for comprehensive, long-running research tasks that need web, document, or enterprise corpus grounding.

Gotchas & caveats

  • Agent Platform API must be enabled in an existing Google Cloud project.
  • LOCATION is set to global.
  • Deep Research requires background=True and stream=True for the documented workflow.
  • Only text inputs are supported for the single-turn query flow described.
  • Stateful conversation management is not supported.
  • Deep Research tasks may take minutes to complete.
  • The interaction_id must be saved to retrieve results after timeout or interruption.
  • Uploaded files should come from trusted sources due to prompt injection risk.

Best practices

  • Save the interaction_id immediately after initialization.
  • Use specific formatting instructions in the prompt to shape reports, sections, tables, and tone.
  • Prompt the agent to state when data is unavailable instead of estimating it.
  • Be cautious when combining sensitive internal data with public web browsing.
  • Verify citations returned by the agent.

Graph View

Backlinks