使用 Gemini Deep Research Agent

Gemini Deep Research Agent 是一款受管理的 AI 智能体，旨在规划、执行和整合复杂的多步骤研究工作流。在 Gemini 的支持下，该代理可浏览各种信息环境（包括公共网站和私有企业数据），生成包含引用来源的综合报告，从而加快明智决策的制定。

本页面介绍了如何使用 Gemini Deep Research 智能体，包括其主要功能和限制、如何开始研究任务，以及如何处理超时和错误处理。

何时使用 Deep Research

Deep Research 是一种智能体，而不仅仅是一种模型。它最适合允许采用异步分析方法的工作负载，而不是低延迟聊天。

在规划项目时，请考虑 Deep Research 的以下优势：

  • 迭代流程：Deep Research 不会像标准聊天模型那样立即生成回答，而是遵循有条不紊的多步骤工作流程：规划 > 多来源搜索 > 迭代 > 输出。

  • 高级工作负载：Deep Research 专门用于处理尽职调查、市场分析和竞争格局分析等复杂任务。

  • 广泛的数据基础：Gemini Deep Research 智能体可以同时对各种数据源进行推理。这包括远程 MCP 服务器、内部机构知识，以及来自上传文件或文件夹的直接上下文。

  • 精美的报告：它会生成包含引用内容的全面报告，其中可能包含可直接用于演示的视觉内容。这些图表包括财务图表、内嵌信息图表和市场定位矩阵，它们是使用 HTML 和图片模型生成的。

  • 高度可控：您可以在提示中直接对最终输出进行高度自定义。这包括设置特定语气（例如技术性或高管语气）、定义严格的格式或请求结构化数据表。

下表从多个不同的指标（包括延迟时间、输出内容以及每种模型最适合的用途）比较了 Gemini Deep Research Agent 与标准 Gemini 模型：

功能 标准 Gemini 模型 Gemini Deep Research 智能体
延迟时间 秒 分钟
流程 生成 → 输出 计划 → 多来源搜索 → 迭代 → 输出
输出 对话风格的文本和代码 包含内嵌图表和图片的详细报告（附有引用）
最佳适用场景 聊天机器人、信息提取、总结 市场分析、深入研究、竞争格局分析

主要功能

Deep Research 具有以下特性和功能：

  • 基于多个来源的接地，包括：
  • 图片和图表输出：生成包含可直接用于演示的资源的详细报告，例如内嵌信息图、市场定位矩阵图和财务表现图
  • 内嵌引用

如何使用 Deep Research

您可以使用 Google Gen AI SDK 或直接 REST API 请求，通过全局端点 (v1beta1) 访问 Gemini Deep Research Agent。如需查看使用示例，请参阅 GitHub 上的 Gemini Deep Research Agent 笔记本简介。

准备工作

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

开始执行 Deep Research 任务

研究任务涉及反复搜索和阅读，可能需要几分钟才能完成。您必须通过将 background 设置为 True 来异步运行 Gemini Deep Research 代理。

您可以使用 Gemini Deep Research 智能体，无论是否启用流式传输：

  • 轮询（非流式）：设置 background=True（以及可选的 stream=False）。API 会立即返回 Interaction 对象。您可以使用 id 属性轮询互动，直到状态从 in_progress 转换为 completed 或 failed。
  • 流式传输：设置 background=True 和 stream=True，以便在研究取得进展时接收实时更新。如需了解详情，请参阅流式传输。

您还可以将代理配置为使用延迟层，该层会自动安排在非高峰时段以 50% 的折扣率运行后台作业。如需使用延迟层，必须在创建任务期间将 stream 设置为 False。

Python


import time
from google import genai

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

interaction = client.interactions.create(
  input="Analyze competitive positioning for solar energy providers.",
  agent="deep-research-preview-04-2026",
  background=True,
  stream=False,
  service_tier="deferred"
)

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)

REST

