Gemini Interactions API 移行ガイド：outputs を steps に変更した後のトラブルシューティング

Sun, 12 Jul 2026 10:33:00 +0800

Gemini Interactions API は、新しいプロジェクトに推奨される統合インターフェイスになりました。これは、生成、ツール呼び出し、思考プロセス、ツールの結果、最終応答を観察可能な実行ステップとして表し、中間状態を表示する必要があるエージェント、長いタスク、およびアプリケーションに適しています。

これは、従来のコードが応答で outputs を想定できなくなったことも意味します。 2026 年 5 月以降、新しいスキーマがデフォルトになります。古いスキーマは 6 月 8 日に削除されました。移行後に空の応答がある場合、ツール呼び出しが失われる場合、SSE イベントがトリガーされない場合、または履歴コンテキストが壊れている場合、通常はモデルの問題ではなく、データが依然として古い構造に従って読み取られているということです。

まず移行先のレイヤーを確認します

トラブルシューティングを行う前に、1 つのフィールドだけを変更しないように、まず問題を分類します。

階層	古いやり方	新しい方法
最終テキスト	`outputs` をトラバースしてテキスト	を検索します。簡易シーン読み込み `interaction.output_text`
完全な返答	`outputs`	でコンテンツ、ツール、または検索結果を見つけます。 `interaction.steps` をトラバースし、`type` として処理します
ツール呼び出し	古いコンテンツタイプから解析する	`function_call`、`function_result` などのプロセスステップ
ストリーミングイベント	`content.start`、`content.delta`、`content.stop`	`step.start`、`step.delta`、`step.stop`
マルチラウンドの歴史	古い `outputs` を返す	サーバーで `previous_interaction_id` を使用するか、クライアントで `steps` を返します

SDK がまだ Python 1.x または JavaScript 1.x である場合は、最初にバージョンを確認してください。公式の移行手順では、新しいスキーマを自動的に採用するには、Python ≥2.0.0 または JavaScript ≥2.0.0 を使用する必要があります。ただし、SDK をアップグレードしても、自分で作成した outputs パーサー、SSE プロセッサー、およびフロントエンドステートマシンは自動的に修正されません。

最も簡単な修正: `output_text` で最終テキストを読み取る

プレーンテキストの質問と回答のみを処理する場合、steps から最後のテキストを手動で検索する必要はありません。新しいバージョンの SDK は、応答の末尾にある連続したテキストブロックを抽出して結合する output_text を提供します。

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="用三句话解释什么是 prompt caching。",
)

print(interaction.output_text)

移行後に interaction.outputs[-1].text をそのままにしておくと、一般的な結果として、プロパティが存在しないか、インデックス付けが失敗するか、オブジェクトが誤って空の文字列にシリアル化されます。まずこれを interaction.output_text に置き換えてから、複雑なシナリオのステップ分析を追加します。

output_text は、すべての応答に適しているわけではありません。テキストが思考、画像、音声、またはツール呼び出しによって分離されている場合、インターリーブされたすべてのコンテンツは復元されません。完全な実行プロセスを表示する必要がある場合は、steps をトラバースする必要があります。

`steps` を適切にトラバースする方法

新しいスキーマは、プロセスを型付きステップとして表します。少なくとも、user_input、model_output、function_call、および function_result は認識されます。サーバー側ツールを使用している場合は、google_search_call、google_search_result、またはその他のツール固有の手順も表示されます。

次の例では、最終的なモデル出力からテキストのみを収集します。

def collect_model_text(interaction):
    chunks = []

    for step in interaction.steps:
        if step.type != "model_output":
            continue

        for item in step.content or []:
            if item.type == "text":
                chunks.append(item.text)

    return "".join(chunks)


print(collect_model_text(interaction))

実際のプロジェクトでは、content がすべてのステップに存在すると仮定したり、thought を最終的な答えとして扱ったりしないでください。最初に step.type に従って分岐し、次にこのタイプで許可されるフィールドを読み取ります。前方互換性を維持するために、未知のステップをタイプ、ID、およびステータスとして記録します。新しいツールステップが表示されたからといって、リクエスト全体が失敗しないようにしてください。

ツール呼び出しが「消える」のはなぜですか?

古いスキーマでは、サーバー側ツールの操作が outputs という特定のコンテンツタイプでラップされることがよくあります。新しいスキーマでは、これらを独立したステップに分割するため、model_output のみをスキャンしても、検索、関数呼び出し、関数の結果は表示されません。

