openai-responses

OpenAI Responses API

状态：生产就绪 | API 发布：2025 年 3 月 | SDK：[email protected]+

---

快速入门（5 分钟）

Node.js

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);

Cloudflare Workers

const response = await fetch('https://api.openai.com/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    input: 'Hello, world!',
  }),
});

const data = await response.json();
console.log(data.output_text);

加载 references/setup-guide.md，查看包含有状态对话和内置工具的完整设置指南。

---

什么是 Responses API？

Responses API（/v1/responses）是 OpenAI 于 2025 年 3 月推出的统一 Agent 应用接口。关键创新：在多轮对话中保留推理状态（与会丢弃推理状态的 Chat Completions 不同），在 TAUBench 上将多轮性能提升约 5%。

为什么选择 Responses 而不是 Chat Completions？ 自动状态管理、保留推理状态、服务端工具、缓存利用率提升 40–80%，以及内置 MCP 支持。

加载 references/responses-vs-chat-completions.md，查看完整对比和选择指南。

---

最重要的 3 条规则

务必做到 ✅

1. 保存 conversation_id——在不同轮次间保留状态（最重要）
2. 使用环境变量存放 API 密钥（绝不硬编码）
3. 处理多态输出——检查 output.type（message、reasoning、function_call）

绝对不要 ❌

1. 绝不忽略 conversation_id——否则状态会丢失
2. 绝不假设输出只有一种类型——始终检查 output.type
3. 绝不在同一对话中混用 Chat Completions 和 Responses

加载 references/setup-guide.md，查看完整规则和最佳实践。

---

5 大使用场景

使用场景 1：有状态对话

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'My favorite color is blue.',
});

const conversationId = response1.conversation_id;

// Second turn - model remembers
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: conversationId,
  input: 'What is my favorite color?',
});
// Output: "Your favorite color is blue."

加载：references/stateful-conversations.md + templates/stateful-conversation.ts

---

使用场景 2：网页搜索 Agent

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search the web for latest AI news.',
  tools: {
    web_search: { enabled: true },
  },
});

加载：references/built-in-tools-guide.md + templates/web-search.ts

---

使用场景 3：代码解释器

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate the sum of squares from 1 to 100.',
  tools: {
    code_interpreter: { enabled: true },
  },
});

加载：references/built-in-tools-guide.md + templates/code-interpreter.ts

---

使用场景 4：文件搜索（RAG）

// Upload file
const file = await openai.files.create({
  file: fs.createReadStream('document.pdf'),
  purpose: 'user_data',
});

// Search file
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Summarize key points from the uploaded document.',
  tools: {
    file_search: {
      enabled: true,
      file_ids: [file.id],
    },
  },
});

加载：references/built-in-tools-guide.md + templates/file-search.ts

---

使用场景 5：MCP 服务集成

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get weather for San Francisco.',
  tools: {
    mcp_servers: [
      {
        url: 'https://weather-mcp.example.com',
        tool_choice: 'auto',
      },
    ],
  },
});

加载：references/mcp-integration-guide.md + templates/mcp-integration.ts

---

内置工具

所有工具都在服务端运行：代码解释器（Python 执行）、文件搜索（RAG）、网页搜索（实时）、图像生成（DALL-E）。

显式启用：

tools: {
  code_interpreter: { enabled: true },
  file_search: { enabled: true, file_ids: ['file-123'] },
  web_search: { enabled: true },
  image_generation: { enabled: true },
}

加载 references/built-in-tools-guide.md，查看包含示例和配置选项的完整指南。

---

有状态对话

通过对话 ID 实现的自动状态管理可免去手动跟踪消息、保留推理状态，并将缓存利用率提升 40–80%。

// Create conversation
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'Remember: my name is Alice.',
});

// Continue conversation
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response1.conversation_id,
  input: 'What is my name?',
});

加载 references/stateful-conversations.md，查看持久化模式（Node.js/Redis/KV）和生命周期管理。

---

从 Chat Completions 迁移

快速变更：messages → input，system 角色 → developer，choices[0].message.content → output_text，/v1/chat/completions → /v1/responses。

迁移前（Chat Completions）：

const messages = [{ role: 'user', content: 'Hello' }];
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: messages,
});
messages.push(response.choices[0].message); // Manual history

迁移后（Responses API）：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
});

const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response.conversation_id, // Automatic state
  input: 'Follow-up question',
});

加载 references/migration-guide.md，查看包含工具迁移模式的完整迁移清单。

---

多态输出

Responses 可能返回多种输出类型（message、reasoning、function_call、image）。请处理每种类型，或使用便捷属性 output_text。

for (const output of response.output) {
  if (output.type === 'message') {
    console.log('Message:', output.content);
  } else if (output.type === 'reasoning') {
    console.log('Reasoning:', output.summary);
  } else if (output.type === 'function_call') {
    console.log('Function:', output.name, output.arguments);
  }
}

