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