たとえば、関数呼び出しは次のようになります。

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Calling ${step.name}`);
    console.log(step.arguments);
  }
}

サーバー側の Google 検索では、検索が実行されたかどうかを最終的なテキストから推測するのではなく、呼び出しと結果のステップを個別に処理する必要があります。クライアント機能ツールの場合、requires_action を受信した後、対応する function_result を送信し、インタラクションのステータスを使用し続けて後続のプロセスを完了します。

ストリーミング SSE イベントは一緒に移行されます

REST 応答の解析のみを変更し、ストリームプロセッサを変更しない場合、フロントエンドは通常、「リクエストは成功しましたが、ページは更新されません」として動作します。新しいイベント名は以下のとおりです。

昔の出来事	新しいイベント
`interaction.start`	`interaction.created`
`interaction.complete`	`interaction.completed`
`content.start`	`step.start`
`content.delta`	`step.delta`
`content.stop`	`step.stop`
`interaction.status_update`	`interaction.in_progress`、`interaction.requires_action`、およびその他のステータスイベント

関数呼び出しのパラメータは、完全に一度に到着することが保証されなくなりました。ストリームでは、step.start が最初に関数名を指定し、次に複数の step.delta イベントがいくつかの JSON パラメーターを使用して部分的に配信されます。クライアントはパラメータを蓄積し、step.stop またはアクションが必要な状態の後に完全な JSON を解析する必要があります。各デルタに対して直接 JSON.parse() を実行しないでください。

let rawArguments = '';

for await (const event of stream) {
  if (event.event_type === 'step.delta' && event.delta?.type === 'arguments') {
    rawArguments += event.delta.partial_arguments;
  }

  if (event.event_type === 'step.stop') {
    // 只在对应 function_call 步骤完成后解析 rawArguments。
  }
}

複数ラウンドの対話の後は返信しないでください `outputs`

古いステートレス実装では、多くの場合、前のラウンドの outputs を収集し、それを次のラウンドの input に戻します。移行後には、より明確なオプションが 2 つあります。

デフォルトのサーバー側状態を使用して、previous_interaction_id 経由で同じセッションを継続します。
履歴を自分で管理する必要がある場合は、前のラウンドの steps を返し、新しい user_input ステップを追加します。

サーバー側のステータスは、通常の複数ラウンドの会話に適しています。クライアント側のステータスは、保存されたコンテンツ、システム間の移行、またはオフライン再生の厳密な制御が必要な場合に使用されます。どちらを選択する場合でも、古い outputs と新しい steps を同時に接続しないでください。接続しないと、コンテキストの重複、ツール結果の不一致、またはトークンの増殖が簡単に発生します。

`response_format` もエラーの原因である可能性があります

この移行は出力配列を変更するだけではありません。構造化出力とマルチモーダル構成も、トップレベルの response_format に統合されています。

元の response_mime_type は削除されました。 response_format エントリに mime_type を指定します。
JSON スキーマは、type: "text" を使用してフォーマットオブジェクトに入れる必要があります。
画像構成が generation_config から type: "image" の response_format エントリに移動されました。
マルチモーダル出力には、フォーマットエントリの配列が必要です。

インターフェイスが 400 を返した場合、steps のチェックに加えて、コードでは response_mime_type、generation_config.image_config、および従来の単一オブジェクト response_format も検索されます。これらの古いフィールドは、同じアップグレード後に outputs 問題とともに表示されることがよくあります。

実際のトラブルシューティング手順

Google GenAI SDK をアップグレードし、実際のバージョンを文書化します。
ツール不要の非ストリーミングの最小限のリクエストで interaction.output_text を検証します。
interaction.steps のタイプとステータスを出力して、プログラムが新しいスキーマを受け取ったことを確認します。
関数呼び出し、サーバー側の検索、ツールの結果の解析ロジックをそれぞれ移行します。
SSE イベントサブスクリプションとパラメータ蓄積ロジックを変更します。
マルチラウンド履歴が previous_interaction_id または steps に変更されているかどうかを確認します。
古い response_format 関連フィールドを検索して置換します。
テキスト、ツール呼び出し、ストリーミング出力、失敗の再試行を使用して回帰テストを 1 つずつ実行します。

古いコードを一時的に復元するために古い Api-Revision ヘッダーに依存しないでください。古いスキーマの移行期間は終了しました。移行は、一貫性のないパーサーを 2 セット継続するのではなく、公式の互換性修正プログラムとみなされるべきです。

概要

outputs を steps に変更する本質は、インタラクション API がすべてのプロセスを出力リストに詰め込むのではなく、入力、リフレクション、ツール、結果、および最終出力を明示的に公開することです。純粋なテキストシーンでは、interaction.output_text が優先的に使用されます。エージェント、ツール、ストリーミング、およびマルチモーダルシーンは、step.type を使用して明示的な分岐を確立します。マルチラウンドセッションでは、代わりに previous_interaction_id または steps を使用します。これら 3 つの原則に従って移行すると、「出力がない」、「ツールが見つからない」、「SSE が更新されない」の問題のほとんどを見つけることができます。

公式情報:

Interactions API on KnightLiブログ

Gemini Interactions API 移行ガイド：outputs を steps に変更した後のトラブルシューティング

まず移行先のレイヤーを確認します

最も簡単な修正: output_text で最終テキストを読み取る

steps を適切にトラバースする方法