Responses API移行をCodexに任せる前に決めること

3行まとめ

Endpoint

入口。

State

履歴。

Tools

呼出。

Tests

確認。

Responses API移行は、endpoint変更だけでなく状態とtoolの扱いを見ます。

• Responses API移行は、endpointの置換だけでなく、input/output、state、tool calling、structured output、streamingを分けて確認します。
• Codexには、全コードの一括置換ではなく、利用箇所のinventory、移行キュー、test、rollback条件を渡します。
• Chat Completionsを残すflowとResponsesへ移すflowを分けると、移行中の不具合やcost変化を追いやすくなります。

OpenAI APIの移行は、表面だけ見ると簡単に見えます。chat.completions.createをresponses.createへ変える。messagesをinputへ変える。返り値をoutput_textで読む。小さなサンプルなら、それで動くことがあります。

でも実務のintegrationは、そこまで単純ではありません。multi-turn conversation、function calling、structured output、streaming、logging、retry、usage計測、A/B test、moderation、customer data policyが絡みます。Codexに「Responses APIへ移行して」とだけ頼むと、動く場所だけ先に直り、運用上の境界が曖昧になります。

この記事では、2026年6月1日時点のOpenAI公式API docsとCodex use casesをもとに、Responses API移行をCodexへ任せる前の整理を扱います。model選択そのものは、公開済み記事のCodexでGPT-5.3/5.2/5.1を選ぶ前に決めることで扱っています。ここでは、API integrationの移行手順に絞ります。

この記事でわかること

Inventory

棚卸し。

Queue

順序。

Gate

判定。

Rollback

戻し。

移行作業を、調査、修正、検証、公開判断へ分けます。

• Chat CompletionsからResponses APIへ移す前の棚卸し
• endpoint、input、outputの差分を小さく直す方法
• statefulness、previous_response_id、store: falseの判断
• function callingとtool outputの見直し方
• structured outputの移行で見る場所
• streaming、retry、ログの分け方
• Codexへ渡すmigration queueと公開前gate

Responses APIは、新しいAPI primitiveとして、agenticな使い方やnative tools、multi-turn、multimodalに寄せた設計です。一方で、既存のChat Completions integrationがすぐ消えるわけではありません。実務では、移行するflowと残すflowを分けて進めるほうが安全です。

前提知識

項目	内容	見方
Responses		推奨API。
Chat		既存API。
Assistants		移行対象。
Streaming		配信。
Text		生成。

API移行では、使っている機能ごとに見るdocsが変わります。

OpenAI公式の「Migrate to the Responses API」では、Responses APIがChat Completionsの進化形として説明され、新規projectではResponsesが推奨されています。Chat Completions API referenceでも、最新機能を使うならResponsesを試すことが案内されています。

移行ガイドでは、Responses APIがbuilt-in tools、multi-turn interactions、text/imagesのnative multimodal supportを持つこと、Chat CompletionsとResponsesでは返却objectやfunction calling、structured outputの形が違うことが説明されています。

Chat Completionsはまだ使えるが新規はResponses寄り

Chat Completionsは、会話message配列からmodel responseを作るAPIです。既存integrationでは今も多く使われます。公式docsでもChat Completionsは説明されています。

ただし、新しいprojectやreasoning model、built-in tools、statefulなagentic workflowを使う場合は、Responses APIを前提に設計するほうが自然です。移行対象を決める時は、既存flowを無理に全部同時に移すのではなく、Responsesの利点が出るflowから移します。

Assistants API移行は別トラックにする

OpenAIのAssistants migration guideでは、Assistants APIからResponses APIへの移行が扱われています。Assistants APIは、thread、assistant、runなどの概念を持っていたため、Chat Completionsからの移行とは確認項目が違います。

既存systemにChat CompletionsとAssistants APIが両方ある場合、同じPRでまとめて移すのは避けます。Chat CompletionsからResponsesへの移行、Assistants APIからResponsesへの移行、model更新、tool更新は別トラックとして扱います。

移行対象を棚卸しする

