Interactions API 概览

Interactions API 提供了一个统一的有状态接口，用于使用 Gemini Enterprise Agent Platform 上托管的 Gemini 模型和 Agentic Workflows 构建生成式 AI 应用和 Agentic Workflows。generateContent API 仍会与 Interactions API 一起得到全面支持。

为何使用 Interactions API？

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

  • 适用于模型和智能体的单一 API：一个统一的端点和模式，可直接调用标准 Gemini 模型以及专用智能体（例如 Gemini Deep Research 智能体和自定义托管式智能体）。
  • 开箱即用的新功能：包括使用 previous_interaction_id 的可选服务器端对话状态、用于调试和界面渲染的可观察执行步骤，以及使用 background=true 的长时间运行任务的后台执行。

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：

点击即可展开支持的模型

除了上述列表中的 Gemini 模型之外，Interactions API 还支持以下生成式音乐模型： * 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 会将互动存储在服务器 (store=true) 上 7 天，以便您使用 previous_interaction_id 串联多轮对话并运行异步后台任务 (background=true)。如需选择无状态执行并支持零数据保留 (ZDR) 工作流，请设置 store=false。如需了解详情，请参阅管理会话存储和对话状态。

请求和多模态限制

Interactions API 强制执行以下请求载荷和多模态输入限制：

  • 请求载荷限制：对于同步和流式 interactions.create 请求，压缩的 HTTP 请求载荷不能超过 256 MiB。如果 service_tier 设置为 deferred（这要求 background 和 store 均为 true），则未压缩的请求不能超过 9.75 MiB。
  • Cloud Storage 文件的 URI 限制：标准 Gemini 模型互动请求支持每个请求最多 100 个不同的 Cloud Storage (gs://) URI，包括通过 previous_interaction_id 从先前对话轮次中继承的 URI。托管式代理互动、Gemini Omni 模型和 Lyria 3 模型不在此 100 个 URI 的限制范围内。如需了解权限和多轮 URI 处理，请参阅访问上传的 Cloud Storage 文件。
  • 多模态内容和 token 限制：标准 Gemini 模型接受的每种模态内容数量与 generateContent 相同（最多 3,000 个图片和 PDF 组合、1,000 个音频文件、10 个视频，以及最多 6,500 个多模态文件组合 [包含纯文本文件时]），受模型 1,048,576 个 token 的上下文窗口限制。单个 Cloud Storage 文件不能超过 2 GiB 减去 500 KiB，公开 HTTP 或 HTTPS 网址不能超过 15 MiB。如需在单个请求中发送超过 100 个文件，请在请求载荷限制内以内嵌方式传递其他附件，或调用 generateContent。

支持的工具和接地

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

  • 依托 Google 搜索进行接地和 Web Grounding for Enterprise：依托 Google 搜索或 Web Grounding for Enterprise 中的实时网络信息对模型回答进行接地。
  • Gemini Enterprise Agent Platform 上的 Agent Search 和 RAG 引擎：使用 Agent Search 和 RAG 引擎，根据私有企业数据存储区和文档库为模型回答提供依据。
  • Exa 网页搜索：使用 Exa 搜索 API 提供的网页搜索结果来接地模型回答。
  • Parallel Web Search：依托 Parallel Web Systems 的搜索 API 提供的实时公开网页数据对模型回答进行接地。
  • 网址上下文：检索并分析提示中包含的公开网址中的内容。
  • 代码执行：使模型能够在安全的沙盒环境中生成和执行 Python 代码。
  • 计算机使用：支持浏览器和界面自动化工作流。
  • 函数调用：使模型能够通过返回结构化函数参数来连接到外部工具、API 和数据库。

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

结算

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

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

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

安全与合规性

Interactions API 支持以下安全控制、合规认证和端点配置：

  • 端点：Interactions API 支持全球端点（aiplatform.googleapis.com 上的 locations/global）以及 us 和 eu 多区域端点（aiplatform.us.rep.googleapis.com 上的 locations/us 和 aiplatform.eu.rep.googleapis.com 上的 locations/eu）。不支持单区域端点（例如 us-central1 或 europe-west1）。
  • 数据驻留：当您使用 us 和 eu 多区域端点（locations/us 和 locations/eu）时，Interactions API 支持机器学习处理（使用中）和存储的静态互动数据 (store=true) 的数据驻留。发送到 global 端点的请求不提供数据驻留保证。
  • 客户管理的加密密钥 (CMEK)： Interactions API 支持 通过服务配置文件（ scope 设置为 INTERACTIONS_API）为存储的互动数据提供 CMEK ，适用于 us 和 eu 多区域。CMEK 不支持 global 端点。
  • VPC Service Controls (VPC-SC)：Interactions API 支持 VPC-SC，有助于保护 API 边界并降低数据渗漏风险。
  • Access Transparency (AXT)：Interactions API 支持 AXT 日志，以便在 Google 员工访问存储的互动内容时提供近乎实时的公开范围。
  • 安全和合规认证：Interactions API 在 Google Cloud FedRAMP High 授权边界内满足 FedRAMP High 要求。Interactions API 不符合美国国防部 (DoD) Impact Level 5 (IL5) 或《国际武器贸易条例》(ITAR) 的要求。

支持的 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。

后续步骤