如何使用 Gemini API 运行 Deep Research：从基础入门到高级流式传输

想象一下，你接到了一个耗时数周的调研任务：梳理全球半导体市场的趋势，不仅要查阅大量文献，还要对比不同厂商的市场份额变化，最终生成一份附带图表的详细报告。在过去，这意味着无数次的搜索、阅读、记录和排版。而现在，通过大语言模型的力量，你可以将这种长周期的复杂研究工作交给一个能够自主规划、搜索并综合信息的智能体。
Google AI Studio 近期公开了 Gemini Deep Research Agent 的使用方法。它不是一个简单的问答机器人，而是一个能够自主执行长期研究任务的系统。它会自己在后台运行，把繁杂的信息搜集和整理工作做完，最后交给你一份带有引用的详细报告。
接下来，我们将从零开始，一步步拆解如何通过代码调用这个强大的研究工具，并深入探讨如何利用它的高级功能来满足真实的业务需求。

Deep Research 是什么？它和普通对话有什么区别

在使用任何工具之前，理解它的边界和特性是最重要的。普通的对话模型就像一个坐在你对面、随问随答的顾问，你问一句，它答一句，连接断开，对话基本就结束了。而 Deep Research 更像是你雇佣的一个独立调研团队，你只需要下达一个宏观的指令，它就会自己去查资料、做分析，几个小时后把一份完整的报告放在你的桌子上。
为了实现这种“独立工作”的能力，它在技术架构上有几个非常关键的设计：
首先，它专门用来处理长时间运行的任务，因此被设计为在后台执行。你发起请求后，不需要一直盯着屏幕等它一个字一个字地吐出来，而是可以去做别的事情，等它做完了再来拿结果。
其次，也是最容易被开发者忽略的一点：它只能通过 Interactions API 来调用，而绝对不能使用传统的 generate_content 接口。这两个接口在底层逻辑上是完全不同的，generate_content 适合短暂的即时生成，而 Interactions API 则是为了管理具有状态、跨多轮甚至长时间运行的任务而设计的。
目前，这个智能体提供了两个不同的版本，你可以根据实际的使用场景来选择：

版本名称	核心特点	适用场景
`deep-research-preview-04-2026`	侧重于速度与效率	适合将结果实时流式传输到客户端用户界面，需要较快反馈的场景
`deep-research-max-preview-04-2026`	追求最大的全面性	适合用于自动化的上下文收集与深度综合，对时间不敏感但对质量要求极高的场景

准备工作：搭建你的本地开发环境

要把这个智能体拉到你的电脑上跑起来，前期准备工作非常简单，只需要两步。
第一步是安装官方提供的 Python 软件开发工具包（SDK）。打开你的终端或者命令行界面，输入以下命令：

pip install google-genai

这个命令会自动从官方仓库下载并安装你所需的所有基础依赖库。
第二步是配置你的身份凭证。大模型接口需要知道是谁在调用它，以便进行权限控制和资源分配。你需要获取一个专属的 API 密钥，并将其设置为操作系统的环境变量。在终端中运行以下代码（记得把里面的占位符替换成你真实的密钥）：

export GEMINI_API_KEY="your-api-key"

这样做的好处是，你的密钥不会直接暴露在代码文件里。如果你使用的是 Windows 系统，配置环境变量的方式会有所不同，通常是在系统属性的高级设置中进行，但无论哪种操作系统，最终目的都是让 Python 程序在运行时能够读取到这个名为 GEMINI_API_KEY 的变量。

基础实战：启动你的第一个后台研究任务

环境配置好之后，我们就可以用几行代码启动第一次调研了。假设我们想让它去研究一下“谷歌 TPU 的发展历史”。

import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-preview-04-2026",
    background=True,
)
while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.outputs[-1].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)

我们来逐行拆解这段代码背后的逻辑：

client = genai.Client()：这行代码实例化了一个客户端对象，它是你与 Gemini 服务进行所有通信的基础。
client.interactions.create(...)：这是发起任务的入口。注意这里的三个参数：
- input：你的研究指令。
- agent：明确指定我们要调用的智能体版本。
- background=True：这是核心开关，告诉系统“这是一个后台任务，不用等我”。
while True: 循环：因为任务在后台运行，可能需要几分钟甚至更长时间，所以我们需要一个机制来不断询问“做完了吗？”。这就是轮询（Polling）。
time.sleep(10)：每隔 10 秒去查询一次状态。为什么是 10 秒？因为如果每隔一毫秒就去问一次，会对服务器造成极大的压力，甚至可能导致你的请求被限流。10 秒是一个兼顾体验和服务器负载的合理间隔。
状态判断：当状态变为 completed 时，打印出最终报告（通过 outputs[-1].text 获取最后生成的文本）；如果状态是 failed，则打印出错误信息并终止循环，避免程序陷入死循环。

