openai-responses

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAI Responses API

Status: Production Ready | API Launch: March 2025 | SDK: openai@5.19.1+

状态：已就绪可用于生产 | API发布时间：2025年3月 | SDK版本：openai@5.19.1+

Quick Start (5 Minutes)

快速入门（5分钟）

Node.js

typescript

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

typescript

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

typescript

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

Load
references/setup-guide.md
for complete setup with stateful conversations and built-in tools.

typescript

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
。

What Is the Responses API?

什么是Responses API？

The Responses API (

/v1/responses

) is OpenAI's unified interface for agentic applications launched March 2025. Key Innovation: Preserved reasoning state across turns (unlike Chat Completions which discards it), improving multi-turn performance by ~5% on TAUBench.

Why Use Responses Over Chat Completions? Automatic state management, preserved reasoning, server-side tools, 40-80% better cache utilization, and built-in MCP support.

Load
references/responses-vs-chat-completions.md
for complete comparison and decision guide.

Responses API（

/v1/responses

）是OpenAI于2025年3月推出的面向智能体应用的统一接口。核心创新：在多轮对话中保留推理状态（不同于会丢弃状态的Chat Completions），在TAUBench上使多轮对话性能提升约5%。

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

如需完整对比和决策指南，请查看
references/responses-vs-chat-completions.md
。

Top 3 Critical Rules

三大关键规则

Always Do ✅

务必遵循 ✅

Store conversation_id - Preserve state between turns (most critical)
Use environment variables for API keys (NEVER hardcode)
Handle polymorphic outputs - Check
```
output.type
```
(message, reasoning, function_call)

存储conversation_id - 保留多轮对话间的状态（最关键）
使用环境变量存储API密钥（绝对不要硬编码）
处理多态输出 - 检查
```
output.type
```
（message、reasoning、function_call）

Never Do ❌

绝对禁止 ❌

Never ignore conversation_id - State will be lost
Never assume single output type - Always check
```
output.type
```
Never mix Chat Completions and Responses in same conversation

Load
references/setup-guide.md
for complete rules and best practices.

绝对不要忽略conversation_id - 否则会丢失状态
绝对不要假设单一输出类型 - 务必检查
```
output.type
```
绝对不要在同一对话中混用Chat Completions和Responses

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

Top 5 Use Cases

五大核心使用场景

Use Case 1: Stateful Conversation

场景1：有状态对话

typescript

// 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."

Load:

references/stateful-conversations.md

templates/stateful-conversation.ts

typescript

// 第一轮对话
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'My favorite color is blue.',
});

const conversationId = response1.conversation_id;

// 第二轮对话 - 模型会记忆之前的内容
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: conversationId,
  input: 'What is my favorite color?',
});
// 输出："Your favorite color is blue."

查看：

references/stateful-conversations.md

templates/stateful-conversation.ts

Use Case 2: Web Search Agent

场景2：网页搜索智能体

typescript

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

Load:

references/built-in-tools-guide.md

templates/web-search.ts

typescript

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

Use Case 3: Code Interpreter

场景3：代码解释器

typescript

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

Load:

references/built-in-tools-guide.md

templates/code-interpreter.ts

typescript

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

Use Case 4: File Search (RAG)

场景4：文件搜索（RAG）

typescript

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

Load:

references/built-in-tools-guide.md

templates/file-search.ts

typescript

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

// 搜索文件内容
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

Use Case 5: MCP Server Integration

场景5：MCP服务器集成

typescript

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

Load:

references/mcp-integration-guide.md

templates/mcp-integration.ts

typescript

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

Built-in Tools

内置工具

All tools run server-side: Code Interpreter (Python execution), File Search (RAG), Web Search (real-time), Image Generation (DALL-E).

Enable explicitly:

typescript

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

Load
references/built-in-tools-guide.md
for complete guide with examples and configuration options.

所有工具均在服务器端运行：Code Interpreter（Python执行）、File Search（RAG）、Web Search（实时搜索）、Image Generation（DALL-E）。

需显式启用：

typescript

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
。

Stateful Conversations

有状态对话

Automatic state management with conversation IDs eliminates manual message tracking, preserves reasoning, and improves cache utilization by 40-80%.

typescript

// 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?',
});

Load
references/stateful-conversations.md
for persistence patterns (Node.js/Redis/KV) and lifecycle management.

通过对话ID实现自动状态管理，无需手动跟踪消息，保留推理逻辑，缓存利用率提升40-80%。

typescript

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

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

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

Migration from Chat Completions

从Chat Completions迁移

Quick changes:

messages

→

input

system

role →

developer

choices[0].message.content

→

output_text

/v1/chat/completions

→

/v1/responses

Before (Chat Completions):

typescript

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

After (Responses API):

typescript

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

Load
references/migration-guide.md
for complete migration checklist with tool migration patterns.

快速修改点：

messages

→

input

、

system

角色 →

