gh-jezweb-claude-skills-skills-openai-responses/references/migration-guide.md

Migration Guide: Chat Completions → Responses API

Last Updated: 2025-10-25

Quick guide for migrating from Chat Completions to Responses API.

---

Breaking Changes Summary

Chat Completions	Responses API	Migration
Endpoint	/v1/chat/completions	/v1/responses
Parameter	messages	input
Role	system	developer
Output	choices[0].message.content	output_text
State	Manual (messages array)	Automatic (conversation ID)
Tools	tools array with functions	Built-in types + MCP

---

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