// Or use convenience property
console.log(response.output_text);

加载 references/reasoning-preservation.md，查看推理输出详情和调试模式。

---

后台模式

对于长时间运行的任务（>60 秒），使用 background: true 异步运行，并轮询任务完成状态。

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze this 50-page document.',
  background: true,
});

// Poll for completion
const completed = await openai.responses.retrieve(response.id);

加载 templates/background-mode.ts，查看包含指数退避的完整轮询模式。

---

3 大常见错误及解决方案

错误 1：会话状态未保留

症状：模型不记得之前的对话轮次。

原因：未使用对话 ID，或每次都创建新对话。

解决方案：

// ✅ GOOD: Reuse conversation ID
const conv = await openai.conversations.create();
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID
  input: 'Question 1',
});
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID - remembers previous
  input: 'Question 2',
});

---

错误 2：MCP 服务连接失败

原因：服务 URL 无效，或授权令牌缺失／已过期。

解决方案：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Test MCP',
  tools: [
    {
      type: 'mcp',
      server_url: 'https://mcp.stripe.com', // ✅ Full HTTPS URL
      authorization: process.env.STRIPE_OAUTH_TOKEN, // ✅ Valid token
    },
  ],
});

预防措施：使用环境变量保存密钥，实现令牌刷新逻辑，并添加指数退避重试。

---

错误 3：代码解释器超时

原因：代码运行时间超过 30 秒（标准模式的限制）。

解决方案：

// ✅ GOOD: Use background mode for long tasks
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Process this massive dataset',
  background: true, // ✅ Up to 10 minutes
  tools: [{ type: 'code_interpreter' }],
});

// Poll for results
let result = await openai.responses.retrieve(response.id);
while (result.status === 'in_progress') {
  await new Promise(r => setTimeout(r, 5000));
  result = await openai.responses.retrieve(response.id);
}

加载 references/top-errors.md，查看全部 8 种错误的详细解决方案和预防策略。

---

何时加载参考资料

在以下情况下加载 references/setup-guide.md：

• 首次使用 Responses API，需要完整的 Node.js 或 Cloudflare Workers 设置指南
• 需要包含环境特定最佳实践的生产部署检查清单
• 排查设置问题，或实现流式／后台模式

在以下情况下加载 references/responses-vs-chat-completions.md：

• 在 Responses API 和 Chat Completions API 之间进行选择
• 了解性能基准（TAUBench 结果、缓存利用率）
• 评估迁移工作量或比较成本结构

在以下情况下加载 references/migration-guide.md：

• 按照分步检查清单从 Chat Completions API 迁移
• 需要代码对比示例（迁移前／后的模式）
• 将工具从自定义函数迁移到内置工具／MCP

在以下情况下加载 references/built-in-tools-guide.md：

• 使用 Code Interpreter、File Search、Web Search 或 Image Generation
• 需要了解工具配置选项、组合多个工具的方法或故障排查

在以下情况下加载 references/mcp-integration-guide.md：

• 集成外部 MCP 服务或构建自定义 MCP 工具
• 需要 MCP 配置示例或身份验证模式

在以下情况下加载 references/stateful-conversations.md：

• 使用 KV／Redis／数据库实现对话持久化
• 需要对话生命周期管理或元数据跟踪模式

在以下情况下加载 references/reasoning-preservation.md：

• 需要访问模型推理过程，以便调试或提高透明度
• 构建可审计的 AI 系统，或需要推理输出示例

在以下情况下加载 references/top-errors.md：

• 遇到 API 错误（涵盖 8 种常见错误及其解决方案）
• 需要错误代码参考、预防策略或错误处理模式

---

生产环境检查清单

部署前：

• 安全存储 API 密钥（环境变量或密钥）
• 已实现错误处理（401、429、400、500）
• 已处理速率限制（指数退避）
• 已持久化对话 ID（数据库／KV）
• 已为较长的响应启用流式传输
• 已显式启用工具
• 已处理多态输出

加载 references/setup-guide.md，查看完整的生产环境检查清单及平台特定注意事项。

---

相关技能

• openai-api - 经典 Chat Completions API
• openai-agents - OpenAI Agents SDK（Responses 的封装）
• claude-api - 用于对比的 Claude API
• ai-sdk-core - Vercel AI SDK（支持 Responses）

---

官方文档

• Responses API：https://platform.openai.com/docs/api-reference/responses
• 迁移指南：https://platform.openai.com/docs/guides/responses-migration
• 内置工具：https://platform.openai.com/docs/guides/responses-tools
• MCP 集成：https://platform.openai.com/docs/guides/mcp

---

有问题或遇到故障？

1. 查看 references/top-errors.md 获取错误解决方案
2. 查看 references/setup-guide.md 了解完整设置流程
3. 查看 references/migration-guide.md 了解 Chat Completions 迁移
4. 从 templates/ 加载模板，查看可运行示例