Gemini 中文指南
获取 API 密钥 ↗

Gemini Deep Research 智能体

↓ 下载 MarkdownInteractions API

Gemini Deep Research 智能体自主规划、执行和综合多步骤研究任务。它由 Gemini 提供支持,可导航复杂的信息环境,生成详细的引用报告。新功能允许您与智能体协作规划、使用 MCP 服务器连接到外部工具、包括可视化(如图表和图形),并直接提供文档作为输入。

研究任务涉及迭代搜索和阅读,可能需要几分钟才能完成。您必须使用后台执行(设置 background=true)异步运行智能体并轮询结果或流更新。参见 处理长时间运行的任务 了解更多详情。

以下示例展示了如何在后台启动研究任务并轮询结果。

python
import time
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.steps[-1].content[0].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)

支持的版本 #

Deep Research 智能体有两个版本:

  • Deep Research (deep-research-preview-04-2026):专为速度和效率而设计,非常适合流回客户端 UI。
  • Deep Research Max (deep-research-max-preview-04-2026):自动上下文收集和合成的最大综合性。

协同规划 #

协作规划使您可以在智能体开始工作之前控制研究方向。启用后,智能体返回建议的研究计划,而不是立即执行。然后,您可以通过多轮交互来审核、修改或批准该计划。

步骤 1:请求计划 #

套装 collaborative_planning=True 在第一次互动中。 智能体返回研究计划而不是完整报告。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

# First interaction: request a research plan
plan_interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Do some research on Google TPUs.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    background=True,
)

# Wait for and retrieve the plan
while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)

步骤 2:细化计划(可选) #

使用 previous_interaction_id 继续对话并迭代计划。保留 collaborative_planning=True 保持计划模式。

python
# Second interaction: refine the plan
refined_plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    previous_interaction_id=plan_interaction.id,
    background=True,
)

while (result := client.interactions.get(id=refined_plan.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)

步骤3:批准并执行 #

套装 collaborative_planning=False (或省略)批准计划并开始研究。

python
# Third interaction: approve the plan and kick off research
final_report = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Plan looks good!",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": False,
    },
    previous_interaction_id=refined_plan.id,
    background=True,
)

while (result := client.interactions.get(id=final_report.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)

可视化 #

当 visualization 设置为 "auto",智能体可以生成图表、图形和其他视觉元素来支持其研究结果。生成的图像包含在响应步骤中并作为流式传输 image 三角洲。为了获得最佳结果,请在查询中明确要求提供视觉效果 - 例如,“包括显示随时间变化的趋势的图表”或“生成比较市场份额的图形”。设置 visualization 到 "auto" 启用该功能,但智能体仅在提示请求时才生成视觉效果。

python
import base64

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Analyze global semiconductor market trends. Include graphics showing market share changes.",
    agent_config={
        "type": "deep-research",
        "visualization": "auto",
    },
    background=True,
)

print(f"Research started: {interaction.id}")

while (result := client.interactions.get(id=interaction.id)).status != "completed":
    time.sleep(5)

for step in result.steps:
    if step.type == "model_output":
        for content_item in step.content:
            if content_item.type == "text":
                print(content_item.text)
            elif content_item.type == "image" and content_item.data:
                image_bytes = base64.b64decode(content_item.data)
                print(f"Received image: {len(image_bytes)} bytes")

支持的工具 #

Deep Research支持多种内置和外部工具。默认情况下(当没有 tools 提供参数),智能体可以访问 Google 搜索、URL 上下文和代码执行。您可以显式指定工具来限制或扩展智能体的功能。

工具类型值说明
Google 搜索google_search搜索公共网络。默认启用。
URL上下文url_context阅读并总结网页内容。默认启用。
代码执行code_execution执行代码以执行计算和数据分析。默认启用。
MCP服务器mcp_server连接到远程 MCP 服务器以进行外部工具访问。
文件搜索file_search搜索您上传的文档语料库。

显式启用 Google 搜索作为唯一工具:

python
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,
)

URL上下文 #

