青蛙小白

Responses API（响应 API）

Responses API（响应 API） 是 OpenAI 用来执行模型推理、暴露工具调用、返回流式事件并支持对话压缩的 API。Codex 的 CLI 通过它驱动 Agent Loop（智能体循环）。

OpenAI 在 2025 年 3 月发布《New tools for building agents》时，把 Responses API 定位为新 Agent 平台的核心 API primitive：它合并了 Chat Completions API 的简单请求形态和 Assistants API 的工具调用能力。对新 Agent 集成，OpenAI 建议优先从 Responses API 开始；Chat Completions 继续服务不需要内置工具的场景，而 Assistants API 在功能对齐后计划迁移到 Responses API。

在 Agent 场景中，Responses API 的意义不只是"发一段文本，收一段文本"。它把模型推理过程拆成可被 harness 消费的结构化项目：消息、reasoning、function call、function call output、assistant message、compaction item 等。

三个核心输入

Codex 使用 Responses API 时，最关键的请求字段包括：

  • instructions：系统或开发者指令，可来自 Codex 内置模型指令或用户配置
  • tools：模型可调用的工具定义，既包括 Codex 内置工具，也包括 Web search、MCP 工具等
  • input：消息、文件、图片、工具调用历史和工具输出等输入项目列表

服务端会把这些结构化 JSON 转成模型实际消费的 prompt。对 OpenAI 托管端点来说，系统内容、工具定义、instructions 和 input 的排序由服务端决定；客户端控制其中很大一部分内容，但不直接手写最终 prompt。

在自定义工具上，Responses API 使用 Function Calling（函数调用）承载“模型请求工具、应用执行工具、再把结果回传”的闭环。模型返回的 function_call 包含 name、JSON 编码的 arguments 和 call_id；应用执行后，需要把 function_call_output 与同一个 call_id 绑定回输入中，供下一轮模型推理使用。

当模型需要直接返回结构化答案时，Responses API 可通过 text.format 使用 Structured Outputs（结构化输出）。这与函数调用的职责不同：text.format 约束最终回复的数据形状，函数调用约束“要调用哪个工具、传什么参数”。

与 Agents SDK 的选型边界

OpenAI 的 Agents SDK 指南把两者的分工概括为：想自己拥有 loop 时用 Responses API；想让 SDK 运行 loop 时用 OpenAI Agents SDK。

Responses API 的核心抽象是一次模型 response。它适合开发者直接控制模型交互、输出项、工具调用、状态和分支逻辑：应用接收函数调用，执行工具，把输出回传，再决定是否继续调用模型。换句话说，Responses API 给的是可组合的底层原语；loop、routing、状态存储、审批和 trace 如何组合，主要由应用自己决定。

Agents SDK 的核心抽象是 agent run。它把常见循环封装起来：重复工具调用、handoff 后切换 specialist agent、sessions、tracing、guardrails 和可恢复审批流程都由 SDK 提供更高层的结构。这个边界不表示 SDK 更“高级”或 Responses API 更“底层”就一定更好，而是工程控制权不同：越需要定制循环，越接近 Responses API；越需要稳定复用的事务型 Agent 工作流，越接近 SDK。

OpenAI API 工具层

Responses API 通过 tools 参数承载 OpenAI API Tools（OpenAI API 工具）。模型会根据输入自动判断是否调用已配置工具，开发者也可以用 tool_choice 显式控制或引导工具选择。

OpenAI 官方 Using tools 文档把工具层扩展为内置工具、自定义函数、tool search 和远程 MCP 的组合，而不是只包含早期发布时的几类托管工具：

工具作用典型场景
Web search让模型获取带引用的最新网页信息研究 Agent、购物助手、旅行规划
File search基于向量存储检索大量文档，支持查询优化、元数据过滤和 reranking客服知识库、法律文档查询、代码文档问答
Tool search让模型运行时加载延迟定义的工具大工具集、企业内部工具目录、低频工具按需暴露
Function Calling调用应用自定义函数查询数据库、调用业务 API、执行内部动作
Programmatic Tool Calling模型生成 JavaScript 编排允许的工具调用，并在托管运行时缩减中间结果批量查询后的聚合、过滤与校验；可预测的多步数据流
Remote MCP连接远程 MCP 服务器接入第三方或企业内部工具服务器
Connectors通过 connector_id 调用 OpenAI API 内置第三方连接器访问 Dropbox、Gmail、Google Drive、SharePoint 等 SaaS 上下文
Shell给模型一个可执行命令、读写文件的受控环境数据处理、代码运行、报告生成、多步文件工作流
Computer use通过 Computer-Using Agent模型生成鼠标和键盘动作，驱动浏览器或桌面环境Web QA、数据录入、遗留系统自动化

这使 Responses API 不只是一个通用推理端点，而是把一部分 Harness Engineering（驾驭工程）常见能力产品化：工具接入、工具输出结构、trace、eval 和内置安全措施都可以由平台提供一部分。应用仍然需要自己定义业务权限、人工审批和高风险动作边界。