进阶技巧一：协作规划——先看大纲，再动笔

有时候，你交代的任务非常宏大，如果智能体理解偏了，等它跑了半个小时出结果后你才发现方向不对，那时间成本就太高了。为了解决这个问题，系统引入了“协作规划”功能。
这就好比你找大学生写毕业论文，你不希望他直接开写，而是希望他先写个开题报告给你看看，你确认大纲没问题了，他再去填充正文。
协作规划分为三个明确的步骤：

步骤 1：请求生成研究计划

在创建交互时，通过 agent_config 参数开启协作规划模式。

import time
from google import genai
client = genai.Client()
plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research Google TPUs vs competitor hardware.",
    agent_config={"type": "deep-research", "collaborative_planning": True},
    background=True,
)
while (result := client.interactions.get(id=plan.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

这段代码执行后，智能体不会去写最终报告，而是会输出一份结构化的研究计划，比如它打算从哪些维度去对比、打算搜索哪些关键词等。

步骤 2：细化和修改计划

看到计划后，你觉得漏掉了一个重要维度——能效比的对比。你可以继续发送指令，但关键在于必须带上 previous_interaction_id 参数，让它知道这是上一次对话的延续，同时继续保持 collaborative_planning 为 True。

refined = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Add a section comparing power efficiency.",
    agent_config={"type": "deep-research", "collaborative_planning": True},
    previous_interaction_id=plan.id,
    background=True,
)
while (result := client.interactions.get(id=refined.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

这个过程可以重复多次，直到你对大纲完全满意。

步骤 3：批准并执行最终研究

这是最容易踩坑的地方。当你觉得计划完美，想让它开始干活时，你不能简单地发一句“开始吧”或者“没问题”。如果你在代码里仍然保持 collaborative_planning=True，它会继续给你修改大纲，而不是去写报告。
你必须显式地将 collaborative_planning 设置为 False，以此来明确告诉系统：“规划阶段结束，现在开始执行”。

report = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Plan looks good!",
    agent_config={"type": "deep-research", "collaborative_planning": False},
    previous_interaction_id=refined.id,
    background=True,
)
while (result := client.interactions.get(id=report.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

进阶技巧二：让数据说话——原生图表与信息图生成

一份优秀的调研报告离不开数据可视化。过去，我们需要让模型生成数据，然后再用 Python 的 Matplotlib 或者其他工具画图。现在，Deep Research 可以直接在研究过程中生成原生的图表和信息图。
要实现这个功能，需要在 agent_config 中设置 visualization="auto"，并且在你的提示词中明确要求它生成视觉内容。

import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Analyze global semiconductor market trends. Include charts showing market share changes.",
    agent_config={"type": "deep-research", "visualization": "auto"},
    background=True,
)
while (result := client.interactions.get(id=interaction.id)).status != "completed":
    time.sleep(5)
for output in result.outputs:
    if output.type == "text":
        print(output.text)
    elif output.type == "image" and output.data:
        image_bytes = base64.b64decode(output.data)
        # display(Image(data=image_bytes)) # 如果在 Jupyter 环境中，可以取消注释来显示图片

这里有几个细节需要注意：
开启 auto 只是赋予了它画图的能力，但模型依然是被动的。如果你在 input 里不提“图表”、“趋势图”等字眼，它可能依然只会输出纯文本。
返回的图像数据并不是一个可以直接打开的链接，而是经过 Base64 编码的字符串。你需要用 base64.b64decode 将其还原为二进制图像字节流，然后保存成文件或者在支持的前端界面中渲染出来。

进阶技巧三：精准控制它的工具箱

Deep Research 之所以强大，是因为它不只是靠脑袋里的训练数据瞎编，而是可以调用真实的工具去获取最新信息。默认情况下，它会使用三种工具：Google Search（网页搜索）、URL Context（读取网页内容）和 Code Execution（执行代码进行计算分析）。
但在某些特定场景下，你可能需要限制它的行为。比如，你只想让它搜公开网页，不想让它跑代码；或者你接入了私有的数据库，只想让它查你的数据库。
系统提供了五种可配置的工具类型，你可以自由组合：

工具类型标识	对应功能	默认状态
`google_search`	搜索公共互联网	开启
`url_context`	读取并总结指定网页内容	开启
`code_execution`	运行代码进行数据处理	开启
`mcp_server`	连接外部工具服务器	关闭
`file_search`	搜索已上传的私有文档库	关闭
如果你希望它只进行网页搜索，不运行任何代码，可以这样写：

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

注意一个隐藏规则：如果你在代码中完全不写 tools 这个参数，系统会默认开启前三个基础工具。但如果你手动传了一个空列表进去，行为可能会有所不同。通常的建议是，需要默认行为就不传，需要定制就明确列出你要开启的工具。

进阶技巧四：带着资料去提问——多模态研究基础

有时候你的研究不是从零开始的，你手里可能已经有一篇几十页的 PDF 论文，或者一张数据截图。你希望智能体基于这些已有材料进行延伸研究。
Deep Research 支持将图像、PDF 和音频等文件作为研究的上下文一起传递过去。这被称为多模态研究基础。

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

在这个例子中，input 参数不再是一个简单的字符串，而是一个列表。列表中包含了文本指令和文档对象的统一格式。通过指定 mime_type 为 application/pdf，模型就能准确识别这是一份 PDF 文档，并以此为起点去搜索相关的后续影响和引用情况。

进阶技巧五：打通任督二脉——连接远程 MCP 服务器

这是整个功能中最具扩展性的一部分。MCP 的全称是 Model Context Protocol（模型上下文协议）。简单来说，它是一个标准接口，允许大模型连接到外部的专业工具或数据库。
比如，你是一家金融机构的开发者，你有一个内部系统能够获取最实时的美元利率数据。你可以把这个内部系统包装成一个 MCP 服务器，然后让 Deep Research 在做地缘政治对利率影响的研究时，直接调用你的内部系统拿真实数据。

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research how recent geopolitical events influenced USD interest rates",
    tools=[
        {
            "type": "mcp_server",
            "name": "Finance Data Provider",
            "url": "https://finance.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"},
        }
    ],
    background=True,
)

在配置远程服务器时，安全性是首要考虑的。系统支持三种认证方式：

无认证：适用于完全公开的测试接口。
Bearer Token：最常见的方式，在请求头中带上一串预先分配好的令牌，如上面的代码所示。
OAuth：更复杂但更安全的标准授权协议。你需要借助像 google-auth 这样的外部库先去获取一个临时的访问令牌，然后再把这个令牌塞到 headers 里传过去。
此外，为了防止模型过度调用外部接口，你还可以使用 allowed_tools 参数来限制模型只能调用这个 MCP 服务器上的哪几个具体功能。

高阶前端体验：实时流式传输与断线重连机制

前面讲的所有例子都是“后台运行+轮询”的模式。这对于写脚本自动化处理很方便，但如果我们要做一个面向普通用户的网页应用，这种体验就很差了。用户点击“开始研究”后，盯着一个转圈圈的动画看五分钟，肯定会以为程序死机了。
为了解决这个问题，Interactions API 提供了实时流式传输的能力。你可以实时看到它在想什么、搜到了什么、甚至它刚画完一半的图表。
开启流式传输需要设置 stream=True，并且强烈建议同时开启 thinking_summaries="auto"。这会让模型把它的中间推理过程（比如“我正在搜索XXX”、“我发现前一个结果不够全面，我换了个关键词”）也作为一个特殊的数据流推给你。
下面是一段完整的流式传输处理代码，它甚至包含了网络断线后的重连逻辑：

import base64
from google import genai
from IPython.display import Image, display
client = genai.Client()
interaction_id = None
last_event_id = None
is_complete = False
def process_stream(stream):
    global interaction_id, last_event_id, is_complete
    for chunk in stream:
        # 记录交互ID，用于后续重连
        if chunk.event_type == "interaction.start":
            interaction_id = chunk.interaction.id
        if chunk.event_id:
            last_event_id = chunk.event_id
            
        # 处理具体的内容增量
        if chunk.event_type == "content.delta":
            # 普通文本
            if chunk.delta.type == "text":
                print(chunk.delta.text, end="", flush=True)
            # 思考摘要
            elif chunk.delta.type == "thought_summary":
                print(f"\n💭 {chunk.delta.content.text}", flush=True)
            # 图片数据
            elif chunk.delta.type == "image" and chunk.delta.data:
                image_bytes = base64.b64decode(chunk.delta.data)
                display(Image(data=image_bytes))
                
        # 判断是否彻底结束
        elif chunk.event_type in ("interaction.complete", "error"):
            is_complete = True
            if chunk.event_type == "interaction.complete":
                print("\n✅ Research Complete")
# 发起流式请求
stream = client.interactions.create(
    input="Research AI chip market trends. Include charts comparing vendors.",
    agent="deep-research-preview-04-2026",
    background=True,
    stream=True,
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "visualization": "auto",
    },
)
process_stream(stream)
# 断线重连机制
while not is_complete and interaction_id:
    status = client.interactions.get(interaction_id)
    if status.status != "in_progress":
        break
    # 使用上一次记录的 event_id 从断点处继续拉取流
    stream = client.interactions.get(
        id=interaction_id,
        stream=True,
        last_event_id=last_event_id,
    )
    process_stream(stream)