赋予智能体读取和总结特定网页的能力:

python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Summarize the content of https://www.wikipedia.org/.",
    tools=[{"type": "url_context"}],
    background=True,
)

代码执行 #

允许智能体执行计算和数据分析的代码:

python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Calculate the 50th Fibonacci number.",
    tools=[{"type": "code_execution"}],
    background=True,
)

MCP 服务器 #

提供服务器 name 和 url 在工具配置中。您还可以传递身份验证凭据并限制智能体可以调用哪些工具。

领域类型必填说明
typestring是的必须是 "mcp_server".
namestring否MCP 服务器的显示名称。
urlstring否MCP 服务器端点的完整 URL。
headersobject否键值对作为 HTTP 标头随每个请求发送到服务器(例如,身份验证 token)。
allowed_toolsarray否限制智能体可以调用服务器上的哪些工具。

基本用法 #

python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Check the status of my last server deployment.",
    tools=[
        {
            "type": "mcp_server",
            "name": "Deployment Tracker",
            "url": "https://mcp.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"},
        }
    ],
    background=True,
)

使用以下命令让智能体访问您自己的数据 文件搜索 工具。

python
import time
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    input="Compare our 2025 fiscal year report against current public web news.",
    agent="deep-research-preview-04-2026",
    background=True,
    tools=[
        {
            "type": "file_search",
            "file_search_store_names": ['fileSearchStores/my-store-name']
        }
    ]
)

可操纵性和格式化 #

您可以通过在提示中提供特定的格式说明来控制智能体的输出。这允许您将报告构建为特定的部分和小节,包括数据表,或调整不同受众的基调(例如“技术”、“执行”、“休闲”)。

在输入文本中明确定义所需的输出格式。

python
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
)

多模态输入 #

Deep Research 支持多模态输入,包括图像和文档 (PDF),允许智能体分析视觉内容并根据所提供的输入进行基于网络的研究。

python
import time
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

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",
            "mime_type": "image/jpeg",
            "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
        }
    ],
    agent="deep-research-preview-04-2026",
    background=True
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.steps[-1].content[0].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)

文档理解 #

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

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

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,
)

处理长时间运行的任务 #

Deep Research 是一个涉及计划、搜索、阅读和写作的多步骤过程。此周期通常超出同步 API 调用的标准超时限制。

需要使用智能体 background=True。 API 返回部分 Interaction 立即反对。您可以使用 id 属性来检索轮询的交互。交互状态将从 in_progress 到 completed 或 failed.

流式输出 #

Deep Research支持流式传输以接收研究进展的实时更新,包括思想摘要、文本输出和生成的图像。您必须设置 stream=True 和 background=True.

要接收中间推理步骤(想法)和进度更新,您必须启用 思考总结 通过设置 thinking_summaries 到 "auto" 在 agent_config。如果没有这个,流可能只能提供最终结果。

流事件类型 #

事件类型三角型说明
step.deltathought智能体的中间推理步骤。
step.deltatext最终文本输出的一部分。
step.deltaimage生成的图像(base64 编码)。

以下示例启动研究任务并通过自动重新连接处理流。它跟踪 interaction_id 和 last_event_id 这样,如果连接断开(例如,在 600 秒超时之后),它可以从中断的位置恢复。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

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", "interaction.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)

# Reconnect if the connection drops
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)

后续问题和互动 #

智能体返回最终报告后,您可以使用 previous_interaction_id。这使您可以要求对研究的特定部分进行澄清、总结或阐述,而无需重新启动整个任务。

python
import time
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    input="Can you elaborate on the second point in the report?",
    model="gemini-4-carbon",
    previous_interaction_id="COMPLETED_INTERACTION_ID"
)

print(interaction.steps[-1].content[0].text)

何时使用 Gemini Deep Research 智能体 #

Deep Research 是 智能体,不仅仅是一个模型。它最适合需要“一体式分析师”方法而不是低延迟聊天的工作负载。

