How to Use the Responses API Migration Prompt to Move Off Chat Completions Without Surprises

Moving from Chat Completions to the OpenAI Responses API looks simple until you hit the details: the system message moves, tool definitions change shape, tool results go back in a new item type, and structured outputs move to a different field. The OpenAI Chat Completions to Responses API Migration Planner: messages to input Map, instructions Field, Function Tool Format Changes, Structured Output text.format, and State Choices prompt maps your real request code to the new API and plans a safe cutover.

What the prompt produces

1. A field map from your current request to the Responses API, with anything uncertain marked to confirm in the API reference.
2. A rewritten request using client.responses.create in your language.
3. A response handling map for text, tool calls, finish state, and usage.
4. A function tool conversion to the flattened format, plus the function_call_output loop with call_id.
5. A state decision between resending history and using previous_response_id with store.
6. A built in tools note if you plan to add web search or file search.
7. A shadow test plan that compares both APIs on real traffic.
8. A rollback switch behind a feature flag.

How to fill the inputs

SdkAndLanguage tells the prompt whether to write Python, Node, or raw HTTP.

CurrentRequest is the most important input. Paste a redacted version of your real call, including the model, messages, temperature, max tokens, tools, and response format. The more exact this is, the more useful the rewrite.

ResponseHandling describes how your code reads results today, for example choices[0].message.content, tool_calls, finish_reason, and usage fields. These all change, and this is where silent bugs hide.

ToolsInUse lists your function tools and whether you want built in tools later.

StateAndRetention matters more than people expect. If you resend history each time and have strict retention rules, you may want store set to false. If you want the API to keep conversation state, previous_response_id depends on stored responses. The prompt lays out the trade off.

CutoverRisk sets the size and length of the shadow test.

Reading the example output

The example is a Python support triage bot with one function tool and a strict JSON schema output.

• The system message becomes instructions, user messages go in input, and max_tokens becomes max_output_tokens.
• The tool definition is flattened so name, description, parameters, and strict sit at the top level, with additionalProperties set to false for strict mode.
• Tool calls are read from output items of type function_call, and results go back as function_call_output items with the matching call_id.
• Structured output moves to text.format with the same schema.
• Because legal asked for minimal stored data, the plan keeps resending history and sets store to false instead of chaining with previous_response_id.
• Usage fields are renamed in the logging code and flagged to confirm.

Tips for better results

• Write a small adapter in your code that returns the same shape your app expects. Then the rest of the app does not care which API answered.
• Compare tool call arguments, not just final text, in the shadow test. A tool mismatch is the most costly kind of regression.
• Log both APIs' token counts during the shadow period so you can see cost changes before you switch.
• Keep the model the same during migration. Change one thing at a time.

Mistakes to avoid

• Do not trust parameter names from memory, including this article. Confirm each one in the current API reference.
• Do not forget the call_id when returning tool results. Without it, the model cannot match results to calls.
• Do not turn on stored state by accident if your data policy says otherwise. Check the store setting.
• Do not delete the Chat Completions path the day you hit full traffic. Keep it for one release.

Who it is for

Backend and platform engineers who own LLM features, AI product teams planning a model or API upgrade, and consultants migrating client code.

A sensible cutover schedule

Start by writing the adapter and running unit tests with recorded responses. Then send a small share of production requests to both APIs and serve only the old result. Review differences daily. When the match rate meets your own bar and latency looks fine, serve the new result to a small share of users, then ramp. The feature flag means a rollback is a config change, not a deploy.

Related PromptDig links

Open the OpenAI Chat Completions to Responses API Migration Planner: messages to input Map, instructions Field, Function Tool Format Changes, Structured Output text.format, and State Choices prompt with your current request code. For more AI tools prompts, Browse more prompts. If you have a migration checklist that worked for your team, Share a prompt.