項目	内容	見方
Endpoint		呼出先。
Model		指定。
Tools		関数。
Output		返却。
State		履歴。

使っている機能を知らないまま一括置換しないようにします。

最初にやるのは、置換ではなく棚卸しです。Codexには、OpenAI APIを呼んでいる箇所を探させ、使っている機能ごとに分類させます。

棚卸しでは、endpoint、model、input、output、tool/function、structured output、streaming、state、storage、retry、logging、testを見ます。

endpoint

/v1/chat/completions、/v1/responses、Assistants API、legacy Completions APIが混ざっていないかを確認します。

同じrepo内でも、管理画面の要約、顧客向けchat、batch job、社内tool、test helperでAPI呼び出しが分かれていることがあります。Codexには、呼び出し箇所をpath、用途、owner、riskで表にさせます。

model

model名は、API移行と同時に変えないほうが比較しやすいです。endpointとmodelを同時に変えると、挙動差の原因が分からなくなります。

Responses APIへ移すPRでは、まず既存model相当で通るかを見ます。model更新は、別PRや別feature flagに分けると、品質とcostの変化を追いやすくなります。

tool

function callingや外部toolを使っているflowは、移行の難度が上がります。Responses APIではtool callとtool outputの扱いがChat Completionsと違います。

Codexには、tool名、schema、strictness、tool outputの戻し方、retry、timeout、permissionを棚卸しさせます。toolが外部APIや課金、DB更新に触れる場合は、人間承認を残します。

state

multi-turn conversationでは、履歴の持ち方が重要です。Chat Completionsでは、message履歴を自前で管理することが多いです。Responses APIでは、previous_response_idや保存機能を使う選択肢があります。

stateの移行は、便利さだけで決めません。保存方針、privacy、compliance、ログ保持、削除要求、監査の要件を見ます。

endpoint差分を小さく直す

1. 1Find

   呼出箇所。

2. 2Wrap

   adapter。

3. 3Patch

   小変更。

4. 4Compare

   比較。

最初のPRでは、挙動を変えずAPI境界を薄く移します。

endpoint移行は、小さなadapterから始めると安全です。いきなり全呼び出しをresponses.createへ書き換えるのではなく、既存の呼び出しを薄いwrapperへ集め、1つのflowだけResponsesへ切り替えます。

最初のPRでは、挙動差を減らします。model、prompt、temperature、structured output、tool設定、timeout、retryをできるだけ既存に合わせます。

inputとmessages

Chat Completionsでは、messagesにroleとcontentの配列を渡します。Responses APIでは、string inputやinput itemを渡せます。簡単なtext generationでは、移行しやすいです。

ただし、system message、developer instruction、tool result、image input、履歴の持ち方がある場合は、単純置換では足りません。

Codexには、各flowについて「inputをどう作っているか」を先に説明させます。prompt builderが複数ある場合は、builder単位で移行します。

output_textとoutput items

Responses SDKにはoutput_text helperがあります。一方で、Responses APIの返却はoutput itemsの配列です。reasoning item、message、tool callなど、複数のitemが入ることがあります。

既存コードがchoices[0].message.contentだけを前提にしている場合、移行後の読み取りを変える必要があります。

Codexには、返却値を読んでいる箇所も探させます。生成結果の表示、ログ、usage記録、error handling、test snapshotが対象です。

nやchoices前提

Chat Completionsでnを使って複数候補を出しているflowは注意が必要です。Responses APIでは、同じ前提で複数choicesを読む形ではありません。

複数候補が必要なUIなら、Responses API呼び出しを複数回にするのか、別の設計にするのかを決めます。

候補生成、best-of、rerank、A/B testを同じ移行PRで変えると、評価が難しくなります。まず既存挙動を保つか、仕様変更として別に扱います。

state管理を決める

Previous

id連結。

Store

保存。

Manual

自前履歴。

ZDR

制約。

会話履歴は、便利さと保存方針を分けて決めます。

