openai-responses by jezweb/claude-skills
npx skills add https://github.com/jezweb/claude-skills --skill openai-responses状态 : 生产就绪 最后更新 : 2026-01-21 API 发布时间 : 2025年3月 依赖项 : openai@6.16.0 (Node.js) 或 fetch API (Cloudflare Workers)
OpenAI 为智能体应用提供的统一接口,于 2025年3月 发布。提供具有 跨轮次保留推理状态 的 有状态对话。
关键创新: 与 Chat Completions(推理在轮次间被丢弃)不同,Responses 保留了模型的推理笔记,在 TAUBench 上性能提升 5%,并实现了更好的多轮交互。
与 Chat Completions 对比:
| 特性 | Chat Completions | Responses API |
|---|---|---|
| 状态 | 手动历史记录跟踪 | 自动(对话 ID) |
| 推理 | 轮次间丢弃 | 跨轮次保留(TAUBench +5%) |
| 工具 | 客户端往返 | 服务器端托管 |
| 输出 | 单一消息 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 多态(8 种类型) |
| 缓存 | 基线 | 利用率提升 40-80% |
| MCP | 手动 | 内置 |
npm install openai@6.16.0
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:
使用对话 ID 进行自动状态管理:
// 创建对话
const conv = await openai.conversations.create({
metadata: { user_id: 'user_123' },
});
// 第一轮
const response1 = await openai.responses.create({
model: 'gpt-5',
conversation: conv.id,
input: 'What are the 5 Ds of dodgeball?',
});
// 第二轮 - 模型记住上下文 + 推理
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' }],
});
TypeScript 限制:web_search 工具的 external_web_access 选项在 SDK 类型中缺失(截至 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], // ✅ 类型断言以抑制错误
});
内置支持模型上下文协议 (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') {
// 向用户显示:"此操作需要与 Stripe 共享数据。批准吗?"
// 用户批准后,使用批准令牌重试
}
替代方案:在 OpenAI 仪表板中预先批准 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, // ⚠️ 不存储,每次请求都需要
}],
});
MCP 输出类型:
mcp_list_tools - 在服务器上发现的工具mcp_call - 工具调用 + 结果message - 最终响应关键创新: 模型的内部推理状态在轮次间得以保留(与 Chat Completions 丢弃它不同)。
视觉类比:
性能: 在 TAUBench 上提升 5%(GPT-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 模型:
对于长时间运行的任务,使用 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] }],
});
// 轮询完成状态(每 5 秒检查一次)
const result = await openai.responses.retrieve(response.id);
if (result.status === 'completed') console.log(result.output_text);
超时限制:
首令牌时间 (TTFT) 延迟: 后台模式目前比同步响应具有更高的 TTFT。OpenAI 正在努力缩小这一差距。
建议:
默认保留:当 store: true(默认)时为 30 天 零数据保留 (ZDR):具有 ZDR 的组织自动强制执行 store: false 后台模式:不兼容 ZDR(存储数据约 10 分钟用于轮询)
时间线:
store: true 时默认保留 30 天控制存储:
// 禁用存储(无保留)
const response = await openai.responses.create({
model: 'gpt-5',
input: 'Hello!',
store: false, // ✅ 无保留
});
// ZDR 组织:store 始终被视为 false
const response = await openai.responses.create({
model: 'gpt-5',
input: 'Hello!',
store: true, // ⚠️ 对于 ZDR 组织,OpenAI 会忽略,视为 false
});
ZDR 合规性:
store: false来源: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);
});
// 或使用仅文本的辅助函数
console.log(response.output_text);
重大变更:
| 特性 | Chat Completions | Responses API |
|---|---|---|
| 端点 | /v1/chat/completions | /v1/responses |
| 参数 | messages | input |
| 角色 | system | developer |
| 输出 | choices[0].message.content | output_text |
| 状态 | 手动数组 | 自动(对话 ID) |
| 流式传输 | data: {"choices":[...]} | 包含 8 种项目类型的 SSE |
示例:
// 之前
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);
// 之后
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 停用时间线
在 2026年8月26日之前迁移以避免重大变更。
关键重大变更:
| Assistants API | Responses API |
|---|---|
| 助手(通过 API 创建) | 提示(在仪表板中创建) |
| 线程 | 对话(存储项目,不仅仅是消息) |
| 运行(服务器端生命周期) | 响应(无状态调用) |
| 运行步骤 | 项目(多态输出) |
迁移示例:
// 之前(Assistants API - 已弃用)
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,
});
// 之后(Responses API - 当前)
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. 会话状态未持久化
const conv = await openai.conversations.create()),在所有轮次中重用 conv.id2. MCP 服务器连接失败 (mcp_connection_error)
fetch() 手动测试,检查令牌过期3. 代码解释器超时 (code_interpreter_timeout)
background: true 以延长超时(最长 10 分钟)4. 图像生成速率限制 (rate_limit_error)
5. 文件搜索相关性问题
chunk.score > 0.7 过滤6. 成本跟踪混淆
store: false,监控 response.usage.tool_tokens7. 对话未找到 (invalid_request_error)
openai.conversations.list() 验证存在性8. 工具输出解析失败
response.output_text 辅助函数或迭代 response.output.forEach(item => ...) 并检查 item.type9. Zod v4 与结构化输出不兼容
错误:Invalid schema for response_format 'name': schema must be a JSON Schema of 'type: "object"', got 'type: "string"'.
发生原因:SDK 的 vendored zod-to-json-schema 库不支持 Zod v4(缺少 ZodFirstPartyTypeKind 导出)
预防:固定使用 Zod v3("zod": "^3.23.8")或使用自定义 zodTextFormat 并设置 z.toJSONSchema({ target: "draft-7" })
// 解决方法:固定使用 Zod v3(推荐) { "dependencies": { "openai": "^6.16.0", "zod": "^3.23.8" // 暂时不要升级到 v4 } }
10. 后台模式网络搜索缺少来源
错误:web_search_call 输出项目包含查询但没有来源/结果
发生原因:当使用 background: true + web_search 工具时,OpenAI 不会在响应中返回来源
预防:当需要网络搜索来源时,使用同步模式(background: false)
// ✅ 同步模式下来源可用 const response = await openai.responses.create({ model: 'gpt-5', input: 'Latest AI news?', background: false, // 获取来源所必需 tools: [{ type: 'web_search' }], });
11. 流式模式缺少 output_text 辅助函数
错误:finalResponse().output_text 在流式模式下是 undefined
发生原因:stream.finalResponse() 不包含 output_text 便利字段(仅在非流式响应中可用)
预防:监听 output_text.done 事件或手动从 output 项目中提取
// 解决方法:监听事件 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; // ✅ 在事件中可用 } }
✅ 始终:
background: trueauthorization 令牌(不存储,每次请求都需要)response.usage.total_tokens 以控制成本❌ 绝不:
response.output_text 辅助函数)rate_limit_error、mcp_connection_error)官方文档:
技能资源: 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、后台网络搜索、流式 output_text),2 个 TIER 2 发现(MCP 批准、推理隐私),数据保留与 ZDR 部分,Assistants API 停用时间线,后台模式 TTFT 说明,网络搜索 TypeScript 限制。更新 SDK 版本至 6.16.0。
每周安装
346
仓库
GitHub 星标
650
首次出现
2026年1月20日
安全审计
安装于
claude-code291
gemini-cli238
opencode234
codex212
cursor208
antigravity205
Status : Production Ready Last Updated : 2026-01-21 API Launch : March 2025 Dependencies : openai@6.16.0 (Node.js) or fetch API (Cloudflare Workers)
OpenAI's unified interface for agentic applications, launched March 2025. Provides stateful conversations with preserved reasoning state across turns.
Key Innovation: Unlike Chat Completions (reasoning discarded between turns), Responses preserves the model's reasoning notebook , improving performance by 5% on TAUBench and enabling better multi-turn interactions.
vs Chat Completions:
| Feature | Chat Completions | Responses API |
|---|---|---|
| State | Manual history tracking | Automatic (conversation IDs) |
| Reasoning | Dropped between turns | Preserved across turns (+5% TAUBench) |
| Tools | Client-side round trips | Server-side hosted |
| Output | Single message | Polymorphic (8 types) |
| Cache | Baseline | 40-80% better utilization |
| MCP | Manual | Built-in |
npm install openai@6.16.0
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);
Key differences from Chat Completions:
/v1/responses (not /v1/chat/completions)input (not messages)developer (not system)response.output_text (not choices[0].message.content)Use Responses:
Use Chat Completions:
Automatic State Management using conversation IDs:
// 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',
});
Benefits: No manual history tracking, reasoning preserved, 40-80% better cache utilization
Conversation Limits: 90-day expiration
Server-side hosted tools eliminate backend round trips:
| Tool | Purpose | Notes |
|---|---|---|
code_interpreter | Execute Python code | Sandboxed, 30s timeout (use background: true for longer) |
file_search | RAG without vector stores | Max 512MB per file, supports PDF/Word/Markdown/HTML/code |
web_search | Real-time web information | Automatic source citations |
image_generation | DALL-E integration | DALL-E 3 default |
Usage:
const response = await openai.responses.create({
model: 'gpt-5',
input: 'Calculate mean of: 10, 20, 30, 40, 50',
tools: [{ type: 'code_interpreter' }],
});
TypeScript Limitation : The web_search tool's external_web_access option is missing from SDK types (as of v6.16.0).
Workaround :
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
});
Source : GitHub Issue #1716
Built-in support for Model Context Protocol (MCP) servers to connect external tools (Stripe, databases, custom APIs).
By default, explicit user approval is required before any data is shared with a remote MCP server (security feature).
Handling Approval :
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
}
Alternative : Pre-approve MCP servers in OpenAI dashboard (users configure trusted servers via settings)
Source : Official MCP Guide
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 Output Types:
mcp_list_tools - Tools discovered on servermcp_call - Tool invocation + resultmessage - Final responseKey Innovation: Model's internal reasoning state survives across turns (unlike Chat Completions which discards it).
Visual Analogy:
Performance: +5% on TAUBench (GPT-5) purely from preserved reasoning
Reasoning Summaries (free):
response.output.forEach(item => {
if (item.type === 'reasoning') console.log(item.summary[0].text);
if (item.type === 'message') console.log(item.content[0].text);
});
What You Get : Reasoning summaries (not full internal traces) What OpenAI Keeps : Full chain-of-thought reasoning (proprietary, for security/privacy)
For GPT-5-Thinking models:
Source : Sean Goedecke Analysis
For long-running tasks, use 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);
Timeout Limits:
Time-to-First-Token (TTFT) Latency: Background mode currently has higher TTFT compared to synchronous responses. OpenAI is working to reduce this gap.
Recommendation:
Source : OpenAI Background Mode Docs
Default Retention : 30 days when store: true (default) Zero Data Retention (ZDR) : Organizations with ZDR automatically enforce store: false Background Mode : NOT ZDR compatible (stores data ~10 minutes for polling)
Timeline :
store: trueControl Storage :
// 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 Compliance :
store: false for claritySource : OpenAI Data Controls
Returns 8 output types instead of single message:
| Type | Example |
|---|---|
message | Final answer, explanation |
reasoning | Step-by-step thought process (free!) |
code_interpreter_call | Python code + results |
mcp_call | Tool name, args, output |
mcp_list_tools | Tool definitions from MCP server |
file_search_call | Matched chunks, citations |
Processing:
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);
Breaking Changes:
| Feature | Chat Completions | Responses API |
|---|---|---|
| Endpoint | /v1/chat/completions | /v1/responses |
| Parameter | messages | input |
| Role | system | developer |
| Output | choices[0].message.content |
Example:
// 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);
CRITICAL: Assistants API Sunset Timeline
Migrate before August 26, 2026 to avoid breaking changes.
Source : Assistants API Sunset Announcement
Key Breaking Changes:
| Assistants API | Responses API |
|---|---|
| Assistants (created via API) | Prompts (created in dashboard) |
| Threads | Conversations (store items, not just messages) |
| Runs (server-side lifecycle) | Responses (stateless calls) |
| Run-Steps | Items (polymorphic outputs) |
Migration Example:
// 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!' },
],
});
Migration Guide : Official Assistants Migration Docs
This skill prevents 11 documented errors:
1. Session State Not Persisting
const conv = await openai.conversations.create()), reuse conv.id for all turns2. MCP Server Connection Failed (mcp_connection_error)
fetch(), check token expiration3. Code Interpreter Timeout (code_interpreter_timeout)
background: true for extended timeout (up to 10 min)4. Image Generation Rate Limit (rate_limit_error)
5. File Search Relevance Issues
chunk.score > 0.76. Cost Tracking Confusion
store: false if not needed, monitor response.usage.tool_tokens7. Conversation Not Found (invalid_request_error)
openai.conversations.list() before using8. Tool Output Parsing Failed
response.output_text helper or iterate response.output.forEach(item => ...) checking item.type9. Zod v4 Incompatibility with Structured Outputs
Error : Invalid schema for response_format 'name': schema must be a JSON Schema of 'type: "object"', got 'type: "string"'.
Source : GitHub Issue #1597
Why It Happens : SDK's vendored zod-to-json-schema library doesn't support Zod v4 (missing ZodFirstPartyTypeKind export)
Prevention : Pin to Zod v3 ("zod": "^3.23.8") or use custom zodTextFormat with 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. Background Mode Web Search Missing Sources
Error : web_search_call output items contain query but no sources/results
Source : GitHub Issue #1676
Why It Happens : When using background: true + web_search tool, OpenAI doesn't return sources in the response
Prevention : Use synchronous mode (background: false) when web search sources are needed
// ✅ 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. Streaming Mode Missing output_text Helper
Error : finalResponse().output_text is undefined in streaming mode
Source : GitHub Issue #1662
Why It Happens : stream.finalResponse() doesn't include output_text convenience field (only available in non-streaming responses)
Prevention : Listen for output_text.done event or manually extract from output items
// 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 } }
✅ Always:
background: true for tasks >30sauthorization tokens (NOT stored, required each request)response.usage.total_tokens for cost control❌ Never:
response.output_text helper)rate_limit_error, mcp_connection_error specifically)Official Docs:
Skill Resources: 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
Last verified : 2026-01-21 | Skill version : 2.1.0 | Changes : Added 3 TIER 1 issues (Zod v4, background web search, streaming output_text), 2 TIER 2 findings (MCP approval, reasoning privacy), Data Retention & ZDR section, Assistants API sunset timeline, background mode TTFT note, web search TypeScript limitation. Updated SDK version to 6.16.0.
Weekly Installs
346
Repository
GitHub Stars
650
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykWarn
Installed on
claude-code291
gemini-cli238
opencode234
codex212
cursor208
antigravity205
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
43,400 周安装
mcp| Connect external tools |
| OAuth supported, tokens NOT stored |
web_search_call | URLs, snippets |
image_generation_call | Image URL |
output_text |
| State | Manual array | Automatic (conversation ID) |
| Streaming | data: {"choices":[...]} | SSE with 8 item types |