Responses API 工程实践：从协议迁移到多模型接入

2026 年 8 月 26 日，Assistants API 正式下线。GPT-5 及更新的模型仅通过 Responses API 提供，Chat Completions 进入维护模式。这一时间表意味着，Responses API 不再是“要不要用”的选项，而是构建生产级 Agent 系统的默认起点。本文从工程视角出发，梳理 Responses API 的核心机制、迁移中的真实成本，以及多模型场景下的接入架构决策。

一、协议演进的本质：从消息到动作序列

Responses API 与 Chat Completions 的差异，不能简单理解为“新接口替代旧接口”。更深层的变化在于数据模型、状态模型和事件模型三个维度的重构。

数据模型的变化最为根本。 Chat Completions 的输入输出是 messages 数组，每个对象包含 role 和 content。Responses API 使用 Items，它是一个联合类型，可以表示 message、function_call、function_call_output、reasoning summary 等多种模型动作。这意味着工具调用、推理过程和文本回复不再是“粘”在消息对象上的字段，而是响应中一等公民的独立对象。调试 Agent 时，开发者可以直接查看模型“做了什么”，而不仅仅是“说了什么”。

状态模型从客户端持有转向服务端托管。 Chat Completions 要求调用方在每次请求中重建完整的消息历史。Responses API 引入 previous_response_id 参数，客户端只需在每轮传入新的用户消息，并携带上一轮的响应 ID，服务端会自动维护状态链。官方文档明确提示：使用 previous_response_id 链式调用时，不要手动裁剪历史。

事件模型从文本增量升级为语义化事件流。 DeepSeek 的 Responses API 文档展示了完整的事件列表：response.created、response.output_item.added、response.reasoning_text.delta、response.function_call_arguments.delta、response.completed 等。流以 response.completed 或 response.failed 结束，没有 Chat Completions 中常见的 data: [DONE] 消息。这种设计让 Agent 运行时可以精确监听工具调用参数增量，而不必解析原始文本块。

二、性能数据：迁移带来的可量化收益与代价

OpenAI 内部评测提供了两个关键数据点：使用推理模型时，Responses API 在 SWE-bench 上有 3% 的提升，缓存利用率相比 Chat Completions 提高 40% 至 80%。缓存利用率的提升直接转化为成本降低，因为缓存命中部分按更低的费率计费。

但收益有代价。多个开发者报告显示，有状态模式下的请求延迟约为无状态 Chat Completions 的 2 倍。对于延迟敏感的用户交互流程，这是一个需要在架构中显式处理的约束。一个可行的缓解策略是在 Agent 循环中使用 Responses API 保持状态，而在面向用户的即时响应场景中，通过无状态调用或流式输出降低感知延迟。

另一个容易被忽略的约束来自 GPT-6 Astra 的对齐监控器。当监控器标记未授权行为时，API 任务会被直接终止，没有恢复路径。这意味着生产 Agent 的工作流必须可以从持久化状态中恢复，而不能依赖会话在内存中的存活。

三、迁移决策：分阶段而非全量替换

对于已有 Chat Completions 集成的项目，全量迁移通常不是最优策略。官方指南的定位是：Chat Completions 仍然被支持，Responses API 推荐用于所有新项目。

更务实的迁移路径是按能力模块逐步切换。以下三类模块优先迁移：

工具调用密集的模块。 Responses API 将 Agent 循环内置到单次请求中，模型可以在一次调用内依次调用 web_search、file_search、code_interpreter、远程 MCP 服务器或自定义函数，直到达到停止条件。在 Chat Completions 中，这个循环需要应用层手动实现：调用模型、解析工具调用、执行工具、追加结果、再次调用。

需要多模态输入的模块。 Responses API 原生支持文本和图像输入，DeepSeek 的文档显示图片通过 input_image 内容块传入，支持 HTTP URL、base64 data URL 或 Files API 上传的 file_id。