developer

、

choices[0].message.content

→

output_text

、

/v1/chat/completions

→

/v1/responses

。

迁移前（Chat Completions）：

typescript

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

迁移后（Responses API）：

typescript

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, // 自动维护状态
  input: 'Follow-up question',
});

如需完整迁移清单及工具迁移模式，请查看
references/migration-guide.md
。

Polymorphic Outputs

多态输出

Responses can return multiple output types (message, reasoning, function_call, image). Handle each type or use

output_text

convenience property.

typescript

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

Load
references/reasoning-preservation.md
for reasoning output details and debugging patterns.

Responses可返回多种输出类型（message、reasoning、function_call、image）。需处理每种类型，或使用

output_text

便捷属性。

typescript

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

// 或使用便捷属性
console.log(response.output_text);

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

Background Mode

后台模式

For long-running tasks (>60 seconds), use

background: true

to run asynchronously and poll for completion.

typescript

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

Load
templates/background-mode.ts
for complete polling pattern with exponential backoff.

对于运行时间超过60秒的任务，使用

background: true

以异步方式运行并轮询结果。

typescript

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

// 轮询完成状态
const completed = await openai.responses.retrieve(response.id);

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

Top 3 Errors & Solutions

三大常见错误及解决方案

Error 1: Session State Not Persisting

错误1：会话状态未持久化

Symptom: Model doesn't remember previous turns.

Cause: Not using conversation IDs or creating new conversation each time.

Solution:

typescript

// ✅ 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',
});

症状：模型无法记住之前的对话内容。

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

解决方案：

typescript

// ✅ 正确做法：复用对话ID
const conv = await openai.conversations.create();
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // 同一ID
  input: 'Question 1',
});
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // 同一ID - 会记住之前的内容
  input: 'Question 2',
});

Error 2: MCP Server Connection Failed

错误2：MCP服务器连接失败

Cause: Invalid server URL, missing/expired authorization token.

Solution:

typescript

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

Prevention: Use environment variables for secrets, implement token refresh logic, add retry with exponential backoff.

原因：服务器URL无效、授权令牌缺失/过期。

解决方案：

typescript

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

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

Error 3: Code Interpreter Timeout

错误3：代码解释器超时

Cause: Code runs longer than 30 seconds (standard mode limit).

Solution:

typescript

// ✅ 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);
}

Load
references/top-errors.md
for all 8 errors with detailed solutions and prevention strategies.

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

解决方案：

typescript

// ✅ 正确做法：对长任务使用后台模式
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Process this massive dataset',
  background: true, // ✅ 最长支持10分钟
  tools: [{ type: 'code_interpreter' }],
});

// 轮询结果
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);
}

如需包含8种常见错误的详细解决方案和预防策略，请查看
references/top-errors.md
。

When to Load References

何时查看参考文档

Load

references/setup-guide.md

when:

当以下情况时查看

references/setup-guide.md

：

First-time Responses API user needing complete Node.js or Cloudflare Workers setup
Want production deployment checklist with environment-specific best practices
Troubleshooting setup issues or implementing streaming/background patterns

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

Load

references/responses-vs-chat-completions.md

when:

当以下情况时查看

references/responses-vs-chat-completions.md

：

Deciding between Responses and Chat Completions APIs
Understanding performance benchmarks (TAUBench results, cache utilization)
Evaluating migration effort or comparing cost structures

正在决定使用Responses还是Chat Completions API
了解性能基准（TAUBench结果、缓存利用率）
评估迁移工作量或比较成本结构

Load

references/migration-guide.md

when:

当以下情况时查看

references/migration-guide.md

：

Migrating from Chat Completions API with step-by-step checklist
Need code comparison examples (before/after patterns)
Migrating tools from custom functions to built-in/MCP

从Chat Completions API迁移，需要分步清单
需要代码对比示例（迁移前后模式）
将自定义工具迁移至内置/MCP工具

Load

references/built-in-tools-guide.md

when:

当以下情况时查看

references/built-in-tools-guide.md

：

Using Code Interpreter, File Search, Web Search, or Image Generation
Need tool configuration options, combining multiple tools, or troubleshooting

使用Code Interpreter、File Search、Web Search或Image Generation
需要工具配置选项、多工具组合使用方法或排查问题

Load

references/mcp-integration-guide.md

when:

当以下情况时查看

references/mcp-integration-guide.md

：

Integrating external MCP servers or building custom MCP tools
Need MCP configuration examples or authentication patterns

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

Load

references/stateful-conversations.md

when:

当以下情况时查看

references/stateful-conversations.md

：

Implementing conversation persistence with KV/Redis/database
Need conversation lifecycle management or metadata tracking patterns

实现基于KV/Redis/数据库的对话持久化
需要对话生命周期管理或元数据跟踪模式

Load

references/reasoning-preservation.md

when:

当以下情况时查看

references/reasoning-preservation.md