PROJECT_ID=PROJECT_ID;
curl --max-time 3600 --keepalive-time 10 -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
    -d '{
      "input": "Research the history of Google TPUs.",
      "agent": "deep-research-preview-04-2026",
      "background": true,
      "stream": false,
      "service_tier": "deferred"
    }'

该 API 会立即返回 interaction_id。您可以使用此 ID 轮询状态或重新连接到数据流。

流式

Deep Research 支持流式传输，可实时接收研究进度更新，包括思路总结、文本输出和生成的图片。使用流式传输时，请设置 background=True 和 stream=True。

以下示例启动了一项研究任务，并处理了具有自动重新连接功能的流。它会跟踪 interaction_id 和 last_event_id，以便在连接断开时从中断处继续。


from google import genai

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

interaction_id = None
last_event_id = None
is_complete = False

def process_stream(stream):
  global interaction_id, last_event_id, is_complete
  for event in stream:
    if event.event_type == "interaction.created":
      interaction_id = event.interaction.id
    if event.event_id:
      last_event_id = event.event_id
    if event.event_type == "step.delta":
      if event.delta.type == "text":
        print(event.delta.text, end="", flush=True)
      elif event.delta.type == "thought":
        print(f"Thought: {event.delta.text}", flush=True)
    elif event.event_type in ("interaction.completed", "error"):
      is_complete = True

stream = client.interactions.create(
  input="Research the history of Google TPUs.",
  agent="deep-research-preview-04-2026",
  background=True,
  stream=True,
  agent_config={"type": "deep-research", "thinking_summaries": "auto"},
)

process_stream(stream)

while not is_complete and interaction_id:
  status = client.interactions.get(interaction_id)
  if status.status != "in_progress":
    break
  stream = client.interactions.get(
    id=interaction_id, stream=True, last_event_id=last_event_id,
  )
  process_stream(stream)

重新连接到互动数据流

如需恢复已丢弃的直播，请使用原始 interaction_id 提交 GET 请求。该 API 将从会话开始时重放所有过去的事件，然后再继续进行实时更新。

Python


response = client.interactions.get(
  id = 'INTERACTION_ID',
  stream=True
)
for chunk in response:
  print(chunk)

REST

PROJECT_ID=PROJECT_ID;
INTERACTION_ID=INTERACTION_ID

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions/${INTERACTION_ID}"

工具

Deep Research 支持多种内置工具和外部工具。 默认情况下（未提供任何工具参数时），智能体有权访问 Google 搜索和网址上下文。您可以明确指定工具来限制或扩展智能体的功能。支持的工具包括：

工具 键 注意
Google 搜索 google_search 搜索公开网络。 默认处于启用状态。
MCP 服务器 mcp_server 连接到远程 MCP 服务器以访问外部工具。
企业版 Google 网页搜索 enterprise_web_search 具有额外合规性控制功能的网页搜索。
Agent Search vertex_ai_search 搜索网站数据或文档集。

以下配置可将 Google 搜索设为唯一工具：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="What are the latest developments in quantum computing?",
  tools=[{"type": "google_search"}],
  background=True,
  stream=True
)

MCP 服务器

在工具配置中提供服务器名称和网址。您还可以传递身份验证凭据，并限制智能体可以调用的工具。

请参阅以下参考资料：

字段 类型 必填 说明
type 字符串 是 必须为 "mcp_server"。
name 字符串 否 MCP 服务器的显示名称。
url 字符串 无 MCP 服务器端点的完整网址。
headers 对象 否 以 HTTP 标头形式随每个请求发送到服务器的键值对（例如身份验证令牌）。
allowed_tools array 无 限制代理可以调用的服务器工具。

请参阅以下示例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="How to deploy an app to Cloud Run on Google Cloud?",
  tools=[
    {
      "type": "mcp_server",
      "name": "Google Cloud Developer Knowledge",
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {"Authorization": "Bearer token"},
    }
  ],
  background=True,
  stream=True
)

