Openai Responses

OpenAI Responses API

Status: Production Ready Last Updated: 2025-10-25 API Launch: March 2025 Dependencies: openai@5.19.1+ (Node.js) or fetch API (Cloudflare Workers)

---

What Is the Responses API?

The Responses API (/v1/responses) is OpenAI's unified interface for building agentic applications, launched in March 2025. It fundamentally changes how you interact with OpenAI models by providing stateful conversations and a structured loop for reasoning and acting.

Key Innovation: Preserved Reasoning State

Unlike Chat Completions where reasoning is discarded between turns, Responses keeps the notebook open. The model's step-by-step thought processes survive into the next turn, improving performance by approximately 5% on TAUBench and enabling better multi-turn interactions.

Why Use Responses Over Chat Completions?

---

Quick Start (5 Minutes)

1. Get API Key

# Sign up at https://platform.openai.com/
# Navigate to API Keys section
# Create new key and save securely
export OPENAI_API_KEY="sk-proj-..."

Why this matters:

• API key required for all requests
• Keep secure (never commit to git)
• Use environment variables

2. Install SDK (Node.js)

npm install openai

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

CRITICAL:

• Always use server-side (never expose API key in client code)
• Model defaults to gpt-5 (can use gpt-5-mini, gpt-4o, etc.)
• input can be string or array of messages

3. Or Use Direct API (Cloudflare Workers)

// No SDK needed - use fetch()
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);

Why fetch?

• No dependencies in edge environments
• Full control over request/response
• Works in Cloudflare Workers, Deno, Bun

---

Responses vs Chat Completions: Complete Comparison

When to Use Each

Use Responses API when:

• ✅ Building agentic applications (reasoning + actions)
• ✅ Need preserved reasoning state across turns
• ✅ Want built-in tools (Code Interpreter, File Search, Web Search)
• ✅ Using MCP servers for external integrations
• ✅ Implementing conversational AI with automatic state management
• ✅ Background processing for long-running tasks
• ✅ Need polymorphic outputs (messages, reasoning, tool calls)

Use Chat Completions when:

• ✅ Simple one-off text generation
• ✅ Fully stateless interactions (no conversation continuity needed)
• ✅ Legacy integrations (existing Chat Completions code)
• ✅ Very simple use cases without tools

Architecture Differences

Chat Completions Flow:

User Input → Model → Single Message → Done
(Reasoning discarded, state lost)

Responses API Flow:

User Input → Model (preserved reasoning) → Polymorphic Outputs
            ↓ (server-side tools)
    Tool Call → Tool Result → Model → Final Response
(Reasoning preserved, state maintained)

Performance Benefits

Cache Utilization:

• Chat Completions: Baseline performance
• Responses API: 40-80% better cache utilization
• Result: Lower latency + reduced costs

Reasoning Performance:

• Chat Completions: Reasoning dropped between turns
• Responses API: Reasoning preserved across turns
• Result: 5% better on TAUBench (GPT-5 with Responses vs Chat Completions)

---

Stateful Conversations

Automatic State Management

The Responses API can automatically manage conversation state using conversation IDs.

Creating a Conversation

// Create conversation with initial message
const conversation = await openai.conversations.create({
  metadata: { user_id: 'user_123' },
  items: [
    {
      type: 'message',
      role: 'user',
      content: 'Hello!',
    },
  ],
});

console.log(conversation.id); // "conv_abc123..."

Using Conversation ID

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

console.log(response1.output_text);

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

console.log(response2.output_text);
// Model automatically knows "first one" refers to first D from previous turn

Why this matters:

• No manual history tracking required
• Reasoning state preserved between turns
• Automatic context management
• Lower risk of context errors

Manual State Management (Alternative)

If you need full control, you can manually manage history:

let history = [
  { role: 'user', content: 'Tell me a joke' },
];

const response = await openai.responses.create({
  model: 'gpt-5',
  input: history,
  store: true, // Optional: store for retrieval later
});

// Add response to history
history = [
  ...history,
  ...response.output.map(el => ({
    role: el.role,
    content: el.content,
  })),
];

// Next turn
history.push({ role: 'user', content: 'Tell me another' });

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

When to use manual management:

• Need custom history pruning logic
• Want to modify conversation history programmatically
• Implementing custom caching strategies

---

Built-in Tools (Server-Side)

The Responses API includes server-side hosted tools that eliminate costly backend round trips.

Available Tools

Code Interpreter

Execute Python code server-side for data analysis, calculations, and visualizations.

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

console.log(response.output_text);
// Model writes and executes Python code, returns results

Advanced Example: Data Analysis

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze this sales data and create a bar chart showing monthly revenue: [data here]',
  tools: [{ type: 'code_interpreter' }],
});

// Check output for code execution results
response.output.forEach(item => {
  if (item.type === 'code_interpreter_call') {
    console.log('Code executed:', item.input);
    console.log('Result:', item.output);
  }
});

Why this matters:

• No need to run Python locally
• Sandboxed execution environment
• Automatic chart generation
• Can process uploaded files

File Search (RAG Without Vector Stores)

Search through uploaded files without building your own RAG pipeline.

// 1. Upload files first (one-time setup)
const file = await openai.files.create({
  file: fs.createReadStream('knowledge-base.pdf'),
  purpose: 'assistants',
});

// 2. Use file search
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What does the document say about pricing?',
  tools: [
    {
      type: 'file_search',
      file_ids: [file.id],
    },
  ],
});

console.log(response.output_text);
// Model searches file and provides answer with citations

Supported File Types:

• PDFs, Word docs, text files
• Markdown, HTML
• Code files (Python, JavaScript, etc.)
• Max: 512MB per file

Web Search

Get real-time information from the web.

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What are the latest updates on GPT-5?',
  tools: [{ type: 'web_search' }],
});

console.log(response.output_text);
// Model searches web and provides current information with sources

Why this matters:

• No cutoff date limitations
• Automatic source citations
• Real-time data access
• No need for external search APIs

Image Generation (DALL-E)

Generate images directly in the Responses API.

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Create an image of a futuristic cityscape at sunset',
  tools: [{ type: 'image_generation' }],
});

// Find image in output
response.output.forEach(item => {
  if (item.type === 'image_generation_call') {
    console.log('Image URL:', item.output.url);
  }
});

Models Available:

• DALL-E 3 (default)
• Various sizes and quality options

---

MCP Server Integration

The Responses API has built-in support for Model Context Protocol (MCP) servers, allowing you to connect external tools.

What Is MCP?

MCP is an open protocol that standardizes how applications provide context to LLMs. It allows you to:

• Connect to external APIs (Stripe, databases, CRMs)
• Use hosted MCP servers
• Build custom tool integrations

Basic MCP Integration

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

// Model discovers available tools on MCP server and uses them
console.log(response.output_text);

