Next-generation large language model interface architecture

Status: 🚧 In progress

Gemini Interactions API 与 OpenAI Responses API 的设计哲学、技术实现与兼容性分析

1. 引言：从无状态对话到有状态智能体架构的演进

在 Generation Intelligence 的发展历程中，2023 年到 2024 的下半年是一个显著的分水岭，LLM 的应用范式从最原始的**Text Completion)**和 Stateless Chat 向更为复杂的 Agentic Interactions 和 Deep Reasoning 转变。

这个转变一方面带来的是模型能力的提升，另一方面意味着底层软件架构和 API 设计哲学需要对此变化进行重构。

长期以来，基于 RESTful 架构的 Chat Completions API（以 OpenAI 的 /v1/chat/completions 为事实标准）主导了 LLM 时代 AI 开发者的接入方式。这种模式的核心特征是**无状态性：**每一次请求都是独立的，开发者必须在客户端维护完整的对话历史，并在每次交互时将其完整地发送给服务端。虽然这种设计简单且易于扩展，但在面对新一代具备 Long Context、Multimodal Understanding 和 CoT 的模型时，凸显了其相应的局限性。

1. Thinking 数据难处理：我们以推理模型代表(如 OpenAI 的 o1/o3 系列和 Google的Gemini 2.5/3.0 系列)为例：模型在生成最终答案之前会产生大量的 “CoT” 数据。这些数据既是计算资源消耗的大户，也是模型智能的核心体现。在无状态架构下，如果服务端不返回这些思维数据，客户端就无法在下一轮对话中让模型”回忆”起之前的推理过程；如果返回，潜在问题就是带宽占用升高和核心技术泄露风险；

   所以模型厂商给出的解决策略是返回 thinking summary，not really CoT content. 🙂

2. Task time 增加：模型厂商已经不局限于提供单一的基座模型，其提供的另外一种 Agent as Model 的机制，使得单次 API 调用背后对应着的实际执行，已经是 Agents 开始执行跨越数分钟甚至数小时的长程任务，典型是 Deep Reasearch，传统的同步 HTTP request-response 受限于长连接网络超时机制，已无法满足该场景的需要。

下一代 API 的出现

为了尝试解决上面所谈到的问题，两大 AI 巨头分别推出了自己下一代 API 接口：OpenAI的 Responses API 和 Google 的 Interactions API。下面的内容将对这两个 API 进行详细的技术解构，深入分析它们在状态管理、多模态处理、Long Running Task 调度以及推理透明度方面的设计差异，并给出如何在现有的 Agent 框架 ADK 中进行 Interactions API 兼容性适配的方案。

2. OpenAI Responses API：推理即服务的容器化设计

OpenAI 推出的 Responses API 对自家的 Chat Completions 接口设计重构的比较彻底。其核心设计哲学在于将”对话状态”和”推理过程”下沉至服务端，通过引入更加直观的 action 类型系统(Item Ontology)来规范复杂的多轮交互。

这里简单放个对比：

{
  "message": {
    "role": "assistant",
    "content": "I'm going to use the get_weather tool to find the weather.",
    "tool_calls": [
      {
        "id": "call_88O3ElkW2RrSdRTNeeP1PZkm",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\":\"New York, NY\",\"unit\":\"f\"}"
        }
      }
    ],
    "refusal": null,
    "annotations": []
  }
}

