openai-responses

OpenAI Responses API

状态：已准备好用于生产环境 最后更新：2026-01-21 API 发布：2025 年 3 月 依赖项：[email protected]（Node.js）或 fetch API（Cloudflare Workers）

---

什么是 Responses API？

OpenAI 为 Agent 应用提供的统一接口，于 2025 年 3 月 发布。支持有状态对话，并在多轮对话中保留推理状态。

关键创新： 与 Chat Completions（轮次之间会丢弃推理）不同，Responses 会保留模型的推理笔记，使 TAUBench 性能提升 5%，并支持更好的多轮交互。

与 Chat Completions 对比：

特性	Chat Completions	Responses API
状态	手动跟踪历史记录	自动（对话 ID）
推理	轮次之间会丢弃	多轮之间保留（TAUBench 提升 +5%）
工具	客户端往返调用	服务端托管
输出	单条消息	多态（8 种类型）
缓存	基准水平	利用率提升 40-80%
MCP	手动	内置

---

快速开始

npm install [email protected]

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What are the 5 Ds of dodgeball?',
});

console.log(response.output_text);

与 Chat Completions 的主要区别：

• 端点：/v1/responses（而非 /v1/chat/completions）
• 参数：input（而非 messages）
• 角色：developer（而非 system）
• 输出：response.output_text（而非 choices[0].message.content）

---

何时使用 Responses，何时使用 Chat Completions

使用 Responses：

• Agent 应用（推理 + 操作）
• 多轮对话（保留推理 = TAUBench 提升 +5%）
• 内置工具（Code Interpreter、File Search、Web Search、MCP）
• 后台处理（标准超时 60 秒，扩展超时 10 分钟）

使用 Chat Completions：

• 简单的一次性生成
• 完全无状态的交互
• 旧版集成

---

有状态对话

使用对话 ID 自动管理状态：

// Create conversation
const conv = await openai.conversations.create({
  metadata: { user_id: 'user_123' },
});

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'What are the 5 Ds of dodgeball?',
});

// Second turn - model remembers context + reasoning
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'Tell me more about the first one',
});

优势： 无需手动跟踪历史记录、保留推理、缓存利用率提升 40-80%

对话限制： 90 天后过期

---

内置工具（服务端）

服务端托管工具无需后端往返调用：

工具	用途	备注
code_interpreter	执行 Python 代码	沙箱隔离，超时 30 秒（如需更长时间，请使用 background: true）
file_search	无需向量存储的 RAG	单个文件最大 512MB，支持 PDF/Word/Markdown/HTML/代码
web_search	实时网络信息	自动引用来源
image_generation	DALL-E 集成	默认使用 DALL-E 3
mcp	连接外部工具	支持 OAuth，不存储令牌

用法：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate mean of: 10, 20, 30, 40, 50',
  tools: [{ type: 'code_interpreter' }],
});

Web Search TypeScript 说明

TypeScript 限制：SDK 类型中缺少 web_search 工具的 external_web_access 选项（截至 v6.16.0）。

解决方法：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search for recent news',
  tools: [{
    type: 'web_search',
    external_web_access: true,
  } as any],  // ✅ Type assertion to suppress error
});

来源：GitHub Issue #1716

---

MCP 服务集成

内置支持 Model Context Protocol (MCP) 服务，用于连接外部工具（Stripe、数据库、自定义 API）。

用户批准要求

默认情况下，向远程 MCP 服务共享任何数据之前，都必须获得用户明确批准（安全功能）。

处理批准：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get my Stripe balance',
  tools: [{
    type: 'mcp',
    server_label: 'stripe',
    server_url: 'https://mcp.stripe.com',
    authorization: process.env.STRIPE_TOKEN,
  }],
});

if (response.status === 'requires_approval') {
  // Show user: "This action requires sharing data with Stripe. Approve?"
  // After user approves, retry with approval token
}

替代方案：在 OpenAI 控制面板中预先批准 MCP 服务（用户可通过设置配置受信任的服务）

来源：官方 MCP 指南

基本 MCP 用法

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Roll 2d6 dice',
  tools: [{
    type: 'mcp',
    server_label: 'dice',
    server_url: 'https://example.com/mcp',
    authorization: process.env.TOKEN, // ⚠️ NOT stored, required each request
  }],
});

MCP 输出类型：

• mcp_list_tools - 服务上发现的工具
• mcp_call - 工具调用及其结果
• message - 最终响应

---

推理保留

关键创新： 模型的内部推理状态可在多轮之间保留（而 Chat Completions 会丢弃该状态）。

形象类比：

• Chat Completions：模型在回答前会撕掉草稿纸
• Responses API：草稿纸会留着供下一轮使用

性能： 仅凭保留推理，GPT-5 在 TAUBench 上的表现就提升了 +5%

推理摘要（免费）：

response.output.forEach(item => {
  if (item.type === 'reasoning') console.log(item.summary[0].text);
  if (item.type === 'message') console.log(item.content[0].text);
});

重要：推理轨迹隐私

