Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 Gemini Deep Research Agent

Gemini Deep Research 智能体是一种代管式 AI 智能体，旨在规划、执行和综合复杂的、多步骤的研究工作流。该智能体由 Gemini 提供支持，可浏览各种信息环境（包括公共网络和私有企业数据），生成全面的、附有引用的报告，从而加快基于充分信息做出决策的速度。

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

何时使用 Deep Research

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

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

迭代过程：Deep Research 不像标准聊天模型那样生成即时回答，而是遵循有条不紊的多步骤工作流：规划 > 多来源搜索 > 迭代 > 输出。
高级工作负载：Deep Research 专门用于处理复杂的任务，例如尽职调查、市场分析、和竞争格局分析。
广泛的数据依据：Gemini Deep Research 智能体可以同时基于各种数据来源进行推理。这些来源包括远程 MCP 服务器、内部机构知识，以及来自上传文件或文件夹的直接上下文。
精美的报告：它可以生成全面的、附有引用的报告，其中可以包含可直接用于演示的视觉内容。这些内容包括财务图表、内嵌信息图表和市场定位矩阵，它们是使用 HTML 和图片模型生成的。
高度可控：您可以直接在提示中大幅自定义最终输出。这包括设置特定语气（例如技术或高管）、定义严格的格式或请求结构化数据表。

下表从多个不同的指标（包括延迟时间、输出内容和最适合的用途）对 Gemini Deep Research 智能体和标准 Gemini 模型进行了比较：

功能	标准 Gemini 模型	Gemini Deep Research 智能体
延迟时间	秒	分钟
处理过程	生成 → 输出	规划 → 多来源搜索 → 迭代 → 输出
输出内容	对话风格的文本和代码	详细的、附有引用的报告，其中包含内嵌图表和图片
适用场景	聊天机器人、信息提取、摘要生成	市场分析、深度研究、竞争格局分析

主要功能

Deep Research 具有以下功能：

基于多个来源进行接地，包括：
- 远程 MCP 服务器
- 依托 Agent Search 进行接地
- 依托 Google 搜索或企业版 Web Grounding 进行接地，这些功能以严格的隐私权和过滤标准为后盾，适合企业工作负载
- 内嵌文件和文件夹上传（例如 PDF 和电子表格），让您可以将上下文直接放入研究工作流并获取引用
图片和图表输出：生成详细的报告，其中包含可直接用于演示的资产，例如内嵌信息图表、市场定位矩阵图表和财务业绩图表
内嵌引用

如何使用 Deep Research

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

准备工作

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
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

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 Google Cloud 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 Google Cloud 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 任务

研究任务涉及迭代搜索和阅读，可能需要几分钟才能完成。您必须异步运行 Gemini Deep Research 智能体。

您必须使用后台执行和流式模式。为此，请在运行智能体时，将响应配置中的 background 和 stream 字段设置为 True。API 会立即返回部分 Interaction 对象。您可以使用 id 属性检索用于轮询的互动。互动状态将从 in_progress 转换为 completed 或 failed。

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
)

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": true
    }'

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 搜索

以下代码将 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`	数组	否	限制智能体可以调用的服务器中的工具。

请参阅以下示例：


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
)

企业版 Google 网页搜索

借助企业版 Google 网页搜索，组织可以基于安全、合规且最新的网页数据来生成式 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 会话。

端点

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

请求正文参数

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

参数	类型	说明
`agent`	`string`	必需。指定智能体 ID 代码（例如 `deep-research-preview-04-2026`）。
`background`	`boolean`	必需。异步运行互动。必须设置为 `true`。
`stream`	`boolean`	必需。启用流式传输。必须设置为 `true`。
`input`	`array` 或 `string`	必需。包含用户输入的列表。仅支持单个对象。
`tools`	`array`	替换默认工具。支持 `google_search`、`external_data_mcp`、`vertex_search` 等。

超时和错误处理

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

软超时

当智能体仍在处理请求时，如果 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）和工具执行情况（搜索和接地）。

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

费用跟踪

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

自动添加标签：您无需在 API 请求中手动配置此标签；智能体默认会为所有执行的任务添加 is_deep_research 标签。
结算过滤：Deep Research 结算报告可以使用 is_deep_research 结算标签过滤。
全面跟踪：is_deep_research 结算标签适用于模型使用情况（输入和输出 token）和工具执行情况（搜索和接地使用情况）。这有助于您汇总和计算异步研究工作流的总费用。

Quota

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

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

在 Google Cloud 控制台中，前往配额和系统限制 页面。

前往“Quotas and system limits”（配额和系统限制）页面
确保您已选择运行 Deep Research 工作负载的正确项目。
在过滤条件搜索框中，搜索 Agent Platform API (aiplatform.googleapis.com)，以查找相关的智能体和互动配额。
选择需要调整的特定配额限制。
点击修改配额 。
在配额更改 对话框的新值字段中，输入您请求的限制。在请求说明中提供明确的理由。提及您的具体 Deep Research 用例、后台执行需求和预期流量模式有助于加快审批流程。
点击提交请求 。

合规性和安全性

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

数据保留

提示和生成的输出内容会存储 7 天，以进行标准处理。

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

缓存

默认情况下， Deep Research 启用隐式缓存，无法关闭。

安全控制

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

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

后续步骤

参考文档

Interactions API 参考文档

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

教程

笔记本：Gemini Deep Research 智能体简介

在 GitHub 上开始使用此 Deep Research Python 笔记本。

使用 Gemini Deep Research Agent 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

何时使用 Deep Research

主要功能

如何使用 Deep Research

准备工作

Check for the roles

Grant the roles

开始执行 Deep Research 任务

Python

REST

流式

重新连接到互动数据流

Python

REST

工具

Google 搜索

MCP 服务器

企业版 Google 网页搜索

多模态输入

文档理解

可控性和格式设置

API 参考文档

方法：interactions.create

端点

请求正文参数

超时和错误处理

软超时

硬故障

最佳做法

限制

价格

费用跟踪

Quota

合规性和安全性

数据保留

缓存

安全控制

后续步骤

Interactions API 参考文档

笔记本：Gemini Deep Research 智能体简介

使用 Gemini Deep Research Agent