Interactions API

Interactions API 是使用 Gemini 构建应用的新标准原语，建议所有新项目都使用该 API。它针对智能体工作流、服务器端状态管理以及复杂的多模态多轮对话进行了优化。原始 generateContent API 仍然完全受支持。

为什么要使用 Interactions API？

  • 服务器端历史记录管理：通过 previous_interaction_id 简化多轮对话流程。服务器默认启用状态 (store=true)，但您可以通过设置 store=false 选择无状态行为。
  • 可观测的执行步骤：通过类型化步骤，可以轻松调试复杂流程并为中间事件（例如想法或搜索 widget）渲染界面。
  • 专为智能体工作流而打造：通过类型化执行步骤，原生支持多步骤工具使用、编排和复杂的推理流程。
  • 长时间运行的任务和后台任务：支持使用 background=true 将耗时的操作（例如Deep Think和Deep Research）分流到后台进程。
  • 使用新模型和功能：未来，除了核心主线系列之外的新模型，以及新的智能体功能和工具，都将仅在 Interactions API 上推出。

如果您要启动新项目、构建智能体应用或需要服务器端对话管理，请使用 Interactions API。如果您有满足需求的现有集成，或者需要 Interactions API 中尚未提供的功能（例如 Batch API 或显式缓存），请使用 generateContent。

开始使用

  • 设置编码智能体：连接到 Gemini 文档 MCP 并安装 gemini-interactions-api 技能，以便让助理直接访问最新的开发者文档和最佳实践。 设置编码代理 →
  • 从 generateContent 迁移：如果您有现有的集成，请按照迁移指南过渡到 Interactions API。
  • 试用快速入门：通过互动 API 快速入门中的极简工作示例开始使用。

功能指南

通过以下指南探索 Interactions API 的具体功能。您可以使用这些页面上的切换开关在 generateContent 和 Interactions API 之间切换：

Interactions API 的运作方式

Interactions API 围绕一个核心资源展开：Interaction。Interaction 表示对话或任务中的完整一轮。它充当会话记录，包含互动的完整历史记录，以执行步骤的时间顺序序列表示。这些步骤包括模型想法、服务器端或客户端工具调用和结果（例如 function_call 和 function_result），以及最终的 model_output。存储的资源（通过 interactions.get 检索）还包括完整上下文的 user_input 步骤，但 interactions.create 响应仅返回模型生成的步骤。

当您调用 interactions.create 时，您会创建一个新的 Interaction 资源。

服务器端状态管理

您可以在后续调用中使用已完成互动的 id，并通过 previous_interaction_id 参数继续对话。服务器会使用此 ID 来检索对话历史记录，从而避免您必须重新发送整个聊天记录。

previous_interaction_id 参数仅使用 previous_interaction_id 保留对话历史记录（输入和输出）。其他参数属于互动范围，仅适用于您当前生成的特定互动：

  • tools
  • system_instruction
  • generation_config（包括 thinking_level、temperature 等）

这意味着，如果您希望应用这些参数，则必须在每次新互动中重新指定这些参数。这种服务器端状态管理是可选的；您也可以通过在每次请求中发送完整的对话历史记录来以无状态模式运行。

数据存储和保留

默认情况下，该 API 会存储所有 Interaction 对象 (store=true)，以便简化服务器端状态管理功能（使用 previous_interaction_id）、后台执行（使用 background=true）和可观测性功能的使用。

  • 付费层级：系统会将互动数据保留 55 天。
  • 免费层级：系统会保留互动数据 1 天。

如果您不希望这样，可以在请求中设置 store=false。此控制措施与状态管理分开；您可以选择不存储任何互动数据。不过请注意，store=false 与 background=true 不兼容，并且会阻止在后续回合中使用 previous_interaction_id。

您可以随时使用 API 参考中的删除方法删除存储的互动记录。只有在知道互动 ID 的情况下，您才能删除互动。

保留期限结束后，系统会自动删除您的数据。

系统会根据条款处理 Interaction 对象。

最佳做法

  • 缓存命中率：使用 previous_interaction_id 继续对话可让系统更轻松地利用对话记录的隐式缓存，从而提高性能并降低费用。
  • 混合互动：您可以灵活地在对话中混合使用代理和模型互动。例如，您可以使用 Deep Research 智能体等专业智能体进行初始数据收集，然后使用标准 Gemini 模型执行后续任务，例如总结或重新格式化，并通过 previous_interaction_id 将这些步骤关联起来。

支持的模型和代理

模型名称 类型 模型 ID
Gemini 3.1 Flash-Lite 模型 gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite 预览版 模型 gemini-3.1-flash-lite-preview
Gemini 3 Pro 预览版 模型 gemini-3.1-pro-preview
Gemini 3 Flash 预览版 模型 gemini-3-flash-preview
Gemini 2.5 Pro 模型 gemini-2.5-pro
Gemini 2.5 Flash 模型 gemini-2.5-flash
Gemini 2.5 Flash-lite 模型 gemini-2.5-flash-lite
Lyria 3 剪辑预览 模型 lyria-3-clip-preview
Lyria 3 Pro 预览版 模型 lyria-3-pro-preview
Deep Research 预览版 代理 deep-research-pro-preview-12-2025
Deep Research 预览版 代理 deep-research-preview-04-2026
Deep Research 预览版 代理 deep-research-max-preview-04-2026

SDK

您可以使用最新版本的 Google GenAI SDK 来访问 Interactions API。

  • 在 Python 中，这是自 1.55.0 版本起提供的 google-genai 软件包。
  • 在 JavaScript 中，这是 1.33.0 版本及更高版本中的 @google/genai 软件包。

如需详细了解如何在库页面上安装 SDK，请参阅相关文档。

限制

  • Beta 版状态：Interactions API 目前为 Beta 版/预览版。功能和架构可能会发生变化。
  • 远程 MCP：Gemini 3 不支持远程 MCP，但很快就会支持。

generateContent API 支持以下功能，但 Interactions API 尚不支持这些功能：

破坏性更改

Interactions API 目前处于早期 Beta 版阶段。我们会根据实际使用情况和开发者反馈，积极开发和完善 API 功能、资源架构和 SDK 接口。

因此，可能会出现重大变更。 更新可能包括以下方面的更改：

  • 输入和输出的架构。
  • SDK 方法签名和对象结构。
  • 具体功能行为。

对于生产工作负载，您应继续使用标准 generateContent API。它仍然是稳定部署的推荐途径，我们将继续积极开发和维护它。

反馈

您的反馈对于开发 Interactions API 至关重要。 欢迎在我们的 Google AI 开发者社区论坛上分享您的想法、报告 bug 或提出功能请求。

后续步骤