你会获得什么：推理摘要（而非完整的内部轨迹） OpenAI 会保留什么：完整的思维链推理（专有信息，用于安全和隐私保护）

对于 GPT-5-Thinking 模型：

• OpenAI 会在其后端内部保留推理
• 这些保留的推理可提升多轮交互性能（TAUBench 提升 +5%）
• 但开发者只能收到摘要，而非实际的思维链
• 不会公开完整的推理轨迹（用于保护 OpenAI 的知识产权）

来源：Sean Goedecke 的分析

---

后台模式

对于长时间运行的任务，请使用 background: true：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze 500-page document',
  background: true,
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// Poll for completion (check every 5s)
const result = await openai.responses.retrieve(response.id);
if (result.status === 'completed') console.log(result.output_text);

超时限制：

• 标准：60 秒
• 后台：10 分钟

性能注意事项

首个令牌延迟（TTFT）： 与同步响应相比，后台模式目前的 TTFT 更高。OpenAI 正在努力缩小这一差距。

建议：

• 对于面向用户的实时响应，请使用同步模式（延迟较低）
• 对于长时间运行的异步任务，请使用后台模式（可接受较高延迟）

来源：OpenAI 后台模式文档

---

数据保留与隐私

默认保留期限：当 store: true（默认值）时为 30 天 零数据保留（ZDR）：启用 ZDR 的组织会自动强制设置 store: false 后台模式：与 ZDR 不兼容（会存储数据约 10 分钟以供轮询）

时间线：

• 2025 年 9 月 26 日：OpenAI 法院命令要求的数据保留期结束
• 当前：store: true 时默认保留 30 天

控制存储：

// Disable storage (no retention)
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello!',
  store: false,  // ✅ No retention
});

// ZDR organizations: store always treated as false
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello!',
  store: true,  // ⚠️ Ignored by OpenAI for ZDR orgs, treated as false
});

符合 ZDR 要求：

• 避免使用后台模式（需要临时存储）
• 明确设置 store: false
• 注意：同步模式下适用 60 秒超时

来源：OpenAI 数据控制

---

多态输出

返回 8 种输出类型，而非单条消息：

类型	示例
message	最终答案、解释
reasoning	逐步思考过程（免费！）
code_interpreter_call	Python 代码 + 结果
mcp_call	工具名称、参数、输出
mcp_list_tools	MCP 服务提供的工具定义
file_search_call	匹配的片段、引用
web_search_call	URL、摘要
image_generation_call	图片 URL

处理方式：

response.output.forEach(item => {
  if (item.type === 'reasoning') console.log(item.summary[0].text);
  if (item.type === 'web_search_call') console.log(item.results);
  if (item.type === 'message') console.log(item.content[0].text);
});

// Or use helper for text-only
console.log(response.output_text);

---

从 Chat Completions 迁移

不兼容变更：

功能	Chat Completions	Responses API
端点	/v1/chat/completions	/v1/responses
参数	messages	input
角色	system	developer
输出	choices[0].message.content	output_text
状态	手动数组	自动（会话 ID）
流式传输	data: {"choices":[...]}	包含 8 种条目类型的 SSE

示例：

// Before
const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
});
console.log(response.choices[0].message.content);

// After
const response = await openai.responses.create({
  model: 'gpt-5',
  input: [
    { role: 'developer', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
});
console.log(response.output_text);

---

从 Assistants API 迁移

重要：Assistants API 停用时间线

• 2025 年 8 月 26 日：Assistants API 正式弃用
• 2025—2026 年：OpenAI 提供迁移工具
• 2026 年 8 月 26 日：Assistants API 停用（停止工作）

请在 2026 年 8 月 26 日之前完成迁移，以避免发生不兼容变更。

来源：Assistants API 停用公告

主要不兼容变更：

Assistants API	Responses API
Assistants（通过 API 创建）	Prompts（在控制面板中创建）
Threads	Conversations（存储条目，而不仅是消息）
Runs（服务端生命周期）	Responses（无状态调用）
Run-Steps	Items（多态输出）

迁移示例：

// Before (Assistants API - deprecated)
const assistant = await openai.beta.assistants.create({
  model: 'gpt-4',
  instructions: 'You are helpful.',
});

const thread = await openai.beta.threads.create();

const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
});

// After (Responses API - current)
const conversation = await openai.conversations.create({
  metadata: { purpose: 'customer_support' },
});