MCP with Authentication (OAuth)

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Create a $20 payment link',
  tools: [
    {
      type: 'mcp',
      server_label: 'stripe',
      server_url: 'https://mcp.stripe.com',
      authorization: process.env.STRIPE_OAUTH_TOKEN,
    },
  ],
});

console.log(response.output_text);
// Model uses Stripe MCP server to create payment link

CRITICAL:

• API does NOT store authorization tokens
• Must provide token with each request
• Use environment variables for security

Polymorphic Output: MCP Tool Calls

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Roll 2d4+1',
  tools: [
    {
      type: 'mcp',
      server_label: 'dice',
      server_url: 'https://dmcp.example.com',
    },
  ],
});

// Inspect tool calls
response.output.forEach(item => {
  if (item.type === 'mcp_call') {
    console.log('Tool:', item.name);
    console.log('Arguments:', item.arguments);
    console.log('Output:', item.output);
  }
  if (item.type === 'mcp_list_tools') {
    console.log('Available tools:', item.tools);
  }
});

Output Types:

• mcp_list_tools - Tools discovered on server
• mcp_call - Tool invocation and result
• message - Final response to user

---

Reasoning Preservation

How It Works

The Responses API preserves the model's internal reasoning state across turns, unlike Chat Completions which discards it.

Visual Analogy:

• Chat Completions: Model has a scratchpad, writes reasoning, then tears out the page before responding
• Responses API: Model keeps the scratchpad open, previous reasoning visible for next turn

Performance Impact

TAUBench Results (GPT-5):

• Chat Completions: Baseline score
• Responses API: +5% better (purely from preserved reasoning)

Why This Matters:

• Better multi-turn problem solving
• More coherent long conversations
• Improved step-by-step reasoning
• Fewer context errors

Reasoning Summaries (Free!)

The Responses API provides reasoning summaries at no additional cost.

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Solve this complex math problem: [problem]',
});

// Inspect reasoning
response.output.forEach(item => {
  if (item.type === 'reasoning') {
    console.log('Model reasoning:', item.summary[0].text);
  }
  if (item.type === 'message') {
    console.log('Final answer:', item.content[0].text);
  }
});

Use Cases:

• Debugging model decisions
• Audit trails for compliance
• Understanding model thought process
• Building transparent AI systems

---

Background Mode (Long-Running Tasks)

For tasks that take longer than standard timeout limits, use background mode.

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

// Returns immediately with status
console.log(response.status); // "in_progress"
console.log(response.id); // Use to check status later

// Poll for completion
const checkStatus = async (responseId) => {
  const result = await openai.responses.retrieve(responseId);
  if (result.status === 'completed') {
    console.log(result.output_text);
  } else if (result.status === 'failed') {
    console.error('Task failed:', result.error);
  } else {
    // Still running, check again later
    setTimeout(() => checkStatus(responseId), 5000);
  }
};

checkStatus(response.id);

When to Use:

• Large file processing
• Complex calculations
• Multi-step research tasks
• Data analysis on large datasets

Timeout Limits:

• Standard mode: 60 seconds
• Background mode: Up to 10 minutes

---

Polymorphic Outputs

The Responses API returns multiple output types instead of a single message.

Output Types

Processing Polymorphic Outputs

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

// Process different output types
response.output.forEach(item => {
  switch (item.type) {
    case 'reasoning':
      console.log('Reasoning:', item.summary[0].text);
      break;
    case 'web_search_call':
      console.log('Searched:', item.query);
      console.log('Sources:', item.results);
      break;
    case 'message':
      console.log('Response:', item.content[0].text);
      break;
  }
});

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

Why This Matters:

• Better debugging (see all steps)
• Audit trails (track all tool calls)
• Richer UX (show progress to users)
• Compliance (log all actions)

---

Migration from Chat Completions

Breaking Changes

Migration Example

Before (Chat Completions):

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 (Responses):

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

Key Differences: 1. chat.completions.create → responses.create 2. messages → input 3. system role → developer role 4. choices[0].message.content → output_text

When to Migrate

Migrate now if:

• ✅ Building new applications
• ✅ Need stateful conversations
• ✅ Using agentic patterns (reasoning + tools)
• ✅ Want better performance (preserved reasoning)

Stay on Chat Completions if:

• ✅ Simple one-off generations
• ✅ Legacy integrations
• ✅ No need for state management

---

Error Handling

Common Errors and Solutions

1. Session State Not Persisting

Error:

Conversation state not maintained between turns

Cause:

• Not using conversation IDs
• Using different conversation IDs per turn

Solution:

// Create conversation once
const conv = await openai.conversations.create();

// Reuse conversation ID for all turns
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // ✅ Same ID
  input: 'First message',
});

const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // ✅ Same ID
  input: 'Follow-up message',
});

2. MCP Server Connection Failed

Error:

{
  "error": {
    "type": "mcp_connection_error",
    "message": "Failed to connect to MCP server"
  }
}

Causes:

• Invalid server URL
• Missing or expired authorization token
• Server not responding

Solutions:

// 1. Verify URL is correct
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Test MCP',
  tools: [
    {
      type: 'mcp',
      server_label: 'test',
      server_url: 'https://api.example.com/mcp', // ✅ Full URL
      authorization: process.env.AUTH_TOKEN, // ✅ Valid token
    },
  ],
});

// 2. Test server URL manually
const testResponse = await fetch('https://api.example.com/mcp');
console.log(testResponse.status); // Should be 200

// 3. Check token expiration
console.log('Token expires:', parseJWT(token).exp);

3. Code Interpreter Timeout

Error:

{
  "error": {
    "type": "code_interpreter_timeout",
    "message": "Code execution exceeded time limit"
  }
}

Cause:

• Code runs longer than 30 seconds

Solution:

// Use background mode for long-running code
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Process this large dataset',
  background: true, // ✅ Extended timeout
  tools: [{ type: 'code_interpreter' }],
});

// Poll for results
const result = await openai.responses.retrieve(response.id);

4. Image Generation Rate Limit

Error:

{
  "error": {
    "type": "rate_limit_error",
    "message": "DALL-E rate limit exceeded"
  }
}

Cause:

• Too many image generation requests

Solution:

// Implement retry with exponential backoff
const generateImage = async (prompt, retries = 3) => {
  try {
    return await openai.responses.create({
      model: 'gpt-5',
      input: prompt,
      tools: [{ type: 'image_generation' }],
    });
  } catch (error) {
    if (error.type === 'rate_limit_error' && retries > 0) {
      const delay = (4 - retries) * 1000; // 1s, 2s, 3s
      await new Promise(resolve => setTimeout(resolve, delay));
      return generateImage(prompt, retries - 1);
    }
    throw error;
  }
};

5. File Search Relevance Issues

Problem:

• File search returns irrelevant results

Solution:

