openai-responses

用途

OpenAI Responses API 是 OpenAI 面向智能体（agentic）应用的统一接口，2025 年 3 月发布，状态为生产可用。它用于构建需要多轮对话、推理与工具调用的 AI 应用，核心创新是跨轮次保留模型的推理状态。

主要能力

有状态对话：通过 conversation ID 自动管理历史，无需手动追踪；对话 90 天过期。
推理保留：不同于 Chat Completions 在轮次间丢弃推理，Responses 保留模型的推理记录，在 TAUBench 上带来 5% 性能提升。开发者只能获得推理摘要（summary），完整思维链由 OpenAI 内部保留，不对外暴露。
服务端内置工具：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，令牌不存储）。
MCP 集成：内置 Model Context Protocol 支持，可连接 Stripe、数据库、自定义 API 等外部工具。默认需要用户显式批准后才向远程 MCP 服务器共享数据，也可在 OpenAI 仪表盘预批准受信服务器。
后台模式：background: true 用于长任务，标准超时 60 秒，后台模式 10 分钟；需轮询（建议每 5 秒）。后台模式当前首 token 延迟（TTFT）高于同步模式。
多态输出：返回 8 种输出类型（message、reasoning、code_interpreter_call、mcp_call、mcp_list_tools、file_search_call、web_search_call、image_generation_call），可用 response.output_text 辅助获取纯文本。
数据保留与隐私：store: true（默认）时默认保留 30 天；ZDR 组织自动强制 store: false；后台模式不兼容 ZDR（需临时存储约 10 分钟）。

使用方式

安装依赖：npm install openai@6.16.0（Node.js），或使用 fetch API（Cloudflare Workers）。

快速上手示例：

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）。

有状态对话：先用 openai.conversations.create() 创建对话，再在每轮 responses.create 中传入 conversation: conv.id。

内置工具调用示例：

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

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,
  }],
});

后台模式示例：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze 500-page document',
  background: true,
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});
const result = await openai.responses.retrieve(response.id);
if (result.status === 'completed') console.log(result.output_text);

适用场景

智能体应用（推理 + 行动）
多轮对话（保留推理带来 +5% TAUBench）
需要内置工具（Code Interpreter、File Search、Web Search、MCP）
后台处理（标准 60 秒，扩展 10 分钟超时）

不适合：简单一次性生成、完全无状态交互、遗留集成——这些场景建议继续使用 Chat Completions。

迁移

从 Chat Completions 迁移需注意端点、参数、角色、输出、状态、流式格式的变化。从 Assistants API 迁移：Assistants API 已于 2025 年 8 月 26 日弃用，将于 2026 年 8 月 26 日停止工作，需在此前迁移。对应关系：Assistants→Prompts（仪表盘创建）、Threads→Conversations、Runs→Responses、Run-Steps→Items。

限制与已知问题

本技能预防 11 个已记录错误，包括：会话状态不持久（需复用 conversation ID）、MCP 连接失败、Code Interpreter 超时、图像生成限流、文件搜索相关性、成本追踪困惑、对话未找到（90 天过期）、工具输出解析失败、Zod v4 与结构化输出不兼容（建议锁定 zod ^3.23.8）、后台模式 Web Search 缺少来源（需用同步模式）、流式模式缺少 output_text 辅助（需监听 output_text.done 事件）。

其他限制：web_search 的 external_web_access 选项在 SDK 类型中缺失（v6.16.0），需用类型断言绕过；MCP 授权令牌不存储，每次请求都需提供；后台模式不兼容 ZDR；后台模式 TTFT 较高。

参考

官方文档：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/ 下的对比、MCP 集成、内置工具、迁移、常见错误等文档。最后验证：2026-01-21，技能版本 2.1.0。

技能介绍

用途

主要能力

使用方式

适用场景

迁移

限制与已知问题

参考