Google把Interactions API定位为面向Gemini模型与Agent的新一代统一接口，并用于Deep Research和Managed Agents等能力。迁移价值在于统一多轮状态、工具和后台任务，但接口变化会影响会话存储、流式输出、计费、错误处理与权限。生产系统不能只替换URL和模型名，必须重新核对上下游契约。
先画出现有调用链
列出客户端、网关、模型接口、工具服务、数据库和日志系统，标记会话ID、用户ID、模型参数和工具结果在哪里保存。确认哪些业务依赖旧接口字段和事件顺序，尤其是流式输出、结束原因与用量统计。
建立契约测试，用固定请求验证文本、结构化输出、工具调用、文件、异常和取消。新旧接口同时运行时使用不同命名空间，防止状态串线。
重新设计状态与幂等
长任务可能在后台继续，客户端断线不等于任务失败。服务端保存交互ID、状态和最后事件位置，重连后从断点读取。创建任务携带幂等键，网络重试不会重复启动研究或写入业务数据。
会话保留期限与隐私政策一致。用户删除对话时同步清理本地映射和供应商侧状态。不要把敏感信息放在可长期复用的元数据里，日志中仅保存必要摘要。
工具调用与错误处理
工具参数用JSON Schema验证，执行器再次检查身份、权限和资源范围。读写工具分开，付款、发布和删除等操作经过确认。远程MCP或第三方工具返回的文本按不可信内容处理。
区分限流、超时、参数错误、权限错误和模型拒绝。只有可恢复错误才重试，并使用指数退避。后台任务超过预算或时间时安全停止，输出已完成步骤与恢复方式。
灰度迁移与可观测性
先以影子流量比较结果，再迁移内部用户和低风险任务。指标包括成功率、首字延迟、总耗时、工具失败、状态丢失、令牌和单任务费用。出现异常可通过配置切回旧接口。
迁移完成后删除平行实现，避免两套状态逻辑长期漂移。更新接口文档、监控面板、告警和应急手册。每次SDK升级先在契约测试环境验证，不让隐式字段变化直接进入生产。
落地检查清单
- 完整梳理会话、事件和统计字段。
- 后台任务使用交互ID与幂等键。
- 工具执行器独立校验权限和参数。
- 影子流量、灰度、监控与回滚同时准备。