// Use more specific queries
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Find sections about pricing in Q4 2024 specifically', // ✅ Specific
  // NOT: 'Find pricing' (too vague)
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// Or filter results manually
response.output.forEach(item => {
  if (item.type === 'file_search_call') {
    const relevantChunks = item.results.filter(
      chunk => chunk.score > 0.7 // ✅ Only high-confidence matches
    );
  }
});

6. Cost Tracking Confusion

Problem:

• Billing different than expected

Explanation:

• Responses API bills for: input tokens + output tokens + tool usage + stored conversations
• Chat Completions bills only: input tokens + output tokens

Solution:

// Monitor usage
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
  store: false, // ✅ Don't store if not needed
});

console.log('Usage:', response.usage);
// {
//   prompt_tokens: 10,
//   completion_tokens: 20,
//   tool_tokens: 5,
//   total_tokens: 35
// }

7. Conversation Not Found

Error:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Conversation conv_xyz not found"
  }
}

Causes:

• Conversation ID typo
• Conversation deleted
• Conversation expired (90 days)

Solution:

// Verify conversation exists before using
const conversations = await openai.conversations.list();
const exists = conversations.data.some(c => c.id === 'conv_xyz');

if (!exists) {
  // Create new conversation
  const newConv = await openai.conversations.create();
  // Use newConv.id
}

8. Tool Output Parsing Failed

Problem:

• Can't access tool outputs correctly

Solution:

// Use helper methods
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search for AI news',
  tools: [{ type: 'web_search' }],
});

// Helper: Get text-only output
console.log(response.output_text);

// Manual: Inspect all outputs
response.output.forEach(item => {
  console.log('Type:', item.type);
  console.log('Content:', item);
});

---

Production Patterns

Cost Optimization

1. Use Conversation IDs (Cache Benefits)

// ✅ GOOD: Reuse conversation ID
const conv = await openai.conversations.create();
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'Question 1',
});
// 40-80% better cache utilization

// ❌ BAD: New manual history each time
const response2 = await openai.responses.create({
  model: 'gpt-5',
  input: [...previousHistory, newMessage],
});
// No cache benefits

2. Disable Storage When Not Needed

// For one-off requests
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Quick question',
  store: false, // ✅ Don't store conversation
});

3. Use Smaller Models When Possible

// For simple tasks
const response = await openai.responses.create({
  model: 'gpt-5-mini', // ✅ 50% cheaper
  input: 'Summarize this paragraph',
});

Rate Limit Handling