借助企业网络搜索，组织可以根据安全、合规且最新的网络数据为生成式 AI 回答提供依据。它使开发者和企业能够将 AI 模型连接到互联网，同时确保数据隐私权和监管合规。

请参阅以下示例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="Research on the latest trend on AI",
  tools=[
    {
      "type": "google_search",
      "search_type": ["enterprise_web_search"],
    }
  ],
  background=True,
  stream=True
)

多模态输入

Deep Research 支持多模态输入，包括图片和文档 (PDF)，使代理能够分析视觉内容，并根据提供的输入进行基于网络的上下文相关研究。

请参阅以下示例：


prompt = """
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.
"""

interaction = client.interactions.create(
  input=[
    {"type": "text", "text": prompt},
    {
      "type": "image",
      "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
    }
  ],
  agent="deep-research-preview-04-2026",
  background=True,
  stream=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)

文档理解

您可以直接将文档作为多模态输入内容传递。智能体分析提供的文档，并根据其内容进行研究。

请参阅以下示例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input=[
    {"type": "text", "text": "What is this document about?"},
    {
      "type": "document",
      "uri": "https://arxiv.org/pdf/1706.03762",
      "mime_type": "application/pdf",
    },
  ],
  background=True,
  stream=True
)

可操纵性和格式设置

您可以在提示中提供具体的格式设置说明，从而引导智能体的输出。这样一来，您就可以将报告整理成特定的部分和子部分，添加数据表格，或针对不同的受众群体调整语气，例如“技术”“高管”或“休闲”。

在输入文本中明确定义输出。请参阅以下示例：


prompt = """
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
"""

interaction = client.interactions.create(
    input=prompt,
    agent="deep-research-preview-04-2026",
    background=True,
    stream=True
)

API 参考文档

本部分提供了有关使用 Gemini Deep Research 智能体的 API 参考文档。

如需了解详情，请参阅Interactions API。

方法：interactions.create

全名： projects.locations.interactions.create

发起新的 Deep Research 会话。

端点

帖子 https://aiplatform.googleapis.com/v1beta1/{parent}/interactions

请求正文参数

请求正文参数可以包含以下内容：

参数 类型 说明
agent string 必需。指定代理 ID 代码（例如 deep-research-preview-04-2026）。
background boolean 必需。异步运行互动。 必须设置为 true。
stream boolean 可选。启用流式传输。默认值为 false。
input array 或 string 必需。包含用户输入的列表。仅支持单个对象。
tools array 替换默认工具。支持 google_search、external_data_mcp、vertex_search 等。
service_tier string 设置为 deferred 可使用延迟层，该层会自动安排在非高峰时段运行后台作业。

超时和错误处理

与智能体互动时，您可能会遇到连接超时或系统错误。本部分介绍了如何识别和解决软超时和硬故障。

软超时

当智能体仍在处理请求时，如果 Interactions API 连接断开，就会发生软超时。智能体会在后台继续执行请求。

如需恢复会话并查看重放的活动，请使用 interaction_id 重新连接到直播。请参阅重新连接到互动数据流。

硬故障

当代理或内部系统错误完全终止代理上下文时，会发生严重故障。这些错误通常会返回 HTTP 500 状态代码。常见原因包括超出 120 分钟的执行时间限制或遇到系统故障。

如需解决此失败问题，请停止当前会话，并在开始新会话之前优化查询。

最佳做法

向自主代理授予对网络和文件的访问权限会带来独特的动态。在实施项目时，请考虑以下最佳实践：

  • 针对未知情况的提示：明确指示代理如何处理缺失的数据。例如，您可以让它说明某个数据是否不可用，而不是估计该数据。

  • 避免提示注入风险：确保上传的文件来自可信来源，因为恶意文件可能包含旨在操纵智能体输出的隐藏文字。

  • 避免数据渗漏：在要求智能体总结敏感的内部数据，同时允许其浏览公共网络时，请务必格外谨慎。

  • 验证引用：虽然系统会应用企业级过滤，但请务必始终验证回答中提供的引用，以确保网络来源可靠。

