Interactions API

如果您目前正在使用传统 generateContent API 进行构建，那么新的 Interactions API 为您的应用提供了一条强大的升级路径。我们建议所有新项目都使用此 API，并且此 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。
  • 试用快速入门：在 Interactions 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 资源。

使用 SDK 便利属性访问输出

虽然 Interactions API 返回执行步骤（例如想法、搜索查询和函数调用）的结构化时间线，但您无需手动遍历这些步骤即可获取最终的模型响应。

Google GenAI SDK 直接在返回的 Interaction 对象上提供便利属性，以访问不同模态的输出：

SDK 便利属性 返回值类型 说明
interaction.output_text 字符串 返回模型响应中的最后一个文本块。如果响应拆分到多个连续的 TextContent 块中，它会自动将这些块连接起来。它不包括被非文本内容（例如想法、图片、音频或工具调用）分隔的较早文本块。对于复杂或交错的多模态响应，您必须改为手动迭代 steps。
interaction.output_image ImageContent 或 None 返回模型在当前请求中生成的最后一个图片块。
interaction.output_audio AudioContent 或 None 返回模型在当前请求中生成的最后一个音频块。

对于高级用例（例如呈现中间思考过程、检查逐步工具调用或调试），您仍然可以手动检查和遍历原始 interaction.steps 时间线。

服务器端状态管理

您可以在后续调用中使用已完成交互的 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.5 Flash 模型 gemini-3.5-flash
Gemini 3.1 Flash-Lite 模型 gemini-3.1-flash-lite
Gemini 3.1 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 Clip 预览版 模型 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 接口。因此，可能会发生破坏性更改 。

现有的破坏性更改：

  • 步骤架构：新的 steps 数组取代了 outputs 数组，以提供每个交互轮次的结构化时间线。

如需了解最新的破坏性更改并了解如何迁移，请参阅破坏性更改迁移指南（2026 年 5 月）。

其他潜在更新可能包括对输入和输出架构、SDK 方法签名和对象结构以及特定功能行为的更改。

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

反馈

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

后续步骤