：

Want to access model reasoning for debugging or transparency
Building auditable AI systems or need reasoning output examples

需要访问模型推理逻辑用于调试或透明化
构建可审计的AI系统或需要推理输出示例

Load

references/top-errors.md

when:

当以下情况时查看

references/top-errors.md

：

Encountering API errors (8 common errors covered with solutions)
Need error code reference, prevention strategies, or error handling patterns

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

Production Checklist

生产环境检查清单

Before deploying:

API key stored securely (environment variable or secret)
Error handling implemented (401, 429, 400, 500)
Rate limiting handled (exponential backoff)
Conversation IDs persisted (database/KV)
Streaming enabled for long responses
Tools enabled explicitly
Polymorphic output handling

Load
references/setup-guide.md
for complete production checklist with platform-specific considerations.

部署前需完成：

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

如需包含平台特定注意事项的完整生产检查清单，请查看
references/setup-guide.md
。

Related Skills

Official Documentation

官方文档

Responses API: https://platform.openai.com/docs/api-reference/responses
Migration Guide: https://platform.openai.com/docs/guides/responses-migration
Built-in Tools: https://platform.openai.com/docs/guides/responses-tools
MCP Integration: https://platform.openai.com/docs/guides/mcp

Questions? Issues?

Check
```
references/top-errors.md
```
for error solutions
Review
```
references/setup-guide.md
```
for complete setup
See
```
references/migration-guide.md
```
for Chat Completions migration
Load templates from
```
templates/
```
for working examples

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

有疑问或问题？

查看
```
references/top-errors.md
```
获取错误解决方案
查看
```
references/setup-guide.md
```
获取完整设置指南
查看
```
references/migration-guide.md
```
获取Chat Completions迁移指南
从
```
templates/
```
获取可运行示例模板

openai-responses

Original

Translation

OpenAI Responses API

OpenAI Responses API

Quick Start (5 Minutes)

快速入门（5分钟）

Node.js

Node.js

Cloudflare Workers

Cloudflare Workers

What Is the Responses API?

什么是Responses API？

Top 3 Critical Rules

三大关键规则

Always Do ✅

务必遵循 ✅

Never Do ❌

绝对禁止 ❌

Top 5 Use Cases

五大核心使用场景

Use Case 1: Stateful Conversation

场景1：有状态对话

Use Case 2: Web Search Agent

场景2：网页搜索智能体

Use Case 3: Code Interpreter

场景3：代码解释器

Use Case 4: File Search (RAG)

场景4：文件搜索（RAG）

Use Case 5: MCP Server Integration

场景5：MCP服务器集成

Built-in Tools

内置工具

Stateful Conversations

有状态对话

Migration from Chat Completions

从Chat Completions迁移

Polymorphic Outputs

多态输出

Background Mode

后台模式

Top 3 Errors & Solutions

三大常见错误及解决方案

Error 1: Session State Not Persisting

错误1：会话状态未持久化

Error 2: MCP Server Connection Failed

错误2：MCP服务器连接失败

Error 3: Code Interpreter Timeout

错误3：代码解释器超时

When to Load References

何时查看参考文档

Load references/setup-guide.md when:

当以下情况时查看references/setup-guide.md：

Load references/responses-vs-chat-completions.md when:

当以下情况时查看references/responses-vs-chat-completions.md：

Load references/migration-guide.md when:

当以下情况时查看references/migration-guide.md：

Load references/built-in-tools-guide.md when:

当以下情况时查看references/built-in-tools-guide.md：

Load references/mcp-integration-guide.md when:

当以下情况时查看references/mcp-integration-guide.md：

Load references/stateful-conversations.md when:

当以下情况时查看references/stateful-conversations.md：

Load references/reasoning-preservation.md when:

当以下情况时查看references/reasoning-preservation.md：

Load references/top-errors.md when:

当以下情况时查看references/top-errors.md：

Production Checklist

生产环境检查清单

Related Skills

相关技能

Official Documentation

官方文档

Load
`references/setup-guide.md`
when:

当以下情况时查看
`references/setup-guide.md`
：

Load
`references/responses-vs-chat-completions.md`
when:

当以下情况时查看
`references/responses-vs-chat-completions.md`
：

Load
`references/migration-guide.md`
when:

当以下情况时查看
`references/migration-guide.md`
：

Load
`references/built-in-tools-guide.md`
when:

当以下情况时查看
`references/built-in-tools-guide.md`
：

Load
`references/mcp-integration-guide.md`
when:

当以下情况时查看
`references/mcp-integration-guide.md`
：

Load
`references/stateful-conversations.md`
when:

当以下情况时查看
`references/stateful-conversations.md`
：

Load
`references/reasoning-preservation.md`
when:

当以下情况时查看
`references/reasoning-preservation.md`
：

Load
`references/top-errors.md`
when:

当以下情况时查看
`references/top-errors.md`
：