限制

在规划项目时，请考虑以下限制：

  • 仅支持单轮：仅支持单轮查询。不支持使用该 API 的 previous_interaction_id 字段。

  • 企业安全性：在预览期间，不支持客户管理的加密密钥 (CMEK) 和 VPC Service Controls。多区域数据驻留限制正在评估中。

  • 缓存：此服务默认启用隐式缓存。 无法关闭。

  • 数据保留：提示和生成的输出会存储 7 天以进行标准处理。使用“依托 Google 搜索进行接地”时，Google 会将提示、上下文信息和生成的输出内容存储 3 天，以便进行调试和测试。如果您使用“依托 Google 搜索进行接地”，则无法关闭此类信息的存储功能。如果您要求零数据保留，建议使用“接地”功能搭配企业版 Google 搜索。

价格

Deep Research 使用 Gemini 的高级推理功能来执行多步骤的智能体研究任务。结算包括模型使用情况（token）和工具执行情况（搜索和 grounding）。

对于后台作业，您可以使用延迟层来享受折扣。

如需了解详情，请参阅价格。

费用跟踪

默认情况下，Gemini Deep Research Agent 会自动将 is_deep_research 用户标签应用于其操作。在 Cloud de Confiance by S3NS中，标签是轻量级的键值对，用于整理资源和跟踪整个基础架构中的费用。

  • 自动添加标签：您无需在 API 请求中手动配置此标签；默认情况下，代理会为所有已执行的任务添加 is_deep_research 标签。

  • 结算过滤：您可以使用 is_deep_research 结算标签过滤 Deep Research 结算报告。

  • 全面跟踪：is_deep_research 结算标签适用于模型使用情况（输入和输出 token）以及工具执行情况（搜索和依据使用情况）。这有助于您汇总和计算异步研究工作流的总成本。

配额

为了应对更高的流量、并发后台任务或更繁重的研究负载，您可以直接在 Cloud de Confiance 项目中申请提高 Agent Platform API 的配额。

如需增加配额，请执行以下操作：

  1. 在 Cloud de Confiance 控制台中，前往配额和系统限制页面。

    前往“Quotas and system limits”（配额和系统限制）页面

  2. 确保您已选择运行 Deep Research 工作负载的正确项目。

  3. 在过滤条件搜索框中，搜索 Agent Platform API (aiplatform.googleapis.com)，以查找相关的代理和互动配额。

  4. 选择需要调整的具体配额限制。

  5. 点击修改配额。

  6. 在配额更改对话框的新值字段中，输入您请求的限额。在请求说明中提供明确的理由。 提及您的具体 Deep Research 使用情形、后台执行需求和预期流量模式有助于加快审批流程。

  7. 点击提交请求。

合规性和安全性

本部分介绍了数据的保留和缓存方式，并列出了在预览期间不受支持的安全控制措施。

数据保留

提示和生成的内容会存储七 (7) 天，以便进行标准处理。

如服务专用条款第 19 条“生成式 AI 服务：依托 Google 搜索进行接地”中所述，Google 会存储客户可能提供的提示和上下文信息，以及生成的输出内容，存储期限为 3 天，目的是生成基于事实结果和搜索建议；存储的这些信息可能会用于调试和测试支持“依托 Google 搜索进行接地”功能的系统。如果您使用“依托 Google 搜索进行接地”，则无法禁止存储此类信息。如果您要求零数据保留，建议使用企业版 Web Grounding。

缓存

对于 Deep Research，隐式缓存默认处于启用状态，并且无法停用。

安全控制

在预览版期间，不支持以下安全控制：

  • 客户管理的加密密钥 (CMEK)
  • VPC-Service Controls (VPC-SC)
  • Access Transparency (AXT)
  • 数据驻留
  • 多区域数据驻留

后续步骤

参考文档

了解 Interactions API，该 API 可让您与智能体互动。

教程

首先，在 GitHub 上使用此 Deep Research Python 笔记本。