const createResponseWithRetry = async (params, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await openai.responses.create(params);
    } catch (error) {
      if (error.type === 'rate_limit_error' && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        console.log(`Rate limited, retrying in ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Monitoring and Logging

const monitoredResponse = async (input) => {
  const startTime = Date.now();

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

    // Log success metrics
    console.log({
      status: 'success',
      latency: Date.now() - startTime,
      tokens: response.usage.total_tokens,
      model: response.model,
      conversation: response.conversation_id,
    });

    return response;
  } catch (error) {
    // Log error metrics
    console.error({
      status: 'error',
      latency: Date.now() - startTime,
      error: error.message,
      type: error.type,
    });
    throw error;
  }
};

---

Node.js vs Cloudflare Workers

Node.js Implementation

import OpenAI from 'openai';

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

export async function handleRequest(input: string) {
  const response = await openai.responses.create({
    model: 'gpt-5',
    input,
    tools: [{ type: 'web_search' }],
  });

  return response.output_text;
}

Pros:

• Full SDK support
• Type safety
• Streaming helpers

Cons:

• Requires Node.js runtime
• Larger bundle size

Cloudflare Workers Implementation

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { input } = await request.json();

    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,
        tools: [{ type: 'web_search' }],
      }),
    });

    const data = await response.json();

    return new Response(data.output_text, {
      headers: { 'Content-Type': 'text/plain' },
    });
  },
};

Pros:

• No dependencies
• Edge deployment
• Faster cold starts

Cons:

• Manual request building
• No type safety without custom types

---

Always Do / Never Do

✅ Always Do

1. Use conversation IDs for multi-turn interactions

   const conv = await openai.conversations.create();
   // Reuse conv.id for all related turns

2. Handle all output types in polymorphic responses

   response.output.forEach(item => {
     if (item.type === 'reasoning') { /* log */ }
     if (item.type === 'message') { /* display */ }
   });

3. Use background mode for long-running tasks

   const response = await openai.responses.create({
     background: true, // ✅ For tasks >30s
     ...
   });

4. Provide authorization tokens for MCP servers

   tools: [{
     type: 'mcp',
     authorization: process.env.TOKEN, // ✅ Required
   }]

5. Monitor token usage for cost control

   console.log(response.usage.total_tokens);

❌ Never Do

1. Never expose API keys in client-side code

   // ❌ DANGER: API key in browser
   const response = await fetch('https://api.openai.com/v1/responses', {
     headers: { 'Authorization': 'Bearer sk-proj-...' }
   });

2. Never assume single message output

   // ❌ BAD: Ignores reasoning, tool calls
   console.log(response.output[0].content);

   // ✅ GOOD: Use helper or check all types
   console.log(response.output_text);

3. Never reuse conversation IDs across users

   // ❌ DANGER: User A sees User B's conversation
   const sharedConv = 'conv_123';

4. Never ignore error types

   // ❌ BAD: Generic error handling
   try { ... } catch (e) { console.log('error'); }

   // ✅ GOOD: Type-specific handling
   catch (e) {
     if (e.type === 'rate_limit_error') { /* retry */ }
     if (e.type === 'mcp_connection_error') { /* alert */ }
   }

5. Never poll faster than 1 second for background tasks

   // ❌ BAD: Too frequent
   setInterval(() => checkStatus(), 100);

   // ✅ GOOD: Reasonable interval
   setInterval(() => checkStatus(), 5000);

---

References

Official Documentation

• Responses API Guide: https://platform.openai.com/docs/guides/responses
• API Reference: https://platform.openai.com/docs/api-reference/responses
• MCP Integration: https://platform.openai.com/docs/guides/tools-connectors-mcp
• Blog Post (Why Responses API): https://developers.openai.com/blog/responses-api/
• Starter App: https://github.com/openai/openai-responses-starter-app

Skill Resources

• templates/ - Working code examples
• references/responses-vs-chat-completions.md - Feature comparison
• references/mcp-integration-guide.md - MCP server setup
• references/built-in-tools-guide.md - Tool usage patterns
• references/stateful-conversations.md - Conversation management
• references/migration-guide.md - Chat Completions → Responses
• references/top-errors.md - Common errors and solutions

---

Next Steps

1. ✅ Read templates/basic-response.ts - Simple example 2. ✅ Try templates/stateful-conversation.ts - Multi-turn chat 3. ✅ Explore templates/mcp-integration.ts - External tools 4. ✅ Review references/top-errors.md - Avoid common pitfalls 5. ✅ Check references/migration-guide.md - If migrating from Chat Completions

Happy building with the Responses API! 🚀

openai-responses

OpenAI Responses API Skill for Claude Code CLI

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

---

What This Skill Does

This skill provides comprehensive knowledge for building applications with OpenAI's Responses API (/v1/responses), the unified stateful API that replaces Chat Completions for agentic workflows.

Key Capabilities

✅ Stateful conversations with automatic state management ✅ Preserved reasoning across turns (5% better performance) ✅ Built-in tools: Code Interpreter, File Search, Web Search, Image Generation ✅ MCP server integration for external tools (Stripe, databases, etc.) ✅ Polymorphic outputs: messages, reasoning summaries, tool calls ✅ Background mode for long-running tasks (up to 10 minutes) ✅ 40-80% better cache utilization vs Chat Completions ✅ Both Node.js SDK and Cloudflare Workers (fetch) support

---

Auto-Trigger Keywords

Primary Keywords

• responses api
• openai responses
• stateful openai
• openai mcp
• agentic workflows
• conversation state
• reasoning preservation

Built-in Tools

• code interpreter openai
• file search openai
• web search openai
• image generation openai

Technical Keywords

• gpt-5
• gpt-5-mini
• polymorphic outputs
• background mode openai
• conversation id

Migration Keywords

• chat completions migration
• responses vs chat completions
• migrate to responses api

Error Keywords

• responses api error
• mcp server failed
• session not found
• conversation not persisting
• code interpreter timeout
• file search not working

---

When to Use This Skill

✅ Use Responses API When:

• Building agentic applications (reasoning + actions)
• Need multi-turn conversations with automatic state management
• Using built-in tools (Code Interpreter, File Search, Web Search, Image Gen)
• Connecting to MCP servers for external integrations
• Want preserved reasoning for better multi-turn performance
• Implementing background processing for long tasks
• Need polymorphic outputs for debugging/auditing

❌ Don't Use Responses API When:

• Simple one-off text generation (use Chat Completions)
• Fully stateless interactions (no conversation continuity needed)
• Legacy integrations with existing Chat Completions code

---

Quick Example

import OpenAI from 'openai';

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

// Stateful conversation
const conv = await openai.conversations.create();

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

console.log(response1.output_text);

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

console.log(response2.output_text);
// Model automatically knows "first one" refers to first D

---

Token Efficiency

Why?

• New API (March 2025) - limited examples online
• Comprehensive error prevention (8 documented issues)
• Working templates for all major patterns
• Clear migration guide from Chat Completions

---

Known Issues Prevented

This skill prevents 8 common errors encountered with the Responses API:

---

Responses vs Chat Completions

---

What's Included

Templates (10 files)

• basic-response.ts - Simple text response
• stateful-conversation.ts - Multi-turn chat with state
• mcp-integration.ts - External MCP servers (Stripe example)
• code-interpreter.ts - Python code execution
• file-search.ts - RAG without vector stores
• web-search.ts - Real-time web information
• image-generation.ts - DALL-E integration
• background-mode.ts - Long-running tasks
• cloudflare-worker.ts - Fetch-based implementation
• package.json - Latest dependencies

References (7 files)

• responses-vs-chat-completions.md - Complete comparison
• mcp-integration-guide.md - MCP server setup
• built-in-tools-guide.md - Code Interpreter, File Search, Web Search, Image Gen
• stateful-conversations.md - Conversation management
• reasoning-preservation.md - How it works, benchmarks
• migration-guide.md - Breaking changes from Chat Completions
• top-errors.md - 8 common errors with solutions

Scripts

• check-versions.sh - Verify openai SDK version

---

Dependencies

Node.js

npm install openai

Latest Version: openai@5.19.1+ (supports Responses API) Minimum Version: openai@5.19.0 Node.js: 18+ required

Cloudflare Workers

No dependencies required - use native fetch API

---

Built-in Tools

Code Interpreter

Execute Python code server-side for data analysis, calculations, and visualizations.

tools: [{ type: 'code_interpreter' }]

File Search

RAG without building your own vector store - search uploaded files automatically.

tools: [{ type: 'file_search', file_ids: [fileId] }]

Web Search

Real-time web information with automatic source citations.

tools: [{ type: 'web_search' }]

Image Generation

DALL-E integration for image creation.

tools: [{ type: 'image_generation' }]

MCP Servers

Connect to external tools (Stripe, databases, custom APIs).

tools: [{
  type: 'mcp',
  server_label: 'stripe',
  server_url: 'https://mcp.stripe.com',
  authorization: process.env.STRIPE_OAUTH_TOKEN,
}]

---

MCP (Model Context Protocol)

MCP is an open protocol for connecting AI models to external tools. The Responses API has built-in MCP support.

Popular MCP Servers:

• Stripe (payments)
• Databases (PostgreSQL, MySQL, MongoDB)
• CRMs (Salesforce, HubSpot)
• Custom business tools

No Additional Cost:

• MCP tool calls are billed as output tokens
• No separate MCP server fees

---

Reasoning Preservation

Unlike Chat Completions (which discards reasoning between turns), Responses preserves the model's internal reasoning state.

Performance Impact:

• +5% better on TAUBench (GPT-5 with Responses vs Chat Completions)
• Better multi-turn problem solving
• More coherent long conversations
• Fewer context errors

Visual Analogy:

• Chat Completions: Model tears out scratchpad page after each turn
• Responses API: Model keeps scratchpad open, previous reasoning visible

---

Background Mode

For tasks that take longer than 60 seconds, use background mode for up to 10 minutes.

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

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

Use Cases:

• Large file processing
• Complex calculations
• Multi-step research tasks
• Data analysis on large datasets

---

Polymorphic Outputs

Responses return multiple output types instead of a single message:

response.output.forEach(item => {
  if (item.type === 'reasoning') {
    console.log('Model thinking:', item.summary);
  }
  if (item.type === 'message') {
    console.log('Response:', item.content);
  }
  if (item.type === 'mcp_call') {
    console.log('Tool used:', item.name, item.output);
  }
});

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

Output Types:

• message - Text response
• reasoning - Model's thought process (free!)
• code_interpreter_call - Python execution
• mcp_call - Tool invocation
• file_search_call - File search results
• web_search_call - Web search results
• image_generation_call - Image generation

---

Cost Optimization

Cache Benefits:

• 40-80% better cache utilization vs Chat Completions
• Lower latency + reduced costs
• Automatic when using conversation IDs

Tips:

// ✅ GOOD: Reuse conversation IDs for cache benefits
const conv = await openai.conversations.create();

// ❌ BAD: New manual history each time
const response = await openai.responses.create({
  input: [...previousHistory, newMessage],
});

---

Migration from Chat Completions

Breaking Changes

Migration Example

Before:

const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { 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 helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
});

console.log(response.output_text);

See references/migration-guide.md for complete details.

---

Production Validation

Based On:

• Official OpenAI documentation (platform.openai.com/docs)
• OpenAI blog post (developers.openai.com/blog/responses-api)
• Starter app (github.com/openai/openai-responses-starter-app)
• March 2025 API release

Tested With:

• openai SDK v5.19.1
• Node.js 18+
• Cloudflare Workers (fetch API)

---

Official Resources

• Responses API Guide: https://platform.openai.com/docs/guides/responses
• API Reference: https://platform.openai.com/docs/api-reference/responses
• MCP Integration: https://platform.openai.com/docs/guides/tools-connectors-mcp
• Blog Post: https://developers.openai.com/blog/responses-api/
• Starter App: https://github.com/openai/openai-responses-starter-app
• Cookbook: https://cookbook.openai.com/examples/mcp/

---

Next Steps

1. ✅ Read SKILL.md - Complete API reference 2. ✅ Try templates/basic-response.ts - Simple example 3. ✅ Explore templates/stateful-conversation.ts - Multi-turn chat 4. ✅ Test templates/mcp-integration.ts - External tools 5. ✅ Review references/top-errors.md - Avoid common pitfalls

---

Contributing

Found an error or have an improvement? Open an issue at: https://github.com/jezweb/claude-skills/issues

---

Last Updated: 2025-10-25 Maintainer: Jeremy Dawes | jeremy@jezweb.net License: MIT

Built-in Tools Guide

Last Updated: 2025-10-25

Comprehensive guide to using Responses API built-in tools.

---

Available Tools

---

Code Interpreter

Execute Python code server-side:

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

Features:

• Sandboxed Python environment
• Automatic chart generation
• File processing support
• Timeout: 30s (use background: true for longer)

---

File Search

RAG without building vector stores:

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

// 2. Search
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What does the document say about pricing?',
  tools: [{ type: 'file_search', file_ids: [file.id] }],
});

Supported formats:

• PDFs, Word docs, text files
• Markdown, HTML, code files
• Max: 512MB per file

---

Web Search

Real-time web information:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What are the latest AI news?',
  tools: [{ type: 'web_search' }],
});

Features:

• No cutoff date limitations
• Automatic source citations
• Real-time data access

---

Image Generation

DALL-E integration:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Create an image of a futuristic cityscape at sunset',
  tools: [{ type: 'image_generation' }],
});

// Find image in output
response.output.forEach(item => {
  if (item.type === 'image_generation_call') {
    console.log('Image URL:', item.output.url);
  }
});

Models: DALL-E 3 (default)

---

Combining Tools

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Find current Bitcoin price and calculate what $1000 would be worth',
  tools: [
    { type: 'web_search' },       // Get price
    { type: 'code_interpreter' }, // Calculate
  ],
});

Model automatically uses the right tool for each subtask.

---

Official Docs: https://platform.openai.com/docs/guides/responses

MCP Integration Guide

Last Updated: 2025-10-25

Guide for integrating external tools using Model Context Protocol (MCP).

---

What Is MCP?

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. It allows connecting external tools like Stripe, databases, and custom APIs.

Key Benefits:

• ✅ Built into Responses API (no separate setup)
• ✅ Automatic tool discovery
• ✅ OAuth authentication support
• ✅ No additional cost (billed as output tokens)

---

Basic MCP Integration

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Roll 2d6 dice',
  tools: [
    {
      type: 'mcp',
      server_label: 'dice',
      server_url: 'https://dmcp.example.com',
    },
  ],
});

---

Authentication

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Create payment link',
  tools: [
    {
      type: 'mcp',
      server_label: 'stripe',
      server_url: 'https://mcp.stripe.com',
      authorization: process.env.STRIPE_OAUTH_TOKEN, // ✅
    },
  ],
});

Important: API does NOT store tokens. Provide with each request.

---

Popular MCP Servers

• Stripe: https://mcp.stripe.com
• Database MCP: Custom servers for PostgreSQL, MySQL, MongoDB
• Custom APIs: Build your own MCP server

---

Building Custom MCP Server

MCP server must implement:

1. List Tools Endpoint

// POST /mcp/list_tools
{
  tools: [
    {
      name: 'get_weather',
      description: 'Get weather for a city',
      input_schema: {
        type: 'object',
        properties: {
          city: { type: 'string' },
        },
        required: ['city'],
      },
    },
  ],
}

2. Call Tool Endpoint

// POST /mcp/call_tool
Request: {
  name: 'get_weather',
  arguments: { city: 'San Francisco' }
}

Response: {
  result: {
    temperature: 72,
    condition: 'sunny',
  }
}

---

Error Handling

try {
  const response = await openai.responses.create({
    model: 'gpt-5',
    input: 'Use tool',
    tools: [{ type: 'mcp', server_url: '...', authorization: '...' }],
  });
} catch (error: any) {
  if (error.type === 'mcp_connection_error') {
    console.error('Server connection failed');
  }
  if (error.type === 'mcp_authentication_error') {
    console.error('Invalid token');
  }
}

---

Official MCP Docs: https://platform.openai.com/docs/guides/tools-connectors-mcp

Migration Guide: Chat Completions → Responses API

Last Updated: 2025-10-25

Quick guide for migrating from Chat Completions to Responses API.

---

Breaking Changes Summary

---

Step-by-Step Migration

Step 1: Update Endpoint

Before:

const response = await openai.chat.completions.create({...});

After:

const response = await openai.responses.create({...});

Step 2: Rename messages to input

Before:

{
  messages: [
    { role: 'system', content: '...' },
    { role: 'user', content: '...' }
  ]
}

After:

{
  input: [
    { role: 'developer', content: '...' },
    { role: 'user', content: '...' }
  ]
}

Step 3: Update Response Access

Before:

const text = response.choices[0].message.content;

After:

const text = response.output_text;

Step 4: Use Conversation IDs (Optional but Recommended)

Before (Manual History):

let messages = [...previousMessages, newMessage];
const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages,
});

After (Automatic):

const response = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // ✅ Automatic state
  input: newMessage,
});

---

Complete Example

Before (Chat Completions):

import OpenAI from 'openai';

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

let messages = [
  { role: 'system', content: 'You are a helpful assistant.' },
];

async function chat(userMessage: string) {
  messages.push({ role: 'user', content: userMessage });

  const response = await openai.chat.completions.create({
    model: 'gpt-5',
    messages,
  });

  const assistantMessage = response.choices[0].message;
  messages.push(assistantMessage);

  return assistantMessage.content;
}

// Usage
await chat('Hello');
await chat('Tell me a joke');

After (Responses):

import OpenAI from 'openai';

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

const conversation = await openai.conversations.create({
  items: [
    { type: 'message', role: 'developer', content: 'You are a helpful assistant.' },
  ],
});

async function chat(userMessage: string) {
  const response = await openai.responses.create({
    model: 'gpt-5',
    conversation: conversation.id,
    input: userMessage,
  });

  return response.output_text;
}

// Usage
await chat('Hello');
await chat('Tell me a joke'); // Remembers previous turn automatically

---

Tool Migration

Chat Completions Functions → Responses Built-in Tools

Before (Custom Function):

{
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get weather',
        parameters: { /* schema */ }
      }
    }
  ]
}

After (Built-in or MCP):

{
  tools: [
    { type: 'web_search' },        // Built-in
    { type: 'code_interpreter' },  // Built-in
    {
      type: 'mcp',                 // External tools
      server_label: 'weather',
      server_url: 'https://weather-mcp.example.com'
    }
  ]
}

---

Streaming Migration

Before:

const stream = await openai.chat.completions.create({
  model: 'gpt-5',
  messages,
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

After:

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

for await (const chunk of stream) {
  // Handle polymorphic outputs
  if (chunk.type === 'message_delta') {
    process.stdout.write(chunk.content || '');
  }
}

---

Testing Checklist

• [ ] Update all endpoint calls
• [ ] Rename messages to input
• [ ] Update system role to developer
• [ ] Update response access (choices[0] → output_text)
• [ ] Implement conversation management
• [ ] Update tool definitions
• [ ] Test multi-turn conversations
• [ ] Verify streaming works
• [ ] Check cost tracking (tool tokens)

---

Official Docs: https://platform.openai.com/docs/guides/responses

Reasoning Preservation Guide

Last Updated: 2025-10-25

Understanding how Responses API preserves reasoning across turns.

---

What Is Reasoning Preservation?

Unlike Chat Completions (which discards reasoning between turns), Responses preserves the model's internal thought process.

Analogy:

• Chat Completions: Model tears out scratchpad page after each turn
• Responses API: Model keeps scratchpad open, previous reasoning visible

---

Performance Impact

TAUBench Results (GPT-5):

• Chat Completions: Baseline
• Responses API: +5% better (purely from preserved reasoning)

Why It Matters:

• ✅ Better multi-turn problem solving
• ✅ More coherent long conversations
• ✅ Improved step-by-step reasoning
• ✅ Fewer context errors

---

Reasoning Summaries

Responses API provides reasoning summaries at no additional cost.

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Solve this complex math problem',
});

// Inspect reasoning
response.output.forEach(item => {
  if (item.type === 'reasoning') {
    console.log('Model thinking:', item.summary[0].text);
  }
  if (item.type === 'message') {
    console.log('Final answer:', item.content[0].text);
  }
});

---

Use Cases

Debugging:

• See how model arrived at answer
• Identify reasoning errors

Auditing:

• Track decision-making process
• Compliance requirements

Transparency:

• Show users why AI made decision
• Build trust in AI systems

---

Official Docs: https://developers.openai.com/blog/responses-api/

Responses API vs Chat Completions: Complete Comparison

Last Updated: 2025-10-25

This document provides a comprehensive comparison between the Responses API and Chat Completions API to help you choose the right one for your use case.

---

Quick Decision Guide

✅ Use Responses API When:

• Building agentic applications (reasoning + actions)
• Need multi-turn conversations with automatic state management
• Using built-in tools (Code Interpreter, File Search, Web Search, Image Gen)
• Connecting to MCP servers for external integrations
• Want preserved reasoning for better multi-turn performance
• Implementing background processing for long tasks
• Need polymorphic outputs for debugging/auditing

✅ Use Chat Completions When:

• Simple one-off text generation
• Fully stateless interactions (no conversation continuity needed)
• Legacy integrations with existing Chat Completions code
• Very simple use cases without tools

---

Feature Comparison Matrix

---

API Comparison

Endpoints

Chat Completions:

POST /v1/chat/completions

Responses:

POST /v1/responses

---

Request Structure

Chat Completions:

{
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
  temperature: 0.7,
  max_tokens: 1000,
}

Responses:

{
  model: 'gpt-5',
  input: [
    { role: 'developer', content: 'You are helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
  conversation: 'conv_abc123', // Optional: automatic state
  temperature: 0.7,
}

Key Differences:

• messages → input
• system role → developer role
• max_tokens not required in Responses
• conversation parameter for automatic state

---

Response Structure

Chat Completions:

{
  id: 'chatcmpl-123',
  object: 'chat.completion',
  created: 1677652288,
  model: 'gpt-5',
  choices: [
    {
      index: 0,
      message: {
        role: 'assistant',
        content: 'Hello! How can I help?',
      },
      finish_reason: 'stop',
    },
  ],
  usage: {
    prompt_tokens: 10,
    completion_tokens: 5,
    total_tokens: 15,
  },
}

Responses:

{
  id: 'resp_123',
  object: 'response',
  created: 1677652288,
  model: 'gpt-5',
  output: [
    {
      type: 'reasoning',
      summary: [{ type: 'summary_text', text: 'User greeting, respond friendly' }],
    },
    {
      type: 'message',
      role: 'assistant',
      content: [{ type: 'output_text', text: 'Hello! How can I help?' }],
    },
  ],
  output_text: 'Hello! How can I help?', // Helper field
  usage: {
    prompt_tokens: 10,
    completion_tokens: 5,
    tool_tokens: 0,
    total_tokens: 15,
  },
  conversation_id: 'conv_abc123', // If using conversation
}

Key Differences:

• Single message → Polymorphic output array
• choices[0].message.content → output_text helper
• Additional output types: reasoning, tool_calls, etc.
• conversation_id included if using conversations

---

State Management Comparison

Chat Completions (Manual)

// You track history manually
let messages = [
  { role: 'system', content: 'You are helpful.' },
  { role: 'user', content: 'What is AI?' },
];

const response1 = await openai.chat.completions.create({
  model: 'gpt-5',
  messages,
});

// Add response to history
messages.push({
  role: 'assistant',
  content: response1.choices[0].message.content,
});

// Next turn
messages.push({ role: 'user', content: 'Tell me more' });

const response2 = await openai.chat.completions.create({
  model: 'gpt-5',
  messages, // ✅ You must pass full history
});

Pros:

• Full control over history
• Can prune old messages
• Simple for one-off requests

Cons:

• Manual tracking error-prone
• Must handle history yourself
• No automatic caching benefits

Responses (Automatic)

// Create conversation once
const conv = await openai.conversations.create();

const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // ✅ Automatic state
  input: 'What is AI?',
});

// Next turn - no manual history tracking
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // ✅ Remembers previous turn
  input: 'Tell me more',
});

Pros:

• Automatic state management
• No manual history tracking
• Better cache utilization (40-80%)
• Reasoning preserved

Cons:

• Less direct control
• Must create conversation first
• Conversations expire after 90 days

---

Reasoning Preservation

Chat Completions

What Happens: 1. Model generates internal reasoning (scratchpad) 2. Reasoning used to produce response 3. Reasoning discarded before returning 4. Next turn starts fresh (no reasoning memory)

Visual:

Turn 1: [Reasoning] → Response → ❌ Reasoning deleted
Turn 2: [New Reasoning] → Response → ❌ Reasoning deleted
Turn 3: [New Reasoning] → Response → ❌ Reasoning deleted

Impact:

• Model "forgets" its thought process
• May repeat reasoning steps
• Lower performance on complex multi-turn tasks

Responses API

What Happens: 1. Model generates internal reasoning 2. Reasoning used to produce response 3. Reasoning preserved in conversation state 4. Next turn builds on previous reasoning

Visual:

Turn 1: [Reasoning A] → Response → ✅ Reasoning A saved
Turn 2: [Reasoning A + B] → Response → ✅ Reasoning A+B saved
Turn 3: [Reasoning A + B + C] → Response → ✅ All reasoning saved

Impact:

• Model remembers thought process
• No redundant reasoning
• +5% better on TAUBench (GPT-5)
• Better multi-turn problem solving

---

Tools Comparison

Chat Completions (Client-Side)

// 1. Define function
const response1 = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [{ role: 'user', content: 'What is the weather?' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get weather',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string' },
          },
        },
      },
    },
  ],
});

// 2. Check if tool called
const toolCall = response1.choices[0].message.tool_calls?.[0];

// 3. Execute tool on your server
const weatherData = await getWeather(toolCall.function.arguments);

// 4. Send result back
const response2 = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    ...messages,
    response1.choices[0].message,
    {
      role: 'tool',
      tool_call_id: toolCall.id,
      content: JSON.stringify(weatherData),
    },
  ],
});

Pros:

• Full control over tool execution
• Can use any custom tools

Cons:

• Manual round trips (latency)
• More complex code
• You handle tool execution

Responses (Server-Side Built-in)

// All in one request - tools executed server-side
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What is the weather and analyze the temperature trend?',
  tools: [
    { type: 'web_search' },       // Built-in
    { type: 'code_interpreter' }, // Built-in
  ],
});

// Tools executed automatically, results in output
console.log(response.output_text);

Pros:

• No round trips (lower latency)
• Simpler code
• Built-in tools (no setup)

Cons:

• Less control over execution
• Limited to built-in + MCP tools

---

Performance Benchmarks

TAUBench (GPT-5)

Cache Utilization

---

Cost Comparison

Pricing Structure

Chat Completions:

• Input tokens: $X per 1K
• Output tokens: $Y per 1K
• No storage costs

Responses:

• Input tokens: $X per 1K
• Output tokens: $Y per 1K
• Tool tokens: $Z per 1K (if tools used)
• Conversation storage: $0.01 per conversation per month

Example Cost Calculation

Scenario: 100 multi-turn conversations, 10 turns each, 1000 tokens per turn

Chat Completions:

Input: 100 convs × 10 turns × 500 tokens × $X = $A
Output: 100 convs × 10 turns × 500 tokens × $Y = $B
Total: $A + $B

Responses:

Input: 100 convs × 10 turns × 500 tokens × $X = $A
Output: 100 convs × 10 turns × 500 tokens × $Y = $B
Storage: 100 convs × $0.01 = $1
Cache savings: -30% on input (due to better caching)
Total: ($A × 0.7) + $B + $1 (usually cheaper!)

---

Migration Path

Simple Migration

Before (Chat Completions):

const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
});

console.log(response.choices[0].message.content);

After (Responses):

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

console.log(response.output_text);

Changes: 1. chat.completions.create → responses.create 2. messages → input 3. system → developer 4. choices[0].message.content → output_text

---

When to Migrate

✅ Migrate Now If:

• Building new applications
• Need stateful conversations
• Using agentic patterns (reasoning + tools)
• Want better performance (preserved reasoning)
• Need built-in tools (Code Interpreter, File Search, etc.)

⏸️ Stay on Chat Completions If:

• Simple one-off generations
• Legacy integrations (migration effort)
• No need for state management
• Very simple use cases

---

Summary

Responses API is the future of OpenAI's API for agentic applications. It provides:

• ✅ Better performance (+5% on TAUBench)
• ✅ Lower latency (40-80% better caching)
• ✅ Simpler code (automatic state management)
• ✅ More features (built-in tools, MCP, reasoning preservation)

Chat Completions is still great for:

• ✅ Simple one-off text generation
• ✅ Legacy integrations
• ✅ When you need maximum simplicity

Recommendation: Use Responses for new projects, especially agentic workflows. Chat Completions remains valid for simple use cases.

Stateful Conversations Guide

Last Updated: 2025-10-25

Guide to managing conversation state with the Responses API.

---

Automatic State Management

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

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

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

---

Conversation Management

Create:

const conv = await openai.conversations.create({
  metadata: { topic: 'support' },
  items: [
    { type: 'message', role: 'developer', content: 'You are helpful.' }
  ],
});

List:

const convs = await openai.conversations.list({ limit: 10 });

Delete:

await openai.conversations.delete(conv.id);

---

Benefits vs Manual History

---

Best Practices

1. Store conversation IDs: Database, session storage, cookies 2. Add metadata: Track user, topic, session type 3. Expire old conversations: Delete after 90 days or when done 4. One conversation per topic: Don't mix unrelated topics

---

Official Docs: https://platform.openai.com/docs/api-reference/conversations

Top 8 Errors with OpenAI Responses API

Last Updated: 2025-10-25

This document covers the most common errors encountered when using the Responses API and their solutions.

---

1. Session State Not Persisting

Error Symptom: Model doesn't remember previous conversation turns.

Causes:

• Not using conversation IDs
• Using different conversation IDs per turn
• Creating new conversation for each request

Solution:

// ❌ BAD: New conversation each time
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'Question 1',
});
const response2 = await openai.responses.create({
  model: 'gpt-5',
  input: 'Question 2', // Model doesn't remember question 1
});

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

Prevention:

• Create conversation once
• Store conversation ID (database, session, cookie)
• Reuse ID for all related turns

---

2. MCP Server Connection Failed

Error:

{
  "error": {
    "type": "mcp_connection_error",
    "message": "Failed to connect to MCP server"
  }
}

Causes:

• Invalid server URL
• Missing or expired authorization token
• Server not responding
• Network issues

Solutions:

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

// 2. Test server URL manually
const testResponse = await fetch('https://mcp.stripe.com');
console.log(testResponse.status); // Should be 200

// 3. Check token expiration
const tokenExpiry = parseJWT(token).exp;
if (Date.now() / 1000 > tokenExpiry) {
  console.error('Token expired, refresh it');
}

Prevention:

• Use environment variables for secrets
• Implement token refresh logic
• Add retry with exponential backoff
• Log connection attempts for debugging

---

3. Code Interpreter Timeout

Error:

{
  "error": {
    "type": "code_interpreter_timeout",
    "message": "Code execution exceeded time limit"
  }
}

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

Solution:

// ❌ BAD: Long-running code in standard mode
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Process this massive dataset',
  tools: [{ type: 'code_interpreter' }], // Timeout after 30s
});

// ✅ 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);
}
console.log(result.output_text);

Prevention:

• Use background: true for tasks > 30 seconds
• Break large tasks into smaller chunks
• Optimize code for performance

---

4. Image Generation Rate Limit

Error:

{
  "error": {
    "type": "rate_limit_error",
    "message": "DALL-E rate limit exceeded"
  }
}

Cause: Too many image generation requests in short time

Solution:

// Implement retry with exponential backoff
async function generateImageWithRetry(prompt: string, retries = 3): Promise<any> {
  for (let i = 0; i < retries; i++) {
    try {
      return await openai.responses.create({
        model: 'gpt-5',
        input: prompt,
        tools: [{ type: 'image_generation' }],
      });
    } catch (error: any) {
      if (error.type === 'rate_limit_error' && i < retries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        console.log(`Rate limited, retrying in ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

const response = await generateImageWithRetry('Create an image of a sunset');

Prevention:

• Implement rate limiting on your side
• Use exponential backoff for retries
• Queue image requests
• Monitor API usage

---

5. File Search Relevance Issues

Problem: File search returns irrelevant or low-quality results

Causes:

• Vague queries
• Poor file quality (OCR errors, formatting)
• Not enough context

Solutions:

// ❌ BAD: Vague query
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Find pricing', // Too vague
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// ✅ GOOD: Specific query
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Find the monthly subscription pricing for the premium plan in the 2025 pricing document',
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// ✅ ALSO GOOD: Filter low-confidence results
response.output.forEach(item => {
  if (item.type === 'file_search_call') {
    const highConfidence = item.results.filter(r => r.score > 0.7);
    console.log('High confidence results:', highConfidence);
  }
});

Prevention:

• Use specific, detailed queries
• Upload high-quality documents (PDFs, Markdown)
• Filter results by confidence score (> 0.7)
• Provide context in query

---

6. Variable Substitution Errors (Reusable Prompts)

Error: Variables not replaced in prompt templates

Cause: Incorrect variable syntax or missing values

Solution:

// ❌ BAD: Incorrect variable syntax
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello {username}', // Not supported directly
});

// ✅ GOOD: Use template literals
const username = 'Alice';
const response = await openai.responses.create({
  model: 'gpt-5',
  input: `Hello ${username}`, // ✅ JavaScript template literal
});

// ✅ ALSO GOOD: Build message dynamically
function buildPrompt(vars: Record<string, string>) {
  return `Hello ${vars.username}, your order ${vars.orderId} is ready.`;
}

const response = await openai.responses.create({
  model: 'gpt-5',
  input: buildPrompt({ username: 'Alice', orderId: '12345' }),
});

Prevention:

• Use JavaScript template literals
• Validate all variables before substitution
• Provide defaults for optional variables

---

7. Chat Completions Migration Breaking Changes

Errors:

• messages parameter not found
• choices is undefined
• system role not recognized

Cause: Using Chat Completions syntax with Responses API

Solution:

// ❌ BAD: Chat Completions syntax
const response = await openai.responses.create({
  model: 'gpt-5',
  messages: [{ role: 'system', content: 'You are helpful.' }], // Wrong
});
console.log(response.choices[0].message.content); // Wrong

// ✅ GOOD: Responses syntax
const response = await openai.responses.create({
  model: 'gpt-5',
  input: [{ role: 'developer', content: 'You are helpful.' }], // ✅
});
console.log(response.output_text); // ✅

Breaking Changes:

Prevention:

• Read migration guide: references/migration-guide.md
• Update all references systematically
• Test thoroughly after migration

---

8. Cost Tracking Confusion

Problem: Billing different than expected

Cause: Not accounting for tool tokens and conversation storage

Explanation:

• Chat Completions: input tokens + output tokens
• Responses API: input tokens + output tokens + tool tokens + conversation storage

Solution:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
  store: false, // ✅ Disable storage if not needed
  tools: [{ type: 'code_interpreter' }],
});

