Gemini Interactions API 已在 2026 年 6 月 GA。旧项目不必抢跑全量迁移，但涉及代理、工具调用和长任务的入口，应先做接口盘点、状态策略和灰度回滚。
- 01先读摘要，判断是否与你的场景相关。
- 02再看来源，保留继续查证的路径。
- 03最后看步骤、风险和可复用动作。
Google 在 2026 年 6 月把 Gemini Interactions API 标为 GA，并把它列为模型与代理的新推荐接口。已经用 generateContent 做工具调用、长任务或多轮对话的开发者，现在要先判断哪些项目值得迁移，哪些继续保持旧接口更稳。
更新日期与来源依据
更新日期：2026-06-30。Google 官方博客说明 Interactions API 已成为 Gemini 模型和代理的主要接口；开发文档写明旧 generateContent 仍受支持，但新项目推荐使用 Interactions；迁移指南给出了输入、输出、状态和后台任务的映射方式。
适用场景
- 你维护的应用已经出现多轮上下文、工具调用、长任务、Deep Research 或代理工作流。
- 你希望把模型调用和代理调用放到同一套接口里，减少旧代码里多种响应格式的分支。
- 你需要把中间执行步骤展示给用户，或把函数调用、检索结果、最终输出拆开记录。
- 你愿意为 paid tier 的 55 天保留、后台任务和服务端状态建立数据保留说明。
不适用场景
- 只有单轮文本生成，响应解析非常稳定，短期没有工具调用和代理计划。
- 项目所在组织不能接受默认 store=true 的交互对象留存，且又必须使用后台执行。
- 当前依赖 Batch API、视频 metadata、Python 自动函数调用或显式缓存，这些在文档中仍列为 Interactions API 尚未覆盖的能力。
准备材料
- 现有调用清单：模型 ID、输入内容、工具、系统指令、温度、响应解析、错误处理。
- 数据边界表：哪些请求可被存储，哪些必须 store=false，哪些需要删除 interaction id。
- 灰度样本：至少 20 条真实请求，覆盖普通问答、工具调用、超时、空结果、长上下文和失败重试。
- 回滚开关：环境变量或配置项可以在旧接口与新接口之间切换。
操作步骤
- 把所有 generateContent 调用按用途分组：单轮生成、多轮对话、工具调用、长任务、代理任务。只有后三类优先迁移。
- 给每组写出输入输出契约。旧接口常从 candidates/content/parts 取结果，新接口要按 execution steps 读取 user_input、function_call、function_result 和 model_output。
- 选择状态策略。需要服务端续聊时保存 previous_interaction_id；不希望存储时设置 store=false，但要接受不能用后台执行和后续续聊的限制。
- 把工具参数改成每次 interaction-scoped 都重新传入。文档说明 tools、system_instruction、generation_config 不会因为 previous_interaction_id 自动沿用。
- 为长任务单独开 background=true 路径，并记录轮询、超时、取消、用户提示和失败重试策略。
- 做双写灰度。相同输入同时跑旧接口和新接口，只比较结构、关键字段、失败类型和延迟，不要把两边结果混在一个用户会话里。
- 通过后只切一个低风险入口，例如内部摘要或测试用户入口；观察 48 小时后再迁移面向客户的主路径。
验收清单
- 每类请求都有旧接口样本、新接口样本和差异说明。
- 所有新接口错误都能定位到字段，不再只把异常展示成“模型失败”。
- 后台任务有超时提示，用户刷新页面后仍能根据任务 id 找回状态。
- store=true、store=false、previous_interaction_id 的使用条件写进 README 或内部运维文档。
- 迁移后仍保留旧接口回滚开关，至少观察两个发布周期。
实际例子
一个内容运营工具原来用 generateContent 做“输入标题，返回摘要与标签”。这个场景保持旧接口也可以。另一个入口会读取网页、调用函数取站内分类、再生成发布建议，并且耗时经常超过普通请求窗口。后者更适合迁到 Interactions API，因为它需要可观察步骤、工具结果和后台执行。
迁移记录
入口：/api/content-plan
旧接口用途：generateContent + function calling
新接口策略：interactions.create + tools + background=true
状态：保存 previous_interaction_id 7 天
保留：敏感输入 store=false，不走后台
灰度样本：20 条
回滚变量：GEMINI_API_MODE=legacy|interactions常见坑
- 把 previous_interaction_id 当成“所有设置都会继承”。实际上工具、系统指令和生成配置仍要在当前请求里传。
- 只改请求，不改响应解析。新接口的价值在 execution steps；如果仍只找单个文本字段，会丢掉调试信息。
- 忽略数据留存。免费层和付费层保留期限不同，敏感请求是否 store=false 要提前定。
- 为了追新把所有入口一次性迁完。更稳的做法是按风险分组、灰度、回滚。
排错路径
- 返回字段不符合预期：先打印 steps 类型，再确认是不是只读取了 model_output。
- 续聊失效：检查是否保存了正确 interaction id，以及当前请求是否仍传入必要工具和系统指令。
- 后台任务不能用：确认没有设置 store=false，并检查任务状态轮询。
- 能力缺口：如果依赖 Batch API 或视频 metadata，先留在旧接口，等官方支持后再迁。
可复制迁移模板
项目：
入口：
旧接口：
迁移原因：
是否需要服务端状态：
是否允许存储：
后台任务：是/否
工具清单：
响应解析变更：
灰度样本数量：
回滚负责人：
下次复查日期：维护建议：把 Interactions API 当成代理化工作流的标准入口，而不是所有旧请求的强制替换。每次 Google 更新限制、SDK 版本或保留政策时，复查一次状态策略和回滚开关。