Responses API移行で大きいのが、state管理です。Responsesにはstatefulな使い方があり、previous_response_idで前のresponseへつなげる選択肢があります。一方で、組織のdata retentionやcompliance要件によっては、保存を避ける必要があります。

stateの判断は、エンジニアだけで決めないほうがよいことがあります。product、security、legal、supportが関係する場合があります。

previous_response_id

previous_response_idを使うと、multi-turnのつながりを扱いやすくなります。毎回すべての履歴を組み立てる設計より、コードが薄くなる場合があります。

ただし、どのconversationで使うか、どのresponse idを保存するか、失敗時にどう復旧するかを決めます。idだけ残って、実際の会話状態が追えないとdebugしにくくなります。

store false

保存を避けたいflowでは、store: falseを検討します。公式docsでは、storageを無効にする設定や、statefulnessに関する注意が説明されています。

customer data、health、finance、legal、enterprise contract、Zero Data Retentionに関係するflowでは、保存方針を先に確認します。

自前履歴

既存systemが自前でconversation履歴を保存しているなら、そのまま残す選択もあります。Responsesへ移しても、すべてのstateをOpenAI側に寄せる必要はありません。

自前履歴を残す場合、prompt assembly、token budget、redaction、deletion、audit logを続けて管理します。

complianceで見る境界

statefulなAPI利用は、UXだけでなく保存方針の問題です。どのデータをOpenAIへ送り、どのデータを自社DBへ保存し、どのデータをログへ残すのかを分けます。

Codexには、policy判断をさせるのではなく、判断に必要な利用箇所、送信データ、保存データ、削除経路を整理させます。

function callingを見直す

項目	内容	見方
Schema		定義。
Strict		厳格。
Call ID		対応。
Output		戻し。

tool callingは、request定義とresponse処理の両方を見直します。

function callingを使っている場合、移行は慎重に進めます。公式移行ガイドでは、Chat CompletionsとResponsesでfunction定義の形に違いがあり、Responsesではtool callsとtool outputsがdistinct itemとして扱われることが説明されています。

つまり、request側だけでなく、response処理とtool outputの戻し方も移行対象です。

schema

まずschemaを確認します。関数名、description、parameters、required、additionalProperties、enum、nullable、defaultの扱いを見ます。

既存schemaが緩い場合、Responses側でstrictな扱いへ寄せると、これまで通っていた曖昧なtool callが失敗することがあります。失敗は悪いことではありませんが、error handlingを用意します。

call_id

Responses APIでは、tool callとtool outputを対応させるためのidが重要になります。toolを実行したあと、どのcallへoutputを返すかを間違えると、会話が壊れます。

Codexには、tool call loopを図にさせるとよいです。model output、tool execution、tool output、next responseの順序を確認します。

strict

function schemaのstrictnessは、品質と互換性に影響します。strictにすれば、tool inputの形は安定しやすくなります。一方で、既存の曖昧なpayloadを受けていたflowは落ちる可能性があります。

移行時は、strict化をendpoint移行と同時にやるか分けるかを決めます。高riskなflowでは、先にschema testを作ります。

structured outputを移す

項目	内容	見方
Old		response_format。
New		text.format。
Schema		型。
Fallback		失敗時。

schemaだけでなく、失敗時の扱いも移行対象にします。

structured outputを使っているflowでは、出力形式の指定場所が変わります。公式移行ガイドでは、Responses APIではresponse_formatではなくtext.formatを使う形が説明されています。

ここも、一括置換に見えて罠があります。schema、parse、validation、fallback、retry、snapshot testが絡むからです。

response_format

Chat Completionsでresponse_formatを使っている箇所を探します。JSON object、JSON schema、structured output helper、独自parserが混ざっていないかを確認します。

Codexには、各flowで「どのschemaを期待し、どこでparseし、失敗時にどうしているか」を表にさせます。

text.format

Responses APIへ移す時は、text.formatへ移します。schemaが同じに見えても、SDK helperや返却objectの形が変わる場合があります。

