MigrationGuide6 min

Migrate a chat-completions workflow to the Responses API

How to move an existing assistant-style workflow into a more flexible Responses API implementation without rewriting the product.

Open source doc

Real example

Example: migrate a support answer generator without changing the UI

A SaaS product has a support widget that sends chat-style messages to an older completion route. Users like the visible chat, but engineering needs better tool orchestration and structured answer metadata.

Keep the chat UI unchanged, but replace the server adapter. The adapter converts the visible conversation into a Responses API request, attaches retrieval/tool options, and returns the same UI message plus hidden metadata such as sources, tool calls, and confidence flags.

Users see the same product behavior, while the backend gains a cleaner path for tools, citations, moderation, and future model changes.

Adapter shape

type ChatMessage = { role: "user" | "assistant"; content: string };

function toResponsesInput(messages: ChatMessage[]) {
  return messages.map((message) => ({
    role: message.role,
    content: message.content,
  }));
}

Tutorial path

How to implement it

Step 01

Inventory the existing messages, system instructions, function calls, streaming behavior, and stored outputs.

Step 02

Map the current prompt and messages into a Responses API request that preserves the same user-visible behavior.

Step 03

Move function definitions into explicit tools and keep tool execution on the server.

Step 04

Compare old and new outputs with representative examples before switching production traffic.

Step 05

Retire dead prompt branches after the new path has enough logged review data.

Checklist

Ready when these are true

Side-by-side fixture tests

Rollback flag or route split

Tool call parity check

Streaming behavior verified

No client-side secret exposure

Field notes

What matters in practice

Keep the existing business contract stable while changing the API boundary.

Migrate one workflow at a time so prompts, tools, and UI behavior remain testable.

Use the migration as a chance to separate conversation display from backend execution state.

Avoid these mistakes

Common failure modes

Do not migrate every prompt at once.

Do not mix UI message history with backend execution state.

Do not skip side-by-side fixtures for your top support intents.

Practical tip

Use the migration to introduce a clean server adapter. The UI should not care which OpenAI API shape is behind it.

Apply this to a build