这段代码的精妙之处在于它处理了真实网络环境中的不稳定因素。last_event_id 就像是看书时夹的一枚书签，如果网络断了，重连后系统会根据这个书签，把断掉的那一段内容重新发给你，确保最终展示在用户面前的信息是完整无缺的。

常见问题解答

在使用这套系统的过程中，开发者通常会遇到一些逻辑上的疑惑。以下是基于技术规则整理的解答：
为什么我调用 Deep Research 时系统报错，提示接口不存在？
这通常是因为你用错了调用的端点。Deep Research 智能体被严格限制只能通过 client.interactions.create 这个方法来创建。如果你习惯性地使用了 client.models.generate_content，系统是无法识别这个智能体的。
在协作规划阶段，我觉得大纲没问题了，直接发了一句“开始执行”，为什么它还在继续修改大纲？
这是因为你没有在代码中改变控制标志。智能体判断你是否要结束规划，唯一的标准就是 agent_config 里的 collaborative_planning 参数是否被显式设置为 False。仅仅在文本输入里写“开始吧”是不起作用的，你必须在前一次交互的基础上，携带 previous_interaction_id，并且将 collaborative_planning=False 传进去，它才会真正启动报告生成流程。
我希望它只在我的私有文档库里做研究，不去公网上搜，应该怎么配置工具？
你可以通过 tools 参数精确控制它的能力边界。如果你只想搜私有文档，你应该只传入 [{"type": "file_search"}]。需要注意的是，如果你传入了空列表或者格式不正确的列表，可能会触发系统的默认行为（即开启搜索和代码执行），所以一定要明确指定你需要的工具类型。
为什么我开启了图表生成功能，但最终结果里只有文字没有图？
仅仅在 agent_config 中设置 visualization="auto" 只是赋予了它画图的能力和权限。大模型的生成逻辑高度依赖于你的文本指令。如果你的 input 里没有明确提出诸如“包含图表”、“用折线图展示”、“生成信息图”等具体的视觉要求，它为了节省计算资源，大概率会选择只输出纯文本分析。
流式传输的时候，如果用户的手机切到后台导致网络断开，任务会失败吗？
不会。因为你在发起请求时设置了 background=True。这意味着无论前端连接是否存在，服务器端的后台研究任务都会一直执行下去直到完成。你唯一丢失的只是断网期间服务器推送给你的实时进度片段。当你通过 last_event_id 重新建立连接后，你可以接着断点继续接收后续的进度，最终依然能拿到完整的研究报告。

总结

Gemini Deep Research Agent 代表了大模型应用从“对话式”向“任务式”演进的一个重要方向。它剥离了开发者处理复杂状态管理、多步搜索逻辑和结果整合的负担，将这一切封装在一个黑盒式的异步智能体中。
无论是通过协作规划来把控研究方向，通过多模态输入来提供研究素材，还是通过 MCP 协议接入企业内部的私有数据源，这套工具都提供了足够灵活的接口。理解并熟练运用 Interactions API 的异步特性和流式传输机制，是将其真正落地到生产环境、构建高质量自动化研究平台的关键所在。

揭秘Gemini Deep Research：从4行代码启动后台调研到流式报告生成（保姆级教程）