型定義があるrepoでは、schemaからTypeScript typeを生成しているか、手書きtypeかも見ます。typeとruntime schemaがずれている場合、移行のタイミングで直すか別タスクにします。

fallback

structured outputで大事なのは、成功時より失敗時です。parseに失敗した時、retryするのか、人間確認へ回すのか、partial resultを捨てるのか、raw outputをログに残すのかを決めます。

Codexには、happy pathだけでなく、invalid JSON、missing field、extra field、tool timeoutのtestを提案させます。

streamingとログを分ける

Events

種類。

Retry

再試行。

Logs

記録。

UX

表示。

streamingは動けばよいではなく、途中失敗とログを見ます。

streamingを使っているUIやworkerでは、移行の確認が増えます。最後のtextが同じでも、途中event、typing indicator、cancel、retry、timeout、ログが変わることがあります。

公式Streaming guideでは、API responseを一括で受けるのではなくstreamingで受ける方法が説明されています。Responses API modeとChat modeでコードの形が変わるため、既存のstream parserを確認します。

event

streamingでは、どのeventをUIが見ているかを確認します。text delta、tool call、completion、error、usage、reasoning summaryなど、必要なeventだけを処理します。

event名やpayloadの形が変わると、UIが止まったり、ログだけ壊れたりします。

retry

途中でstreamが切れた時の扱いも決めます。再試行するのか、ユーザーへ失敗を返すのか、partial outputを保存するのか。

生成途中にtool callが絡むflowでは、同じtoolを二重実行しないようにします。外部APIや課金処理を含むtoolでは特に重要です。

observability

移行後も、latency、token usage、error rate、tool call count、timeout、user cancelを見ます。API移行でcostやlatencyが変わることがあるためです。

Codexには、コード修正だけでなく、ログ項目の差分も見させます。既存dashboardやalertがChat Completions前提のfield名を読んでいる場合があります。

Codexに渡す移行キュー

項目	内容	見方
Flow		対象。
Risk		影響。
Patch		差分。
Test		確認。
Owner		判断。

Codexには、全移行ではなく小さなqueueを渡します。

棚卸しが終わったら、Codexへmigration queueを渡します。queueは、flow、risk、変更範囲、test、owner、rollbackを持つ表にします。

「repo全体をResponses APIへ移行して」ではなく、「admin summary flowだけをResponses APIへ移す」「toolなしのtext generationだけ移す」「structured output flowは調査だけ」のように分けます。

inventory

まずinventoryだけを作らせます。

flow	endpoint	tools	state	structured output	streaming	risk
support summary	chat	none	manual	no	no	low
user chat	chat	functions	manual	no	yes	high
report JSON	chat	none	none	yes	no	medium

この表があると、低riskなflowから移せます。

patch

patchは、小さくします。1つのPRで移す対象は、同じ性質のflowだけにします。

たとえば、toolなしのtext generationを先に移し、streamingありのchat UIは後にします。structured outputはschema testを足してから移します。Assistants APIは別計画にします。

tests

testは、unit、integration、snapshot、manual check、shadow comparisonに分けます。

Responses APIへ移したflowでは、同じ入力で旧実装と新実装の出力を比較します。完全一致を求める必要はありませんが、schema、重要field、error handling、latency、usageの差分は見ます。

release前に見ること

1. 1Shadow

   比較。

2. 2Cost

   使用量。

3. 3Errors

   失敗。

4. 4Rollback

   戻し。

API移行は公開前に、品質と運用の両方を確認します。

API移行のrelease前には、コードが通るだけでは足りません。shadow run、cost、latency、error、rollback、monitoringを確認します。

Codexには、release checklistを作らせます。人間は、そのchecklistが自社の運用に合っているかを見ます。

shadow

可能なら、旧実装と新実装を同じ入力で比較します。production trafficをそのまま二重送信する場合は、data policyとcostに注意します。

shadowは、出力の完全一致より、破壊的な差分を見つけるために使います。schemaが壊れていないか、tool callが増えすぎていないか、latencyが大きく悪化していないかを見ます。

rollback

