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 docReal workflow example
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.
Implementation approach
This guide is anchored in OpenAI Responses API guide. Use the official API behavior as the boundary, then design the surrounding product state so the feature can be reviewed, retried, and improved.
- Inventory the existing messages, system instructions, function calls, streaming behavior, and stored outputs.
- Map the current prompt and messages into a Responses API request that preserves the same user-visible behavior.
- Move function definitions into explicit tools and keep tool execution on the server.
- Compare old and new outputs with representative examples before switching production traffic.
- Retire dead prompt branches after the new path has enough logged review data.
Adapter shape
type ChatMessage = { role: "user" | "assistant"; content: string };
function toResponsesInput(messages: ChatMessage[]) {
return messages.map((message) => ({
role: message.role,
content: message.content,
}));
}
Field notes
- 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.
Mistakes to avoid
- 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.
Ready checklist
- Side-by-side fixture tests
- Rollback flag or route split
- Tool call parity check
- Streaming behavior verified
- No client-side secret exposure