对于 chat completions 接口，单次请求只会发出一条 message👆。

 {
    "id": "rs_6888f6d0606c819aa8205ecee386963f0e683233d39188e7",
    "type": "reasoning",
    "summary": [
      {
        "type": "summary_text",
        "text": "**Determining weather response**\n\nI need to answer the user's question about the weather in San Francisco. ...."
      },
  },
  {
    "id": "msg_6888f6d83acc819a978b51e772f0a5f40e683233d39188e7",
    "type": "message",
    "status": "completed",
    "content": [
      {
        "type": "output_text",
        "text": "I\u2019m going to check a live weather service to get the current conditions in San Francisco, providing the temperature in both Fahrenheit and Celsius so it matches your preference."
      }
    ],
    "role": "assistant"
  },
  {
    "id": "fc_6888f6d86e28819aaaa1ba69cca766b70e683233d39188e7",
    "type": "function_call",
    "status": "completed",
    "arguments": "{\"location\":\"San Francisco, CA\",\"unit\":\"f\"}",
    "call_id": "call_XOnF4B9DvB8EJVB3JvWnGg83",
    "name": "get_weather"
  },

而在 Responses API 中，实际上返回的是个完整的行为链，如何展示、记录或者忽略掉什么都是由开发者决定。

2.1 设计哲学：不透明推理与状态托管

Responses API 的诞生，很大程度上是为了解决”推理模型”在商业化落地中的悖论。OpenAI 的 o 系列模型(如 o1， o3)通过 RLHF 在内部生成 long CoT 来提升推理能力。这些 CoT 为核心商业机密，并不希望直接暴露给用户。

在旧有的 Chat API 中，如果模型不返回思维链，用户在进行多轮追问时，模型就会丢失上一轮的思考上下（本质原因是不允许客户端拿到 raw CoT），导致智力”断崖式下跌”。Responses API 通过引入**服务端有状态(Server Statefulness)**来解决这个问题。Responses 会在服务端保留模型的 reasoning state（加密且对客户端隐藏），并允许通过 previous_response_id（或 reasoning items）安全续接下一轮交互。用户只需引用上一次的响应 ID，模型即可在服务端内部继续之前的推理，而无需把原始 CoT 传回客户端。

这种设计哲学可以概括为:“信任服务端的记忆”。它将开发者从繁琐的 Prompt Caching(提示词缓存)和历史记录截断(Truncation)工作中解放出来，但同时也加深了开发者对 OpenAI 基础设施的依赖。

2.2 核心数据模型：Item 本体论的兴起

Responses API 最显著的技术变革是废弃了结构松散的 Message 对象，转而采用类型严格的 Item 联合类型(Union Type)。这一变化反映了多模态输入的复杂性已经超过了单一文本字段的承载能力。

2.2.1 Input Item(输入项)

在 Responses API 中，输入不再是简单的 messages 数组，而是 input 字段，它可以包含多种类型的 InputItem:

2.2.2 Output Item(输出项)

输出同样被结构化为一系列 Item，这使得工具调用、代码解释器输出和文本回复可以被清晰地拆分:

从 Message 到 Item 的转变，标志着 LLM 交互从”Text exchange”转向了”Object operation”。开发者不再是处理一段连续的文本，而是在操作一个由多模态内容构成的结构化对象。

2.3 状态管理机制：previous_response_id 与 reasoning state

Responses 被设计为 stateful-by-default：会话与工具状态由服务端自动追踪；模型的 reasoning state 会在多轮之间被保留（加密且对客户端隐藏），从而让推理模型在后续回合不会“忘记刚才怎么想的”。

基于 ID 的安全续接 (previous_response_id)

• 机制: 开发者在发送请求时提供 previous_response_id（上一轮响应的 id）。服务端会在内部续接上下文与推理状态，并继续推进同一个“推理-行动”循环
• 适用场景: 多轮对话、工具链调用、需要保留推理状态的 agentic workflow
• 注意点: 客户端至少需要保存上一轮的 response id 以便续接；reasoning state 本身不会回传到客户端（避免暴露 raw CoT）

此外，OpenAI 也提到可以通过 reasoning items 辅助安全续接，但原始 CoT 仍不会对客户端暴露。

2.4 流式传输与语义事件

Responses API 的流式传输(Streaming)也不再只是文本 token 的 delta，而是官方所称的 semantic streaming events：围绕响应生命周期与不同 Item（例如 message、function_call、reasoning）的生成过程发出结构化事件（参考👆的示例），客户端可以在交互上更精细地驱动 UI（例如在工具调用开始时立刻展示状态）。

此外，官方也强调 SDK 提供了 output_text 等 helper，避免像 Chat Completions 那样从 choices[0].message.content 里提取文本，其他的开发细节就按下不表了。

3. Google Gemini Interactions API：异步智能体的操作系统

如果说 OpenAI 的 Responses API 是为了优化”思考”(Reasoning)，那么 Google 的 Interactions API 则是为了优化”行动”(Doing)。Google 将 Interactions API 定位为构建自主智能体(Autonomous Agents)的统一接口，特别是针对那些需要长时间运行、跨越多源信息整合的任务。

3.1 设计哲学：时间维度的解放

Google 的设计哲学与 Responses API 的思路一致：对于真正的深度研究或复杂任务处理，其耗时往往超过了标准 HTTP 连接的超时限制(通常为 30-60 秒)。因此，Interactions API 被设计为一个任务调度系统，允许任务在后台运行数十分钟。

3.2 核心架构：Interaction 与 Content

Interactions API 的端点位于 generativelanguage.googleapis.com/v1beta/interactions，其架构与 OpenAI 截然不同。

3.2.1 Interaction 对象

一个 Interaction 不仅仅是一次对话，它是一个包含输入、执行状态和输出结果的完整生命周期对象:

熟悉 Gemini 原本 API endpoint 的同学可能会比较熟悉新的 Interactions API，两种 API 的 request body 中，input 部分的调整相比 OpenAI 的两版 API 并不大，这一点可能与 Gemini 一直主打多模态原生支持的设计理念有关，使得 Gemini input 一开始就允许了多模态输入的复杂性。

3.2.2 状态管理：可选的服务端状态

Interactions API 在“是否托管状态”上更明确：你可以选择把历史交给服务端，也可以完全自己管理。

• Stateful：下一轮请求携带 previous_interaction_id（上一轮 Interaction.id），服务端会自动拉取完整上下文，客户端无需重复发送全量历史；并且更容易命中服务端缓存以降低成本
• Stateless：每次请求都传入完整对话历史（history 数组），由客户端承担上下文拼装
• 存储与合规：Interaction 默认 store=true；若设为 store=false 可以选择不存储，但会阻断后续 previous_interaction_id 续接，并且与 background=true 不兼容
• 对比：OpenAI 的 Responses 强调 stateful-by-default（服务端自动追踪会话与工具状态，并可通过 previous_response_id 安全续接）；Google 则把**“可选的服务端状态”**用 previous_interaction_id 显式暴露出来，并允许无状态地直接提交完整历史。

这里并不是说 OpenAI Responses API 拒绝无状态直接提交完整的 history，和 Gemini 提供的策略一样，两者都支持和 Chat 无状态接口一样通过 input 中构造 history，以达成原有 Chat API 中的交互效果，只是如此一来，是否使用新的 API 不再有任何区别。

Interactions API 的旗舰应用是 Gemini Deep Research Agent。这一点大家都比较熟悉了，就不过多赘述。

3.3 MCP（Model Context Protocol）的原生支持

Google 在 Interactions API 中也明确集成了对 MCP 的支持。

4. 对比分析

综合来看，其实两者并没有太多差异，我们只从一些存在差异的细节方面进行横向对比：

4.1 状态管理与上下文处理

5. 兼容性适配与迁移指南

对于现有的开发者来说，最关心的问题莫过于: 现有的基于 OpenAI Chat API 的代码还能用吗?我该如何迁移?

5.1 Gemini 的 OpenAI 兼容层：真相与陷阱

Google 宣称提供了”三行代码迁移”的 OpenAI 兼容性。这在很大程度上是真实的，但存在一个巨大的**“范围陷阱”**。

兼容范围

Gemini 的兼容层是针对 OpenAI Legacy Chat Completions API (/v1/chat/completions) 的，而不是针对新的 Responses API (/v1/responses)。

• 这意味着，如果使用的是标准的 [openai.chat.completions.create 方法，你确实只需要更改 base_url 和 api_key 即可无缝切换到 Gemini 模型；
• Google 甚至贴心地做了参数映射:将 OpenAI 的 reasoning_effort 参数自动映射为 Gemini 的 thinking_level 或 thinking_budget。这使得开发者可以在不修改业务逻辑的情况下，测试 Gemini 的推理能力；

不兼容范围

你无法通过 OpenAI SDK 使用 Gemini 的 Interactions API 特性:

• 例如，你不能在 OpenAI SDK 中传递 agent='deep-research' 参数
• 你不能传递 background=true 参数来触发异步执行
• 你不能使用 previous_interaction_id 进行链式状态管理

结论： Gemini 的兼容性是为了”抢存量”，即让那些只需要基础对话功能的开发者低成本试用 Gemini。但如果你想利用 Gemini 后续退出的功能(如深度研究)，必须重写代码，使用 Google 官方的 genai SDK。

5.2 从 Chat Completions 迁移到 Responses API（OpenAI 生态内）

即使在 OpenAI 生态内部，从 Chat API 迁移到 Responses API 也是一个单向且昂贵的过程:

1. 重构数据结构

必须将所有的 messages 数组重构为 input 列表。由于 Item 类型系统的引入，简单的字符串拼接不再适用，必须构建结构化的 JSON 对象。

2. 放弃客户端历史管理

开发者需要停止在数据库中存储大段的对话历史，转而至少存储上一轮的 response id（后续通过 previous_response_id 续接）。这虽然简化了数据库，但也意味着应用逻辑更依赖服务端状态。

3. 适配流式解析器

前端必须重写流式解析逻辑，以处理官方所称的语义级事件流(semantic streaming events)及多 Item 输出，而不是 Chat Completions 的 token delta（例如 choices[0].delta.content）。同时可以利用 SDK 的 output_text helper 简化取文本。

5.3 接入适配策略

鉴于 Interactions 和 Chat 在架构上的巨大分歧，试图编写一个能够同时完美支持两者的”通用适配器”其实不太现实。更加建议根据实际的业务场景需求采取**“双栈策略”(Dual-Stack Strategy)**:

同步交互层

对于聊天机器人、实时问答等低延迟场景，继续使用标准的 Chat Completions API 抽象。这层抽象可以同时兼容 OpenAI(旧接口)、Gemini(通过兼容层)、Anthropic 和开源模型(如 vLLM)。无需急于迁移到 Interactions API，这对保持模型中立是非常有利的。

这里也在 Google 官方的 blog 中有所体现：

尽管Interaction API支持大多数generateContent功能，并能提供更强大的开发者体验，但目前仍处于公开测试阶段，因此可能还会出现重大变更。对于标准的生产工作负载，generateContent仍然是主要途径，并将持续得到开发与维护。

异步任务层

对于 Deep Research、Agent kernel 这一层是可以尝试 新的 Interactions API。

6. 使用限制

6.1 State Lock-in

随着 API 变得有状态，供应商绑定的风险会更加严重。

在无状态时代，迁移模型只需改一行 URL。在有状态时代，迁移模型往往意味着要迁移大量会话/工具运行历史，并将其重新映射到另一个供应商的状态模型(如果对方支持的话)。而 reasoning state（被服务端加密隐藏）通常不可导出，这意味着一旦在某个平台上进入一段深度推理/工具链流程，迁移成本会显著上升。

6.2 Agent as Infrastructure

Gemini 的 Deep Research 不仅仅是一个功能，它明确展示着**“智能体即基础设施”**会是未来的一部分。未来的 API 调用可能不再是 completion(prompt)，而是 hire(agent, goal)。API 提供商将不仅提供模型，还提供运行智能体的运行时环境(Runtime)、工具库(Tools)和记忆存储(Memory)。Interactions API 正是这一愿景的雏形。

6.3 Vertex AI not Ready

来自 Google 官方的 Blog：Interactions API 和 Gemini 深度研究功能即将登陆 Vertex AI 平台。https://blog.google/technology/developers/interactions-api/

7. 总结

OpenAI 的 Responses API 和 Google 的 Interactions API 虽然都旨在解决下一代 AI 应用的挑战，但对于开发者而言，选择不再仅仅关于模型性能(Benchmarks)，更关于应用架构的选择：是构建一个即时响应的对话界面，还是构建一个异步交付结果的任务系统。理解这一差异，才是下一代 AI 应用开发的关键。

Appendix

这里尝试就模型服务与 Google 生态集成的现状给出一个可能是最轻的解决方案。

现状：所有基于 ADK 实现的 Agent，为了使用我们自己的模型服务，都采用的是 ADK 提供的 LiteLLM 兼容层来用。

我们的核心诉求是：在 Google ADK 里继续使用“原生 Gemini 能力”（google-genai 的类型系统、tool calling、cachedContents、files/resumable upload、SSE 等），并把所有上游切换/治理/统计都收敛到我们自己的模型代理网关。

在 google-adk 的实现下，这个诉求会直接推导出：网关必须提供 Gemini Developer API（AI Studio / v1beta）兼容面，否则要么只能直连 Google，要么只能走 OpenAI endpoint + LiteLLM（协议与能力会发生漂移）。

ADK 现有三条接入路径（以及限制）

1. ADK Gemini（默认）
   • 走 google-genai SDK（原生 Gemini 体验最好）。
   • 但 ADK 构造 google.genai.Client(...) 时 不提供 base_url，只传 tracking headers（因此“指向自有网关”只能靠 google-genai 的默认 base_url 机制或环境变量）：
     • 见 google/adk/models/google_llm.py 中 Gemini.api_client 的实现。
2. ADK ApigeeLlm（命名为 Apigee，但本质是 proxy client）
   • 也是走 google-genai，但显式支持 proxy_url/base_url，并能注入 custom_headers：
     • 见 google/adk/models/apigee_llm.py 中 HttpOptions(base_url=proxy_url)（附录 A 第 7 点）。
   • 局限：它依然只是在 ADK 内“更方便地把 google-genai 指向代理”，并不会减少网关要做的协议兼容/能力覆盖；且在 vertex_ai 模式下通常要求 GOOGLE_CLOUD_PROJECT/LOCATION，并可能引入调用侧 GCP 凭证路径（与“凭证与切换集中在网关”的目标相悖）。
3. ADK LiteLlm（OpenAI endpoint / provider-style）
   • 适合已具备 OpenAI 兼容网关时快速接入。
   • 但如果强调“原生 Gemini 能力/语义一致”（尤其 cachedContents、files/resumable upload、部分 tool/stream 语义），OpenAI ChatCompletions 需要额外适配且不保证 1:1 等价；最终复杂度仍会回到网关（只是从 Gemini 协议变成 OpenAI 协议）。

因此建议的落地方式

如果我们的目标是“保持原生调用 Gemini”，那在 ADK 场景里最稳的做法是：

• 调用方（ADK）一律按 Gemini Developer API（AI Studio / v1beta）方式调用网关：
  • 通过 GOOGLE_GEMINI_BASE_URL=https://<gateway> 把 google-genai 的 base_url 指向网关；
  • 用 GOOGLE_API_KEY=<gateway_token> 作为网关鉴权（网关把它当作 API key/Token 即可）。
• 不建议在 ADK 默认 Gemini 下用 GOOGLE_GENAI_USE_VERTEXAI=1 + GOOGLE_VERTEX_BASE_URL=... 来“走 Vertex 且指向网关”：
  • google.genai.Client 在初始化时会先基于 vertexai 入参（vertexai or False）决定读取 GOOGLE_GEMINI_BASE_URL 还是 GOOGLE_VERTEX_BASE_URL；而 ADK 默认并不显式传 vertexai=True。
  • 结果是：即使底层 BaseApiClient 后续通过环境变量把模式切到了 Vertex，Client 层也未必会按预期读取 GOOGLE_VERTEX_BASE_URL；最稳的仍是固定走 /v1beta（AI Studio shape）并让网关内部路由到 Vertex。
• 网关内部再决定走 Vertex 还是 AI Studio（或其它 provider）：
  • 推荐按 token 或 X-Client-Id 做路由映射与计量归因；
  • 可选支持 X-LLM-Upstream 这类 header 做灰度/切换（见第 0.1 的方案 B），但在 ADK 默认 Gemini 下需注意下面的限制。

一个容易忽略但很关键的限制：ADK 的 context caching 不会携带“每次请求”自定义的路由 header

• ADK 的 GeminiContextCacheManager 使用共享的 self.api_client 做 caches 调用，并不使用 GenerateContentConfig.http_options（也就不会携带在 generate_content_config 里设置的 header）。
• 因此：如果希望 cachedContents 也能按“每次请求 header”在上游间切换，ADK 默认 Gemini 不足以表达；更稳的是让网关按 token/client 映射决定缓存上游，或在调用侧改用能注入全局 header 的方式（例如 ApigeeLlm(custom_headers=...) 或自定义 model_code）。