rollbackは、feature flagやadapterで戻せる形にします。API移行PRで古い実装をすぐ消すと、戻しにくくなります。

まずは切替点を残し、一定期間monitoringしてから古いpathを消します。

cost

Responses APIへ移すと、cache利用、state、tool call、model選択、reasoning effortでcostが変わります。公式移行ガイドでは、Responsesのbenefitとしてcache utilizationの改善などが説明されていますが、自社flowでどうなるかは測ります。

costは、平均だけでなくp95や異常値を見ます。tool loopが増えると、一部requestだけ高くなることがあります。

よくある失敗

Replace all

一括置換。

Lost state

履歴消失。

Tool drift

関数差分。

No shadow

比較なし。

成功した1リクエストだけで、本番移行を判断しないようにします。

よくある失敗は、一括置換、state消失、tool差分の見落とし、structured outputのhappy pathだけ確認、streamingの途中失敗未確認、rollbackなしです。

一括置換は、短期的には速く見えます。しかし、挙動差が出た時に原因を分けられません。

state消失は、multi-turnで起きます。前のturnのcontextが渡らず、応答が浅くなることがあります。

tool差分の見落としは、外部APIやDB更新で危険です。tool callが増えたり、同じ処理を二重実行したりする可能性があります。

structured outputのhappy pathだけ確認すると、parse失敗時にUIやworkerが落ちます。

streamingの途中失敗を見ないと、ユーザーには途中で止まったように見えます。

rollbackなしは、移行後の運用を重くします。feature flag、adapter、旧pathの保持期間を決めてから公開します。

Codexに判断を任せすぎる

Codexは、呼び出し箇所の棚卸し、差分作成、test追加、migration queue作成に向いています。一方で、data retention、compliance、pricing許容、user experienceの最終判断は人間側に残します。

特に、store、customer data、tool permission、external API実行、production rolloutは、Codexの提案をそのまま採用しません。

model更新とAPI移行を混ぜる

model更新とAPI移行を同時に行うと、品質差の原因が分かりません。まずAPI境界を移し、その後にmodelやreasoning effortを調整します。

どうしても同時に変える場合は、変更理由と比較条件をPR本文へ残します。

FAQ

項目	内容	見方
一括?		段階的。
Chat?		継続可。
Assistants?		別計画。
Tools?		先に棚卸し。

迷ったら、使っている機能単位へ戻します。

Chat Completionsはすぐやめるべきですか？

すぐ全停止と考える必要はありません。公式docsではResponsesが新規project向けに推奨されていますが、既存flowは段階的に移すほうが安全です。

Assistants API移行も同じ手順でよいですか？

一部は共通しますが、別トラックにするほうがよいです。Assistants APIにはassistant、thread、runなどの概念があるため、Chat Completionsからの移行とは確認項目が違います。

function callingがないflowから移してよいですか？

はい。toolなし、streamingなし、structured outputなしのtext generationは、最初の移行対象にしやすいです。低riskなflowでadapterとmonitoringを作ると、次の移行が楽になります。

structured outputはschemaを同じにすれば十分ですか？

十分ではありません。response_formatからtext.formatへ移すだけでなく、parse、validation、fallback、test snapshotを確認します。

Codexにはどこまで任せるべきですか？

棚卸し、差分案、test追加、migration queue、PR説明の作成は任せやすいです。保存方針、customer data、rollout、rollback条件は、人間が判断します。

参照した主な情報源

• Migrate to the Responses API – OpenAI API
• Chat Completions API reference – OpenAI API
• Text generation guide – OpenAI API
• Streaming API responses – OpenAI API
• Assistants migration guide – OpenAI API
• Codex Use Cases – OpenAI Developers

次に読むなら

更新履歴

1. 2026.06.01

   初版。

OpenAI APIの仕様は更新されるため、移行時に公式docsを見直します。

• 2026年6月1日: OpenAI公式API docsのResponses API移行ガイド、Chat Completions API reference、Text generation guide、Streaming guide、Assistants migration guide、Codex Use Casesを確認し、初版を作成しました。