MCP 和 OpenAI API Connectors在 Responses API 中共享 type: "mcp" 工具形态。Remote MCP 使用 server_url 指向外部 MCP server；connector 使用 connector_id 指向 OpenAI API 内置的第三方服务连接器。两者调用成功后都会在 response output 中出现 mcp_call，失败时也会通过同一类输出项承载协议错误、工具执行错误或连接错误。

Skills 不是独立的 tools[].type，而是 Shell 工具环境的附加能力。这里的 Shell 是 Responses API 的工具能力，不属于 Chat Completions API；它可以运行在 OpenAI 托管容器（hosted shell，environment.type: "container_auto"）里，也可以运行在开发者自管的 local shell runtime 里。开发者通过 tools[].environment.skills 把包含 SKILL.md、脚本和资产的 Skill bundle 挂载到 Shell 环境里；模型先看到 Skill 的 name、description 和 path，需要时再读取 SKILL.md。因此 Skill 更像“可挂载的过程包”，而不是一次原子函数调用。

Programmatic Tool Calling（程序化工具调用）也是托管工具，但边界不同：它让模型在全新隔离的 V8 runtime 中生成 JavaScript 来调用本次授权的工具，不能获得 Node.js、网络、文件系统或子进程权限。对函数、MCP、shell 等 eligible 工具，allowed_callers 可限制为 direct、programmatic 或两者皆可；适合处理可预测的数据流，不能替代审批敏感写入与最终语义核验。

使用 Skills 的基本路径：先把可复用流程写成 SKILL.md + 支持文件；OpenAI 托管容器 Shell 场景用 POST /v1/skills 上传并取得 skill_id；调用 Responses API 时在 Shell 工具的 environment.skills 中引用它。local shell 场景不使用上传后的 skill_reference，而是直接提供本地 name、description 和 path。

事件流

Responses API 可通过 Server-Sent Events 返回增量事件。Codex 会消费这些事件并转成内部事件对象：

  • 输出文本 delta 用于 UI 流式显示
  • reasoning item 和 function call item 会追加到后续请求的 input 中
  • function call output 绑定 call id，作为下一次推理的观察结果
  • assistant message 表示当前 turn 结束

这使 Harness Engineering（驾驭工程） 可以在模型生成过程中持续观察、转发、记录和执行动作，而不是等一个完整字符串返回后再解析。

Responses API 可在 assistant 输出项上使用 phase 区分 commentary/preamble 与 final answer。harness 手动重放历史时，需要把 assistant item 及其原始 phase 一起保存并传回；如果历史重建时丢掉 phase，模型会更难区分工作中的用户更新和最终回答，长任务表现可能退化。使用 previous_response_id 时，先前的 assistant 状态会自动延续。

无状态请求与 ZDR

Responses API 支持用 previous_response_id 避免重复发送完整历史，但 Codex 在文章描述的实现中没有使用它，主要是为了保持请求无状态并支持 Zero Data Retention 配置。

无状态请求简化了 API 提供方和数据保留语义，但代价是每次请求都携带不断增长的 input。Codex 因此依赖Prompt Caching（提示缓存）降低推理成本，并在上下文超过阈值时使用 compact 机制。

对 GPT-5.6，reasoning.context 还控制可用 reasoning item 的复用范围。它适合目标、假设和优先级仍稳定的多轮任务；当旧推理已与当前问题无关时，应改用当前 turn 的行为，避免旧思路增加 token、延迟或造成锚定。它与对话历史续接相关，但不替代应用自己的任务状态和长期记忆。

Compact 机制

Responses API 提供 /responses/compact 端点，用更小的项目列表替换原始输入，从而释放上下文窗口。与普通摘要不同，compact 结果可以包含特殊的 type=compaction 项，并携带不透明的加密内容，用来保留模型对原对话的隐含理解。

这把Context Engineering（上下文工程）中的"上下文压缩"从客户端自写摘要，推进到 API 层的一等能力。

相关概念

参考来源
  1. 1. https://openai.com/index/unrolling-the-codex-agent-loop/
  2. 2. https://openai.com/index/new-tools-for-building-agents/
  3. 3. https://developers.openai.com/api/docs/guides/tools
  4. 4. https://developers.openai.com/api/docs/guides/function-calling
  5. 5. https://developers.openai.com/api/docs/guides/structured-outputs
  6. 6. https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide
  7. 7. https://developers.openai.com/api/docs/guides/agents
  8. 8. https://developers.openai.com/api/docs/guides/tools-connectors-mcp
  9. 9. https://developers.openai.com/api/docs/guides/tools-shell
  10. 10. https://developers.openai.com/api/docs/guides/tools-skills
  11. 11. https://developers.openai.com/cookbook/examples/skills_in_api
  12. 12. https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling
  13. 13. https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6
评论