const response = await openai.responses.create({
  model: 'gpt-5',
  conversation: conversation.id,
  input: [
    { role: 'developer', content: 'You are helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
});

迁移指南：Assistants 迁移官方文档

---

已知问题防范

此技能可防范 11 个已记录的错误：

1. 会话状态未持久化

• 原因：未使用对话 ID，或每轮使用不同的 ID
• 解决方法：创建一次对话（const conv = await openai.conversations.create()），并在所有轮次中重复使用 conv.id

2. MCP 服务连接失败（mcp_connection_error）

• 原因：URL 无效、身份验证令牌缺失或过期、服务已关闭
• 解决方法：确认 URL 正确，使用 fetch() 手动测试，并检查令牌是否过期

3. 代码解释器超时（code_interpreter_timeout）

• 原因：代码运行时间超过 30 秒
• 解决方法：对于需要更长超时的任务，使用 background: true（最长 10 分钟）

4. 图像生成速率限制（rate_limit_error）

• 原因：DALL-E 请求过多
• 解决方法：实施指数退避重试（延迟 1 秒、2 秒、3 秒）

5. 文件搜索相关性问题

• 原因：模糊的查询会返回不相关的结果
• 解决方法：使用具体的查询（例如使用“2024 年第 4 季度的定价”，而不是“查找定价”），并按 chunk.score > 0.7 筛选

6. 成本跟踪混淆

• 原因：Responses 会对输入 + 输出 + 工具 + 已存储的对话计费（而 Chat Completions 仅对输入 + 输出计费）
• 解决方法：如果不需要存储，请设置 store: false，并监控 response.usage.tool_tokens

7. 未找到对话（invalid_request_error）

• 原因：ID 拼写错误、对话已删除或已过期（90 天期限）
• 解决方法：使用前通过 openai.conversations.list() 确认对话存在

8. 工具输出解析失败

• 原因：访问了错误的输出结构
• 解决方法：使用 response.output_text 辅助方法，或迭代 response.output.forEach(item => ...) 并检查 item.type

9. Zod v4 与结构化输出不兼容

• 错误：Invalid schema for response_format 'name': schema must be a JSON Schema of 'type: "object"', got 'type: "string"'.
• 来源：GitHub Issue #1597
• 原因：SDK 内置的 zod-to-json-schema 库不支持 Zod v4（缺少 ZodFirstPartyTypeKind 导出）
• 预防方法：固定使用 Zod v3（"zod": "^3.23.8"），或使用自定义的 zodTextFormat，并搭配 z.toJSONSchema({ target: "draft-7" })

// Workaround: Pin to Zod v3 (recommended)
{
  "dependencies": {
    "openai": "^6.16.0",
    "zod": "^3.23.8"  // DO NOT upgrade to v4 yet
  }
}

10. 后台模式下的网页搜索缺少来源

• 错误：web_search_call 输出项包含查询，但不包含来源或结果
• 来源：GitHub Issue #1676
• 原因：使用 background: true + web_search 工具时，OpenAI 不会在响应中返回来源
• 预防方法：需要网页搜索来源时，请使用同步模式（background: false）

// ✅ Sources available in sync mode
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Latest AI news?',
  background: false,  // Required for sources
  tools: [{ type: 'web_search' }],
});

11. 流式模式缺少 output_text 辅助方法

• 错误：在流式模式下，finalResponse().output_text 为 undefined
• 来源：GitHub Issue #1662
• 原因：stream.finalResponse() 不包含 output_text 便捷字段（仅在非流式响应中可用）
• 预防方法：监听 output_text.done 事件，或从 output 项中手动提取

// Workaround: Listen for event
const stream = openai.responses.stream({ model: 'gpt-5', input: 'Hello!' });
let outputText = '';
for await (const event of stream) {
  if (event.type === 'output_text.done') {
    outputText = event.output_text;  // ✅ Available in event
  }
}

---

关键模式

✅ 始终：

• 多轮对话使用对话 ID（缓存效果提升 40-80%）
• 处理多态响应中的全部 8 种输出类型
• 对超过 30 秒的任务使用 background: true
• 提供 MCP authorization 令牌（不会被存储，每次请求都必须提供）
• 监控 response.usage.total_tokens 以控制成本

❌ 绝不：

• 在客户端代码中暴露 API 密钥
• 假设输出只有一条消息（使用 response.output_text 辅助方法）
• 在不同用户之间重复使用对话 ID（存在安全风险）
• 忽略错误类型（针对 rate_limit_error 和 mcp_connection_error 进行处理）
• 以短于 1 秒的间隔轮询后台任务（使用 5 秒的间隔）

---

参考资料

官方文档：

• Responses API 指南：https://platform.openai.com/docs/guides/responses
• API 参考：https://platform.openai.com/docs/api-reference/responses
• MCP 集成：https://platform.openai.com/docs/guides/tools-connectors-mcp
• 博客文章：https://developers.openai.com/blog/responses-api/
• 入门应用：https://github.com/openai/openai-responses-starter-app

技能资源： templates/、references/responses-vs-chat-completions.md、references/mcp-integration-guide.md、references/built-in-tools-guide.md、references/migration-guide.md、references/top-errors.md

---

最后验证时间：2026-01-21 | 技能版本：2.1.0 | 变更：新增 3 个 TIER 1 问题（Zod v4、后台网页搜索、streaming output_text），新增 2 个 TIER 2 发现（MCP 审批、推理隐私），新增数据保留与 ZDR 章节、Assistants API 终止时间线、后台模式 TTFT 说明，以及网页搜索的 TypeScript 限制。SDK 版本更新至 6.16.0。