// Monitor usage
console.log('Input tokens:', response.usage.prompt_tokens);
console.log('Output tokens:', response.usage.completion_tokens);
console.log('Tool tokens:', response.usage.tool_tokens);
console.log('Total tokens:', response.usage.total_tokens);

// Calculate cost
const inputCost = response.usage.prompt_tokens * 0.00001; // Example rate
const outputCost = response.usage.completion_tokens * 0.00003;
const toolCost = response.usage.tool_tokens * 0.00002;
const totalCost = inputCost + outputCost + toolCost;
console.log('Estimated cost: $' + totalCost.toFixed(4));

Prevention:

• Monitor usage.tool_tokens in responses
• Set store: false for one-off requests
• Track conversation count (storage costs)
• Implement cost alerts

---

Common Error Response Formats

Authentication Error

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Rate Limit Error

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded",
    "retry_after": 5
  }
}

Invalid Request Error

{
  "error": {
    "type": "invalid_request_error",
    "message": "Conversation conv_xyz not found"
  }
}

Server Error

{
  "error": {
    "type": "server_error",
    "message": "Internal server error"
  }
}

---

General Error Handling Pattern

async function handleResponsesAPI(input: string) {
  try {
    const response = await openai.responses.create({
      model: 'gpt-5',
      input,
    });

    return response.output_text;
  } catch (error: any) {
    // Handle specific errors
    switch (error.type) {
      case 'rate_limit_error':
        console.error('Rate limited, retry after:', error.retry_after);
        break;
      case 'mcp_connection_error':
        console.error('MCP server failed:', error.message);
        break;
      case 'code_interpreter_timeout':
        console.error('Code execution timed out, use background mode');
        break;
      case 'authentication_error':
        console.error('Invalid API key');
        break;
      default:
        console.error('Unexpected error:', error.message);
    }

    throw error; // Re-throw or handle
  }
}

---

Prevention Checklist

• [ ] Use conversation IDs for multi-turn interactions
• [ ] Provide valid MCP server URLs and tokens
• [ ] Use background: true for tasks > 30 seconds
• [ ] Implement exponential backoff for rate limits
• [ ] Use specific queries for file search
• [ ] Use template literals for variable substitution
• [ ] Update Chat Completions syntax to Responses syntax
• [ ] Monitor usage.tool_tokens and conversation count

---

Getting Help

If you encounter an error not covered here:

1. Check official docs: https://platform.openai.com/docs/api-reference/responses 2. Search OpenAI Community: https://community.openai.com 3. Contact OpenAI Support: https://help.openai.com

---

Last Updated: 2025-10-25