结构化输出要求严格的模块。 Responses API 使用 text.format 替代 Chat Completions 的 response_format，直接约束响应为符合 JSON Schema 的结果。

迁移中的一个技术细节：多轮对话处理方式不同。Chat Completions 中，开发者将 assistant 消息追加到 messages 数组。Responses API 中，可以使用 previous_response_id 链式调用，也可以选择无状态模式，将上一轮的输出 Items 手动追加到新的 input 数组中。两种方式的选择取决于是否需要服务端托管状态。

四、多模型接入的工程挑战

Responses API 的推广抬高了第三方模型接入 Codex 等 Agent 工具的门槛。Codex 要求模型提供商平台原生支持 /v1/responses 端点才能直接对接。如果只提供 Chat Completions，就需要在中间加一层协议转换。

目前已有多种桥接方案。codex-relay 是一个轻量 Rust 代理，将 Codex 的 Responses API 请求转译为 Chat Completions，支持 DeepSeek、Kimi、Qwen 等提供商。另一种方案是使用支持 Responses API 的模型提供商直连——DeepSeek V4-Flash 在 2026 年 7 月 31 日的正式版中原生支持 Responses API，官方配置从 wire_api = "chat" 切换为 wire_api = "responses"，Codex 的子 Agent 调度和并行工具调用能力得以完整使用。

协议兼容性的现状并不均衡。在主流模型中，OpenAI 完整支持 Responses API；Claude 和 Gemini 的原生协议并非 Responses 格式，需要通过桥接层转换。这意味着，当 Agent 工作流需要在不同模型之间切换时，协议差异会带来实际的配置管理成本。

五、统一接入层的工程价值

当项目同时使用多个模型时——例如用推理能力强的模型做规划、用成本更低的模型执行子任务——config.toml 中的 provider 条目会逐渐增多。API Key 管理、错误码归一化、用量统计的跨供应商聚合，这些工作随模型数量线性增长。

统一 API 接入层的价值在于把协议转换、凭证管理和路由分发收敛到一个可观测的层面。Agent 侧的配置只需指向网关端点，由网关侧完成 Responses 与 Chat Completions 之间的协议映射。对于已经在使用 OpenAI SDK 的项目，迁移成本主要在调整 base_url 和 api_key 两个配置项。

koalaAPI 作为 API 中转站，提供 200 余个模型的接入能力，覆盖 20 余家模型及服务供应商。开发者使用一个 API Key 即可调用平台已接入的模型，Agent 侧只需面对一套接口，协议适配和路由分发在网关层完成。

需要明确的是，统一网关解决的是接入层的工程问题。它不会消除不同模型在系统提示词遵循、工具调用格式和上下文限制方面的差异。Agent 的行为在不同模型上仍然会有可观测的偏差。在把某个模型投入生产 Agent 循环之前，用真实工具调用链验证其可靠性，仍然是不可跳过的步骤。

六、设计 Responses API 集成的几个判断

状态管理的位置决定了系统的可迁移性。 把会话状态交给服务端托管，应用层代码更轻，但状态的可观测性和跨平台迁移能力降低。如果会话数据对业务逻辑有直接价值，需要在架构中保留足够的审计和导出能力。

延迟预算是架构设计的硬约束。 有状态模式约 2 倍的延迟增长，意味着面向用户的即时交互不能依赖有状态链式调用。一个可行的模式是：Agent 循环使用 Responses API 保持状态，用户界面通过流式事件实时展示进度。

工具定义的组织方式和暴露方式同等重要。 当 Agent 可调用的工具从几个增长到几十个，工具定义本身会占据可观的上下文空间。Responses API 的远程 MCP 支持让模型可以在单次请求中发现并调用 MCP 服务器的工具，减少了应用层手动编排的需要。

迁移不是一次性事件。 从 Chat Completions 到 Responses API 的过渡期会持续较长时间。按模块分阶段迁移，优先切换工具调用密集和多模态输入模块，是控制风险的有效路径。

了解更多：https://koalaapi.com