Openai Responses

# OpenAI Responses API

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

---

## Quick Start (5 Minutes)

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

### 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.**

---

## What Is the 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.**

---

## Top 3 Critical Rules

### Always Do ✅

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

### Never Do ❌

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

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

---

## Top 5 Use Cases

### Use Case 1: Stateful Conversation

```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`

---

### Use Case 2: Web Search Agent

```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`

---

### Use Case 3: Code Interpreter

```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`

---

### Use Case 4: File Search (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`

---

### Use Case 5: MCP Server Integration

```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`

---

## 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.**

---

## 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.**

---

## Migration from 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.**

---

## 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.**

---

## 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.**

---

## Top 3 Errors & Solutions

### Error 1: Session State Not Persisting

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

---

### Error 2: MCP Server Connection Failed

**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.

---

### Error 3: Code Interpreter Timeout

**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.**

---

## When to Load References

### Load `references/setup-guide.md` when:
- 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

### Load `references/responses-vs-chat-completions.md` when:
- Deciding between Responses and Chat Completions APIs
- Understanding performance benchmarks (TAUBench results, cache utilization)
- Evaluating migration effort or comparing cost structures

### Load `references/migration-guide.md` when:
- 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

### Load `references/built-in-tools-guide.md` when:
- Using Code Interpreter, File Search, Web Search, or Image Generation
- Need tool configuration options, combining multiple tools, or troubleshooting

### Load `references/mcp-integration-guide.md` when:
- Integrating external MCP servers or building custom MCP tools
- Need MCP configuration examples or authentication patterns

### Load `references/stateful-conversations.md` when:
- Implementing conversation persistence with KV/Redis/database
- Need conversation lifecycle management or metadata tracking patterns

### Load `references/reasoning-preservation.md` when:
- Want to access model reasoning for debugging or transparency
- Building auditable AI systems or need reasoning output examples

### Load `references/top-errors.md` when:
- Encountering API errors (8 common errors covered with solutions)
- Need error code reference, prevention strategies, or error handling patterns

---

## 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.**

---

## Related Skills

- **openai-api** - Classic Chat Completions API
- **openai-agents** - OpenAI Agents SDK (wrapper for Responses)
- **claude-api** - Claude API for comparison
- **ai-sdk-core** - Vercel AI SDK (supports Responses)

---

## 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?**

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