Gemini Deep Research 接入：只能用 Interactions API，再加 60 分钟上限、store=true 和 MCP 私有数据
凌晨两点跑尽调报告，第二天早上把结果贴进评审文档——这个用法决定了你选哪个 agent 代码、怎么调、以及哪些东西现在接不了。下面是把 Deep Research 接进内部流程时踩到和绕开的点。
参考材料：
- Gemini API Deep Research 文档
- 发布说明
- Google Cloud 企业版文档
- GitHub notebook：Introduction to Gemini Deep Research Agent
版本与 agent 代码
2026-04-21 Google 发布 Deep Research 和 Deep Research Max，均基于 Gemini 3.1 Pro，2025-12 的 preview 版本被替换。可用的 agent 代码有两个，选型基本是二选一：
deep-research-preview-04-2026：速度与效率优先，适合流式回客户端 UI。用户能看着研究过程往前走，等待感可控。deep-research-max-preview-04-2026：最大全面性，用扩展 test-time compute 反复推理/搜索/精炼，适合异步后台工作流，比如夜间 cron 跑尽调报告。
Max 与旧版相比会咨询更多来源、权衡冲突证据，引用 SEC filings、开放获取同行评审期刊等权威来源。代价是时间，所以别把它塞进交互式请求路径里。
只能走 Interactions API
调用入口只有 Interactions API，不能走 generate_content。这一条的影响比看上去大：已有的 generate_content 封装——重试策略、超时、埋点、流式解析——都得另起一套，不能复用。Interactions API 目前是 public beta，schema 可能变。REST 请求里的 Api-Revision: 2026-05-20 头就是拿来钉住版本的，生产接入建议显式带上，别吃默认值。
上下文：输入窗口 1,048,576 tokens，输出上限 65,536 tokens。输入支持文本、图片、PDF、音频、视频——可以把参考资料直接塞进去，不用先转文本。
REST 与 SDK
POST https://generativelanguage.googleapis.com/v1beta/interactions
Content-Type: application/json
x-goog-api-key: $GEMINI_API_KEY
Api-Revision: 2026-05-20
{
"agent": "deep-research-preview-04-2026",
"input": "...",
"background": true
}
Python SDK：
from google import genai
client.interactions.create(
agent="deep-research-preview-04-2026",
input="...",
background=True
)
JS：
client.interactions.create({agent, input, background:true})
企业版：background 和 stream 都得开
企业版走 global endpoint v1beta1：
POST https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions
Authorization: Bearer $(gcloud auth print-access-token)
企业版必须 background=true 且 stream=true。注意这里的 stream 不是把最终报告一段段推给你，而是 API 立即返回部分 Interaction 对象，后续用返回的 id 轮询，状态从 in_progress 转到 completed 或 failed。所以前端拿到 "stream 已开" 不等于拿到结果，轮询逻辑还是得写。curl 建议 --max-time 3600 --keepalive-time 10。
两种用法的取舍基本清楚：
- 面向用户界面的，用
deep-research-preview-04-2026，流式往前推，让用户看到进展。 - 后台任务/报告生成的，用 Max，起一个 job，隔一段时间按
id查状态，完成后再取结果。
工具与 MCP
不传 tools 时默认启用 google_search、url_context、code_execution。可显式指定 tools 来限制或扩展。
| 工具 | 取值 | 默认 |
|---|---|---|
| Google Search | google_search | 启用 |
| URL Context | url_context | 启用 |
| Code Execution | code_execution | 启用 |
| MCP Server | mcp_server | |
| File Search | file_search | 搜上传的文档语料 |
| 企业版 | enterprise_web_search、vertex_ai_search |
MCP server 配置字段：
type：必填，必须是"mcp_server"。name：显示名。url：MCP 端点完整 URL。headers：每个请求带上的 HTTP header，如 Authorization token。allowed_tools：限制 agent 可调用哪些工具。
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
)
挂私有数据的工程意义有两层。headers 是把鉴权交给 MCP 端点自己判，token 按请求传，不用把内部数据同步到 Google 侧。allowed_tools 是唯一能收窄 agent 权限的旋钮——MCP server 通常暴露一整套工具，agent 自己决定调哪个，不写 allowed_tools 等于全开。接内部系统时，把权限大的 MCP server 配成只允许只读的那几个工具。
agent_config
agent_config 控制行为：
type：字符串，必填"deep-research"。thinking_summaries：默认"none"，设"auto"暴露推理步骤。visualization：默认"auto"，设"off"关闭图表/图片。collaborative_planning：开启计划审查，让用户先审研究计划。
thinking_summaries 开成 "auto" 对 UI 有用，但也会拉长输出；visualization 对纯文本下游可以直接关掉。
现实边界
- 不支持自定义 Function Calling 工具，只能用远程 MCP server。想调内部函数，就得先把它们包成 MCP server 暴露出来。
- 不支持结构化输出。下游拿到的是一段自然语言报告，要落库或进流程得自己解析——常见做法是再过一遍普通 LLM 把报告转成 JSON，或者在 prompt 里约定输出章节标题，用规则切。
- 研究时间上限 60 分钟，多数任务 20 分钟内完成。夜间 cron 排期时按 60 分钟留窗口，别让下一个 job 和它叠上；配合
--max-time 3600也正好卡在这个上限。 background=True时必须store=True。background 的结果要按id取回，服务端不留 Interaction 对象就没法查，所以 store 关不掉。这意味着研究任务和结果会留在服务端，接敏感数据前先过一遍合规。