Gemini Deep Research 升级并开放 API

以前 Deep Research 只活在 Gemini 网页里：丢一个题目，它自己搜、自己读，过几分钟交一份带引用的报告。2025 年 12 月起，同一套能力进了 Gemini API 的 Interactions 接口，可以塞进自己的脚本或产品。2026 年 4 月又加了更快的一档、更慢更全的 Max、先审计划再跑，以及 MCP。

这篇按现在能调到的接口写。它还在 preview，只能走 Interactions，不能走 generate_content。任务经常要跑好几分钟，请求必须开 background=True，然后轮询或流式收结果。

两个版本怎么选

现在公开的 agent 代号有两个：

deep-research-preview-04-2026：偏快，适合接到自己的界面上，边跑边往回推进度。
deep-research-max-preview-04-2026：偏全，适合夜里丢一个尽职调查、竞品扫描这类可以等的任务。

两边都是 1M 输入、65K 输出。输入可以带文本、图片、PDF、音频、视频；输出主要是带引用的报告，也可以出图。选哪个取决于你能不能等，以及报告漏一条关键来源的代价有多大。日常试用先用普通档。

第一次调用

先装官方 SDK，Key 从 Google AI Studio 拿：

bash

pip install google-genai
export GEMINI_API_KEY="你的密钥"

最小例子。注意读结果走的是 steps，不是旧文档里的 outputs（2026 年 5 月 Interactions 改过字段）：

python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="梳理 Google TPU 从第一代到现在的产品线，并标出和同期 GPU 的差异。",
    agent="deep-research-preview-04-2026",
    background=True,
)
print("started", interaction.id)

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

REST 也行，先 POST https://generativelanguage.googleapis.com/v1beta/interactions，body 里放 input、agent、background: true，再用返回的 id 去 GET /v1beta/interactions/{id}。

提示词里把结构写死一点会好用很多：要哪些章节、要不要表格、引用细到什么程度。它会按你的标题去搜，而不是自己发挥成一篇散文。

先看计划再跑

不想它一上来就花十几分钟乱搜，把 collaborative_planning 打开。第一轮它只交一份研究计划，你改完再批准。

python

plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="对比 Google TPU 和同期竞品加速卡，少写历史，多写功耗和软件栈。",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    background=True,
)

继续改计划时带上 previous_interaction_id，并保持 collaborative_planning=True。真正开跑时必须显式改成 False。只回一句「可以，开始」而不改这个开关，它还停在计划模式，不会出报告。

适合用这套的场景：题目大、方向容易跑偏、或者报告要交给别人看，你得先确认它会查哪些源。

工具、MCP、自己的材料

不传 tools 时，默认打开三个：google_search、url_context、code_execution。也就是上网搜、打开网页读、必要时跑点代码做计算。

只想让它搜公开网页，可以收窄：

python

client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="量子计算最近半年的工程进展，只要公开网页。",
    tools=[{"type": "google_search"}, {"type": "url_context"}],
    background=True,
)

要接自己的数据，有两条路。一条是远程 MCP：把服务器的 name、url、鉴权头传进去，可选 allowed_tools 限制它能调哪些工具。鉴权支持无认证、Bearer、OAuth。另一条是 file_search，对着已经上传的文档库搜。也可以在 input 里直接塞 PDF 或图片，比如一篇论文加一句「这篇之后行业怎么跟」。

把公开网页和私有源混在一起时，提示词里写清楚哪些结论必须落到你们自己的数据上。否则它很容易用网上的二手综述把内部数字盖掉。

边跑边看，以及图表

长任务可以 stream=True，配合 thinking_summaries: "auto" 看它中间在想什么。连接掉了用 last_event_id 接着拉，官方文档里有完整重连例子。

要图表时打开 visualization: "auto"，并在提示词里写要哪类图。能力开了不等于它自动画，你得点名。返回的图是 base64 图片，自己解码保存即可。

计费和几个容易踩的点

计费按底层模型和它实际用到的工具走，一次请求会自己循环规划、搜索、阅读、再规划，所以比普通聊天贵、也慢。官方按用量计价，具体数字看当时的 Gemini API 定价页，这里不抄容易过期的估算。

使用上记住这几条：

只能走 Interactions。generate_content 调不通。
必须 background=True。同步等它跑完通常会超时。
读结果用 steps。抄到旧字段会空。
还在 preview，字段和代号可能再改。Java 示例里偶尔还能看到更早的 deep-research-pro-preview-12-2025，新代码别用那个。
报告有引用，但仍要抽查。尤其是数字、监管条款、竞品参数。

适合丢给它的是「需要跨很多网页、还要合成」的题目：尽调初稿、赛道扫描、一篇论文之后的跟进。不适合要秒回的客服，也不适合已经有一份权威内部文档、只差摘要的场景。那种用普通长上下文更便宜。

字节笔记本

Gemini Deep Research 升级并开放 API

两个版本怎么选

第一次调用

先看计划再跑

工具、MCP、自己的材料

边跑边看，以及图表

计费和几个容易踩的点

相关链接