Interactions API 概览

Interactions API 提供了一个统一的有状态接口，用于使用 Gemini 模型和托管在 Gemini Enterprise Agent Platform 上的 Agentic Workflows 构建生成式 AI 应用和 Agentic Workflows。虽然此 API 与现有的 generateContent API 在功能上有所重叠，但 generateContent API 仍完全受支持。

为什么要使用 Interactions API？

Interactions API 在构建生成式 AI 应用和 Agentic Workflows 方面具有以下几项关键优势：

  • 适用于模型和智能体的单个 API：一个统一的端点和模式，用于 直接调用标准 Gemini 模型以及专用智能体 （例如 Gemini Deep Research 智能体和自定义托管式智能体）。
  • 开箱即用的新功能：例如，使用 previous_interaction_id 的可选服务器端 对话状态、用于调试和界面呈现的可观测执行 步骤，以及使用 background=true 的长时间运行任务的后台执行。
  • 新功能的发布位置：今后，所有新模型、多模态 功能、工具和智能体功能都将在 Interactions API 上受支持。

Interactions API 的工作原理

Interactions API 以 Interaction 资源为中心。Interaction 表示对话或任务中的完整轮次，并充当会话记录，其中包含按时间顺序排列的执行 steps 序列：

  • user_input：为该轮次提供的输入消息、多模态文件或工具结果。使用 interactions.get 检索的存储交互包含 user_input 步骤以提供完整上下文，而 interactions.create 响应仅返回在该轮次中生成的步骤。
  • thought：模型或智能体在规划其响应时生成的中间推理摘要。
  • 工具调用和结果步骤：客户端或服务器端工具调用 和输出（例如 function_call 和 function_result）。
  • model_output：模型或智能体生成的最终文本、结构化 JSON 或多模态内容。

当您调用 interactions.create时， Agent Platform 会处理您的输入，执行任何已配置的服务器端 工具或智能体循环，并返回生成的 Interaction 资源。如需查看 Python、TypeScript/JavaScript 和 REST 的代码 示例，请参阅 Interactions API 开发者指南。

支持的模型

以下 Gemini 模型支持 Interactions API：

点击即可展开支持的模型

除了上面列出的模型之外，Interactions API 还支持以下专用多模态和音频生成模型：

  • gemini-omni-flash-preview：高性能多模态模型，用于对话式视频生成、编辑和电影控制。
  • lyria-3-clip-preview 和 lyria-3-pro-preview：生成式音乐模型，用于高保真音频片段和完整歌曲创作（仅在无状态交互中受支持，且 store=false）。

支持的智能体

您可以通过 Interactions API 调用以下智能体，方法是指定 agent 参数而不是 model：

  • antigravity-preview-05-2026：通用型自主智能体，专为多步推理、编码、文件操作和工具使用而设计。
  • deep-research-preview-04-2026： Gemini Deep Research 智能体 专为自主多步网络研究和综合而设计。
  • 部署在 Agent Platform 上的 自定义托管式智能体。

功能和规范

以下部分介绍了 Interactions API 的核心功能、技术规范和运营注意事项。

状态管理

默认情况下，Interactions API 会存储请求，因此您可以使用 previous_interaction_id 来利用服务器端状态管理功能。您可以将 store=false 设置为选择无状态行为。

支持的工具和接地

Interactions API 中的 Gemini 3 模型支持以下内置工具、接地提供程序和搜索功能：

  • 依托 Google 搜索进行接地和 Web Grounding for Enterprise： 使用 Google 搜索或 Web Grounding for Enterprise 中的实时网络信息对模型响应进行接地。
  • Gemini Enterprise Agent Platform 上的 Agent Search 和 RAG 引擎：使用 Agent Search 和 RAG 引擎根据私有企业数据存储区和文档 库对模型响应进行接地。
  • xAI Search：将模型连接到实时社交搜索和知识 接地。
  • Parallel Search：使用 Parallel Web Systems 的搜索 API 提供的实时公开网络数据对模型响应进行接地。
  • 代码执行：让模型在安全的沙盒环境中生成和 执行 Python 代码。
  • **函数调用**：通过返回结构化函数实参，使模型能够连接 到外部工具、API 和数据库。

Interactions API 支持 Web Grounding for Enterprise 和依托 Google 搜索进行接地。您对这些功能的使用还需遵守其 服务专用条款。

结算

Interactions API 的使用情况按令牌消耗量结算。

对于中断或未完成的请求，结算方式如下：

  • 手动取消：如果在交互完成之前取消（例如，通过发送取消请求），系统会向您收取取消时消耗的令牌费用。
  • 请求失败：如果交互请求因内部 系统错误或后端故障而失败，系统不会向您收取失败 请求的费用。

安全与合规性

在预览期间，Interactions API 具有以下安全、合规性和数据驻留注意事项：

  • 安全与合规性认证 ：Interactions API 预览版不支持 FedRAMP，也不符合美国国防部 (DoD) Impact Level 5 (IL5) 或国际武器贸易条例 (ITAR) 要求。
  • 客户管理的加密密钥 (CMEK)：Interactions API 通过 服务配置文件 （将 scope 设置为 INTERACTIONS_API）在 us 和 eu 多区域中支持 CMEK，用于存储交互数据。
  • VPC Service Controls：Interactions API 预览版支持 VPC Service Controls (VPC-SC)，以保护您的 API 边界。
  • 数据驻留：Interactions API 预览版不支持数据 驻留，并且不对会话存储做出任何承诺。
  • 端点：Interactions API 预览版支持全局端点 (locations/global)，并且在使用 CMEK 时支持 us 和 eu 多区域端点 (locations/us 和 locations/eu)。

支持的 SDK

您可以使用统一的 Google Gen AI SDK 或直接 REST 调用来访问 Interactions API：

  • Python：google-genai 版本 2.3.0 或更高版本
  • TypeScript / JavaScript：@google/genai 版本 2.3.0 或更高版本
  • Go: google.golang.org/genai
  • Java：com.google.genai:google-genai

旧版 SDK（google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai）不支持 Interactions API。

后续步骤