Interactions API 概览

Interactions API 提供了一个统一的有状态接口，用于使用 Gemini Enterprise Agent Platform 上托管的 Gemini 模型和 Agentic Workflows 构建生成式 AI 应用和 Agentic Workflows。虽然与现有 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 时，智能体平台会处理您的输入，执行所有已配置的服务器端工具或智能体循环，并返回生成的 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 进行无状态互动时受支持）。

支持的智能体

您可以通过指定 agent 参数（而非 model）来通过 Interactions API 调用以下智能体：

  • 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 搜索：将模型连接到实时社交搜索和知识接地。
  • Parallel Search：依托 Parallel Web Systems 的搜索 API 提供的实时公开网络数据对模型回答进行接地。
  • 代码执行：使模型能够在安全的沙盒环境中生成和执行 Python 代码。
  • 函数调用：使模型能够通过返回结构化函数参数来连接到外部工具、API 和数据库。

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

结算

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

对于中断或未完成的请求，系统会按以下方式处理结算：

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

安全与合规性

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

  • 安全与合规认证：Interactions API 预览版不支持 FedRAMP，也不符合美国国防部 (DoD) 影响级别 5 (IL5) 或《国际武器贸易条例》(ITAR) 的要求。
  • 客户管理的加密密钥 (CMEK)：Interactions API 通过服务配置文件（scope 设置为 INTERACTIONS_API）在 us 和 eu 多区域中支持针对存储的互动数据的 CMEK。
  • VPC Service Controls：Interactions API 预览版支持 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。

后续步骤