Gemini Interactions API の `steps` 移行は、SDK 更新より parser 棚卸しが本体

要点

要点まとめ

Google は Gemini Interactions API の返り値の読み方を切り替え、古い形式を 2026-06-08 で外すと明記した。
怖いのは SDK 更新そのものより、返り値を読む自前コードや監視画面が静かに壊れることだ。
新しい `steps` 形式では、会話、tool 呼び出し、結果が時系列で並ぶため、アプリ側の読み方も変える必要がある。
function calling、構造化出力、streaming、会話履歴の引き継ぎを持つ実装ほど影響範囲が広い。

続けて読む

読み終えたら次へ

この1本で終わらせず、同じ目的・同じテーマ・近い原典へ進めます。

同じ目的で読む 作る前に確認したい

API や設定を試す前に、先に落とし穴を知りたい人向け。

同じテーマで読む LLM API

Responses API、Gemini API、モデル更新、構造化出力、SDK。

次の記事 Gemini API の release notes は、仕様変更を追うための一次情報になる

Gemini API の changelog は、モデル、SDK、OpenAI compatibility、構造化出力などの変更確認に使える。

読解

何が変わったのか

この migration guide は、response の主要単位を平坦な `outputs` 配列から、時系列を持つ `steps` へ切り替えています。新 schema では `user_input` と `model_output` を timeline として扱い、function calling や server-side tool result もその中に入ります。つまり、単に property 名を読み替えるだけでは足りず、『モデルの返答をどう観測し、履歴としてどう次 request に渡すか』というアプリの見方自体が変わります。

日本の文脈

なぜ重要か

日本の開発者にとって重要なのは、期限が明記された schema change であり、しかも failure mode が地味なことです。アプリが完全停止するとは限らず、function call を拾えない、tool result を描画できない、SSE listener が新 event を見ない、history の継続入力が壊れる、という半壊が起きやすい。これは QA で見逃しやすく、本番で初めて気づきやすい種類の変更です。

技術ポイント

技術的ポイント

latest SDK では new schema へ自動移行するが、response reader の更新は残る。Python 2.0+ と JavaScript 2.0+ で legacy schema は扱わない前提になる。
REST API では `Api-Revision: 2026-05-20` で先行 opt-in、`2026-05-07` で一時 opt-out ができたが、2026-06-08 以降は legacy schema が削除される。
function calling は `outputs` 走査から `steps` 内の function-related step を探す形へ変わる。tool result や search result を扱うコードも同様に読み替えが必要。
stateless history は次 request の `input` に `steps` を渡す前提へ変わる。会話継続や replay 実装を持つアプリでは影響が広い。
streaming client は `interaction.created` や `step.delta` など新しい SSE event type を listen できないと、表面上は接続できても UI 更新が壊れる。
`response_format` 移行は structured output 利用者ほど要確認で、`response_mime_type`、schema 包装、image config、multimodal array 化まで同時に見る必要がある。

用語

英日キーワード

英語	日本語	補足
outputs	旧 outputs スキーマ	legacy response の平坦な出力配列。Gemini Interactions API では `steps` への移行で読み替えが必要になった。
steps	steps スキーマ	入出力と tool 呼び出しを時系列で持つ新しい表現。parser、viewer、履歴引き継ぎの実装影響が大きい。
function calling	関数呼び出し	モデル出力をアプリ側の関数実行に接続する仕組み。schema 設計と失敗時処理が実装品質を左右する。
response_format	出力形式設定	構造化出力や multimodal response の指定方法。schema の包み方や parser の前提に効く。
Api-Revision	APIリビジョン指定ヘッダー	REST API で schema を切り替えるためのヘッダー。移行猶予や先行 opt-in の管理に使う。
step.delta	ステップ差分イベント	streaming 時に新 schema で流れる差分イベント。listener が古い event 名のままだと UI が半壊しやすい。

試す

試すなら

`interaction.outputs` を読んでいる箇所を全検索し、parser、viewer、logger、history builder、streaming handler に分類する。
SDK 利用なら 2.0 系で staging を回し、REST 利用なら新 revision で replay test を作って `steps` の実 payload を確認する。
function calling、server-side tools、structured output、SSE streaming の4経路で回帰テストを作り、『半壊』を見逃さないようにする。
migration をコード修正だけで終わらせず、運用 runbook に『vendor schema change を読む担当』と『期限前に replay test を走らせる手順』を残す。

注意

注意点

このガイドは Interactions API 向けであり、Gemini API 全体の全 endpoint に同じ変更が及ぶとは限らない。適用範囲を混同しないほうがよい。
SDK 更新で request 構造が大きく変わらない箇所もあるが、response の読み方は別問題で、特に自前の log viewer や analytics pipeline は壊れやすい。
2026-06-08 の期限はこの migration guide に基づく。すでに移行済みかどうかは手元の SDK version と response payload を見て確認すべき。

この記事は役に立ちましたか

公益的に続けるため、役に立った点や読みづらかった点だけを短く送れます。メールアドレスは不要です。