Gemini Interactions API：统一模型与 Agent 的有状态接口
Google Gemini API 的统一交互接口，用同一资源模型调用基础模型与专用 Agent，并支持状态、后台任务和执行步骤。
Gemini Interactions API developer-api agent-protocol agent-orchestration model-api Google Gemini API 的统一交互接口，用同一资源模型调用基础模型与专用 Agent，并支持状态、后台任务和执行步骤。
1. 项目定位
Gemini Interactions API 是 Google 为 Gemini 模型和专用 Agent 提供的统一接口。官方文档称其自 2026 年 6 月起进入 GA，并推荐新项目使用；原有 generateContent 仍继续受支持。[S1][S2] 它把一次模型或 Agent 任务表示为 Interaction，便于统一处理多模态输入、工具步骤和最终输出。
2. 要解决的问题
当应用同时调用普通模型、深度研究 Agent、工具和长任务时，多套接口会增加状态、错误与观测逻辑。Interactions API 用一致的创建、查询和步骤结构承载这些路径。[S1] 它能减少接口分裂，但不会替开发方决定权限、数据保留、重试和人工审批；这些治理规则仍要由业务系统明确实现。
3. 资源与步骤
每个 Interaction 代表一轮对话或任务，记录按时间排列的执行步骤，包括输入、模型输出以及工具调用和结果等。[S1] 开发者可通过创建接口启动任务，再读取返回或查询资源。日志层应保存 interaction ID、模型、工具版本和业务请求 ID，但避免把完整敏感提示词无期限复制到多个系统。
4. 状态管理
开发者可以把已完成交互的 ID 作为 previous_interaction_id 继续对话，由服务端取回历史；也可以选择无状态模式并自行发送上下文。[S1] 工具、系统指令和生成配置是单次 Interaction 的参数，需要按调用重新声明。迁移时若误以为所有配置都会自动继承，可能造成权限或行为偏差。
5. 后台任务
接口支持以 background=true 运行长任务，并让应用查询进度或结果；执行步骤也可用于调试和界面展示。[S1] 后台模式适合研究或长工具链，但需要幂等键、超时、取消、状态机和重复回调处理。前端不能把“任务已创建”显示成“任务已完成”，计费与失败也要按最终状态核算。
6. 存储与保留
官方文档说明，默认 store=true 会保存 Interaction，以支持服务端状态、后台执行和观测；可设置 store=false，但这会与部分能力不兼容。[S1] 文档还区分免费与付费层的保留方式。接入前应由隐私和法务确认数据类型、区域、删除路径与保留期，敏感场景优先评估无状态设计。
7. 版本与迁移
Interactions API 已列入 Gemini API 的稳定 v1，而 v1beta 用于仍在演进的功能。[S2] 稳定版本不等于调用代码永远不变，SDK、模型和工具能力仍会更新。迁移应先建立契约测试，逐项对比请求字段、步骤解析、错误码、流式输出和旧接口结果，再分流量切换。
8. 适用场景
适合需要统一调用模型与 Agent、多轮状态、长任务或工具观测的 Gemini 应用。单轮、无状态且已经稳定运行的简单调用未必需要立即迁移。团队应根据新能力收益、数据保留要求和改造成本决策，避免只因为官方推荐就一次性替换全部生产请求。
9. 验收建议
建立覆盖单轮、多轮、工具成功与失败、后台取消、超时、重复提交和删除的测试矩阵。核对每次交互的状态转换、费用、日志与用户界面是否一致，并验证 store=false 场景没有意外依赖服务端历史。灰度期间保留旧接口回退通道，直到关键任务的正确率和稳定性达到基线。
10. 来源与更新时间
本简调截至 2026-08-12，依据 Google Gemini API 官方概览与版本说明。数据保留、模型兼容和功能状态可能变化，生产迁移前应重新核对当前文档。