特点标准 Gemini 型号Gemini Deep Research 智能体
延迟秒数分钟(异步/后台)
工艺流程生成->输出计划 -> 搜索 -> 读取 -> 迭代 -> 输出
输出对话文本、代码、简短摘要详细报告、长篇分析、比较表格
最适合聊天机器人、提取、创意写作市场分析、尽职调查、文献综述、竞争格局

智能体配置 #

Deep Research 使用 agent_config 控制行为的参数。将其作为具有以下字段的字典传递:

领域类型默认说明
typestring必填必须是 "deep-research".
thinking_summariesstring"none"设置为 "auto" 在流式传输期间接收中间推理步骤。设置为 "none" 禁用。
visualizationstring"auto"设置为 "auto" 启用智能体生成的图表和图像。设置为 "off" 禁用。
collaborative_planningbooleanfalse设置为 true 在研究开始之前启用多轮计划审查。
python
agent_config = {
    "type": "deep-research",
    "thinking_summaries": "auto",
    "visualization": "auto",
    "collaborative_planning": False,
}

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the competitive landscape of cloud GPUs.",
    agent_config=agent_config,
    background=True,
)

供货情况和定价 #

您可以使用 Google AI Studio 和 Gemini API 中的 Interactions API 访问 Gemini Deep Research、智能体。

定价遵循 现收现付模式 基于底层 Gemini 模型和智能体使用的特定工具。与标准聊天请求(请求导致一个输出)不同,Deep Research 任务是一个智能体工作流。单个请求会触发计划、搜索、阅读和推理的自主循环。

预计费用 #

成本根据所需研究的深度而有所不同。 智能体自动确定回答您的提示所需的阅读和搜索量。

  • Deep Research (deep-research-preview-04-2026):对于需要适度分析的典型查询,智能体可能使用~80 搜索查询、~250k 输入 token(~50-70% 缓存)和~60k 输出 token。 * 预计总数: ~$1.00 - 每个任务 $3.00

  • Deep Research Max (deep-research-max-preview-04-2026):对于深入的竞争格局分析或广泛的尽职调查,智能体可能会使用最多~160 搜索查询、~900k 输入 token(~50-70% 缓存)和~80k 输出 token。 * 预计总数: ~$3.00 - 每个任务 $7.00

安全考虑 #

授予智能体访问网络和您的私人文件的权限需要仔细考虑安全风险。

  • 使用文件提示注入: 智能体读取您提供的文件的内容。确保上传的文档(PDF、文本文件)来自可信来源。恶意文件可能包含旨在操纵智能体输出的隐藏文本。

  • 网页内容风险: 智能体搜索公共网络。虽然我们实施了强大的安全过滤器,但智能体仍存在遇到并处理恶意网页的风险。我们建议审查 citations 在回复中提供以验证来源。

  • 渗漏: 询问时要小心智能体如果您还允许它浏览网页,则可以汇总敏感的内部数据。

最佳实践 #

  • 提示未知数: 指导智能体如何处理丢失的数据。例如,添加 “如果 2025 的具体数字不可用,请明确说明它们是预测或不可用,而不是估计” 根据您的提示。

  • 提供上下文: 通过直接在输入提示中提供背景信息或约束来奠定智能体的研究基础。

  • 使用协作计划: 对于复杂的查询,启用协作规划以在执行之前审查和完善研究计划。

  • 多模态输入: Deep Research 智能体支持多模态输入。请谨慎使用,因为这会增加成本并带来上下文窗口溢出的风险。

限制 #

  • 自定义工具: 您当前无法提供自定义函数调用工具,但可以将远程 MCP (Model Context Protocol) 服务器与 Deep Research 智能体结合使用。

  • 结构化输出: Deep Research 智能体目前不支持结构化输出。

  • 最长研究时间: Deep Research 智能体的最长研究时间为 60 分钟。大多数任务应在 20 分钟内完成。

  • 店铺要求: 智能体执行使用 background=True 需要 store=True.

  • 谷歌搜索: Google 搜索 默认情况下启用并且 具体限制 适用于提供事实依据结果。

后续步骤 #

搜索标题、API 名称或正文内容