OpenAIはResponses APIのassistantメッセージへphaseフィールドを追加した。値は途中経過を示すcommentaryと、利用者へ返す最終結果を示すfinal_answerである。
表示上のラベルに見えるが、公式APIリファレンスは、GPT-5.3 Codex以降のようなモデルへ後続リクエストを送る際、すべてのassistantメッセージでphaseを保持して再送するよう求めている。欠落すると性能が低下し得るため、会話データのスキーマ変更として扱う必要がある。
何が変わったか
Responses APIの入力・出力メッセージで、assistantメッセージが作業途中の説明なのか最終回答なのかを機械的に識別できるようになった。userメッセージには使用しない。
変更前後の差
| 項目 | phaseなし | phaseあり |
|---|---|---|
| 途中経過の識別 | 文面や順序から推測 | commentaryで明示 |
| 最終回答の識別 | 最後のメッセージと仮定 | final_answerで明示 |
| 会話再送 | roleとcontent中心 | phaseも保持 |
| UI表示 | 独自ルール | API情報で分離可能 |
| 監査 | 作業ログと結論が混在 | 種別ごとに保存可能 |
| 互換性 | 古い保存形式 | スキーマ移行が必要 |
誰に影響するか
長時間のコード変更、調査、複数ツール実行、ストリーミングで進捗を見せるアプリ、Response出力をDBへ保存して後から会話を再開するシステムに影響する。単発で最終テキストだけを使い、履歴を再送しない処理では影響は限定的である。
期限
強制移行期限は公表されていない。ただし、対応モデルで履歴を再利用するシステムは、欠落による品質低下を避けるため早期対応が必要である。
必要な対応
保存スキーマへphaseを追加し、未知値を破棄しない。既存データには無理に推測値を一括付与せず、移行後に受信した値を正本とする。UI、通知、監査、エクスポートでも途中経過と最終回答を別扱いにする。
実装・移行手順
- Responseの全output itemを保存しているか確認する。
- assistant messageにnullableな
phase列を追加する。 - API応答の
phaseをそのまま永続化する。 - 後続リクエストの履歴再構築で
phaseを復元する。 commentaryは進捗欄、final_answerは確定結果欄へ表示する。- 旧レコードはnullのまま互換処理し、新旧混在を試験する。
- SDK更新後もJSONシリアライザーが未知フィールドを落とさないか確認する。
失敗しやすい点
最後のassistantメッセージを常に最終回答と仮定する、DB保存時に認識しないフィールドを除去する、ストリームの途中でcommentaryをユーザーへの確定回答として通知する、会話再送時にcontentだけを再構築する、といった実装が問題になる。
リスク
phase欠落によるモデル性能低下、途中経過の誤配信、未確定コードや推測の外部送信、監査ログで最終判断を特定できない問題がある。途中経過には機密なツール結果が含まれる可能性があるため、表示権限も分離すべきである。
評価方法
- phase保存率と再送率
- commentaryを最終回答として表示した件数
- 会話再開前後のタスク成功率
- 同一履歴でphase有無を比較した回帰試験
- ストリーム切断後の復元成功率
- 最終回答を監査ログから一意に取得できる割合
- 旧クライアントとの互換エラー件数
ロールバック
UIの新しい表示分離に問題があれば、保存自体は継続したまま旧表示へ戻す。API送信ではphaseを落とすロールバックを行わず、対応モデルへの再送情報を維持する。DB列追加は後方互換にし、旧アプリが読める状態を保つ。
編集部分析
phaseは表示上の装飾ではなく、エージェント実行の状態を伝えるプロトコル要素である。AIアプリが長時間・複数段階になるほど、「モデルが今考えていること」と「利用者が採用すべき結果」を区別する責任は大きくなる。保存、再送、表示、通知、監査を同時に更新しなければ効果は出ない。
実務チェックリスト
- [ ] assistantメッセージのphaseを保存している
- [ ] 後続リクエストでphaseを再送している
- [ ] userメッセージへphaseを付けていない
- [ ] commentaryとfinal_answerをUIで区別した
- [ ] 未知フィールドを落とす変換処理を確認した
- [ ] 旧レコードとの混在を試験した
- [ ] 途中経過の閲覧権限を確認した