Interactions API 概览

Interactions API 提供了一个统一的有状态接口，用于使用 Gemini 模型和托管在 Gemini Enterprise Agent Platform 上的智能体构建生成式 AI 应用和智能体工作流。虽然 generateContent API 与现有的 generateContent API 在功能上有所重叠，但 generateContent API 仍会获得全面支持。

为什么要使用 Interactions API？

对于构建生成式 AI 应用和智能体工作流，Interactions API 具有以下几项关键优势：

  • 适用于模型和代理的单一 API：一个统一的端点和模式，用于直接调用标准 Gemini 模型以及专用代理（例如 Gemini Deep Research Agent 和自定义托管式代理）。
  • 开箱即用的新功能：包括使用 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 提供的实时公开 Web 数据对模型回答进行接地。
  • 代码执行：让模型能够在安全的沙盒环境中生成和执行 Python 代码。
  • 函数调用：通过返回结构化函数实参，使模型能够连接到外部工具、API 和数据库。

Interactions API 支持企业版 Web Grounding 和依托 Google 搜索进行接地。使用这些功能时，您还必须遵守其服务专用条款。

结算

Interactions API 的使用费用根据 token 消耗量计费。

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

  • 手动取消：如果互动在完成之前被取消（例如，通过发送取消请求），您需要支付取消时已消耗的令牌费用。
  • 失败的请求：如果互动请求因内部系统错误或后端故障而失败，您无需为失败的请求付费。

安全与合规性

在预览版期间，使用 Interactions API 时，请注意以下安全性、合规性和数据驻留注意事项：

  • 安全和合规性认证：Interactions API 预览版不支持 FedRAMP 或客户管理的加密密钥 (CMEK)，也不符合美国国防部 (DoD) Impact Level 5 (IL5) 或国际武器运输条例 (ITAR) 要求。
  • VPC Service Controls：Interactions API 预览版支持 VPC Service Controls (VPC-SC)，以保护您的 API 边界。
  • 数据驻留：Interactions API 预览版不支持数据驻留，并且不对会话存储做出任何承诺。
  • 端点：Interactions API 预览版仅支持全球端点 (locations/global)。

支持的 SDK

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

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

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

后续步骤