0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Gemini Deep Research API移行ガイド、旧IDは10月23日に停止

0
Posted at

はじめに

Gemini API の Deep Research エージェントを組み込んだコードが、今日も問題なく動いているとします。それでも、agent に deep-research-pro-preview-12-2025 と書いてあるなら、そのコードには停止日が決まっています。動いている今のうちに、どこを直せば止まらずに済むのでしょうか。

対象読者は、Gemini API の Deep Research エージェント（deep-research-pro-preview-12-2025）を使っている、または使う予定の開発者です。

Gemini API の changelog によると、2026-10-08 に deep-research-pro-preview-12-2025 は非推奨となり、2026-10-23 に停止 する予定です。同じ日には gemini-3.5-flash と gemini-3.7-flash の置き換えも告知されていますが、こちらは新モデルへの自動転送が明記されているのに対し、Deep Research 側には自動転送の記載がありません。

この記事で解決できること

  • 公式の非推奨告知の内容と、移行先 2 種類の選び方
  • interactions.create の agent 差し替えを中心にした移行手順
  • 停止日までに確認しておくチェックリスト

前提条件

  • Gemini API キーを環境変数 GEMINI_API_KEY に設定済みであること
  • Python の google-genai SDK、または REST で Interactions API を呼び出していること

Deep Research エージェントの基本的な使い方は、以前の記事「Gemini Deep Research Agent入門」で扱いました。ただし同記事は旧 ID を前提に書いており、本記事はその旧 ID からの移行と、同記事の記述が古くなった点に絞ります。

TL;DR

この記事の手順を終えると、次の状態になります。

  1. コード中の deep-research-pro-preview-12-2025 を deep-research-preview-04-2026 か deep-research-max-preview-04-2026 に置き換え終わっている
  2. レスポンスの読み取り位置（steps[-1].content[0].text）とポーリング処理が現行ドキュメントの記述に揃っている
  3. 「モデル一覧に見えているから安全」という判断に頼らず、非推奨ページを監視する運用になっている

公式発表の整理

changelog と deprecations ページの記述を並べると、今回の変更は次のとおりです。

ID リリース日 停止日 代替
deep-research-pro-preview-12-2025 2025-12-11 2026-10-23 deep-research-preview-04-2026
deep-research-preview-04-2026 2026-04-21 未発表 なし
deep-research-max-preview-04-2026 2026-04-21 未発表 なし
gemini-3.7-flash 2026-08-13 未発表（gemini-3.8-flash へ自動転送） gemini-3.8-flash
gemini-3.5-flash 2026-05-19 未発表（gemini-3.6-flash へ自動転送） gemini-3.6-flash

出典: Gemini API changelog、Gemini API deprecations

数字に直すと、旧 ID はリリースから停止まで 316 日、非推奨の告知（2026-10-08）から停止まで 15 日です。後継の 2 つは旧 ID の停止より約半年前の 2026-04-21 に公開されており、告知の時点で移行先はすでに揃っていました。

一点、日付の読み方に注意があります。deprecations ページの原文は、表の停止日を「earliest possible dates」（最も早い場合の日付）としており、正式な日付は事前に通知されると書いています。つまり 2026-10-23 は「この日より前には止まらない」日付であって、「この日まで確実に動く」保証ではありません。移行の締め切りとしては、この日付を最終ラインと考え、余裕を持って前倒しするのが安全です。

移行先 2 種類の使い分け

changelog は移行先を 2 つ挙げ、それぞれの性格を次のように説明しています。

移行先 公式の説明 向いている用途
deep-research-preview-04-2026 速度と効率を重視。クライアント UI へのストリーミングに向く ユーザーが画面の前で結果を待つアプリ、進捗を逐次表示する UI
deep-research-max-preview-04-2026 網羅性を最大化 バッチ処理で回す調査、時間よりも抜け漏れの少なさを優先するレポート

deprecations の表で旧 ID の代替欄に載っているのは deep-research-preview-04-2026 のほうです。迷ったらまずこちらに置き換え、網羅性に不満が出た処理だけ Max に切り替える、という順番が手戻りの少ない進め方になります。

料金について、料金ページ の「Pricing for agents」は、エージェントのモデル推論を標準の Gemini 公開レートで課金し、ループ中の中間入力や推論トークンも含むと説明しています。ツール利用料は既存の料金体系どおりで、Search Grounding は取得トークンを課金対象から除き、URL Context と File Search は取得トークンも含みます。一方で、新旧エージェントそれぞれの個別料金や、Max と通常版の単価差は料金ページには記載がありません。代わりに Deep Research のドキュメント末尾に、プレビュー段階の概算としてコストの目安が載っています。標準版は 1 タスクあたり約 $1.00〜$3.00、Max は約 $3.00〜$7.00 で、いずれも変更の可能性があると明記されています。この目安どおりなら Max は標準版の 2〜2.3 倍ほどです。実額はタスクの内容で変わるため、Max に切り替えるときは実際の請求で確かめてください。

実機確認：models.list では旧 ID がまだ見える

停止が告知されたモデルは、モデル一覧から先に消えるのでしょうか。それを確かめるため、筆者は 2026-10-12 JST に Gemini API の models.list（GET。生成を伴わないため課金は発生しません）を実行しました。API キーはリクエストヘッダーに載せるだけで、出力には含めていません。

結果の抜粋が次のとおりです（モデル名・version・supportedGenerationMethods の順）。

HTTP 200
count 62
models/gemini-3.5-flash 3.5-flash-05-2026 ['generateContent','countTokens','createCachedContent','batchGenerateContent']
models/gemini-3.6-flash 3.6-flash-07-2026 [同上]
models/gemini-3.7-flash 3.7-flash-08-2026 [同上]
models/gemini-3.8-flash 3.0 [同上]
models/deep-research-max-preview-04-2026 deepthink-exp-05-20 ['generateContent','countTokens']
models/deep-research-preview-04-2026 deepthink-exp-05-20 ['generateContent','countTokens']
models/deep-research-pro-preview-12-2025 deepthink-exp-05-20 ['generateContent','countTokens']
nextPageToken: False

一覧は 62 件で、1 ページに収まりました。この時点で、停止予定の旧 ID も、新しい 2 つの ID も、置き換え対象の gemini-3.5-flash と gemini-3.7-flash も、すべて一覧に残っています。

この結果から言えることは 2 つあります。

  • 一覧に見えていることは「停止していない」ことしか示さない: 停止日の 11 日前でも旧 ID は普通に並んでおり、一覧の有無を移行の要否判断に使うと、停止当日まで何も気づけません。
  • 一覧から非推奨状態は読み取りにくい: 筆者が抽出して表示した項目（名前・version・supportedGenerationMethods）には、非推奨かどうかを示すものがありませんでした。62 件すべてのレスポンスの全フィールドを調べたわけではないため、state のようなフィールドが存在しないとまでは言えません。ただ、今回確認した範囲では一覧の監視で非推奨に気づける手がかりは見つからなかったので、非推奨の検知は changelog と deprecations ページの確認に頼るのが確実です。

一覧には説明のつかない点もありました。Deep Research の 3 つの ID はいずれも supportedGenerationMethods に generateContent が表示されています。しかし Deep Research のドキュメント は、Deep Research を Interactions API 経由でのみ利用でき、generate_content では使えないと記載しています。また 3 つの ID の version がいずれも deepthink-exp-05-20 で共通しています。どちらも原因は調べきれていないため、ここでは一覧の表示とドキュメントの記述が食い違っているという事実だけを示します。実装はドキュメントに従い、Interactions API で呼び出してください。

手元で同じ確認をする場合は、次のようなコマンドで一覧を絞り込めます。

curl -s "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  | jq -r '.models[] | select(.name | test("deep-research|flash")) | "\(.name) \(.version)"'

レスポンスに nextPageToken が含まれている場合は、続きのページが残っています。

移行手順

ここからの API の挙動は、公式ドキュメントの記述に基づきます。新しい ID で interactions.create を呼び出した結果は、本記事の執筆時点では実行していません。

1. 旧 ID の使用箇所を洗い出す

最初に、リポジトリ内のどこで旧 ID を使っているかを確認します。

grep -rn "deep-research-pro-preview-12-2025" .

設定ファイル、環境変数のデフォルト値、テストのフィクスチャ、ドキュメントのサンプルコードまで対象に含めます。本番コードだけを直してテストが旧 ID を参照し続けると、停止後にテストだけが失敗する状態になります。

2. agent パラメータを差し替える

changelog によると、移行方法は interactions.create の agent パラメータを新しい ID に変えることです。ID をコードに直書きせず、環境変数から読む形にしておくと、次の非推奨のときに設定変更だけで済みます。

import os
import time

from google import genai

# API キーは環境変数 GEMINI_API_KEY から読み込まれる
client = genai.Client()

# エージェント ID は設定から読む（既定は通常版）
AGENT_ID = os.environ.get("DEEP_RESEARCH_AGENT", "deep-research-preview-04-2026")

interaction = client.interactions.create(
    agent=AGENT_ID,
    input="Gemini API の非推奨ポリシーの変遷を調査してください",
    background=True,  # Deep Research では必須
)

while True:
    current = client.interactions.get(interaction.id)
    if current.status in ("completed", "failed"):
        break
    time.sleep(10)

if current.status == "completed":
    print(current.steps[-1].content[0].text)
else:
    print(f"調査が失敗しました: {current.error}")

Deep Research のドキュメントでは、agent にエージェント ID、input にクエリを渡し、background=True を必須としています。完了の判定は interactions.get をポーリングし、status が completed か failed になるまで待つ方式です。

3. レスポンスの読み取り位置を確認する

旧 ID から移行するコードでは、レスポンスを読む位置も確認してください。現行の Deep Research ドキュメントは、最終レポートの本文を steps[-1].content[0].text から取得する例を示しています。以前の記事（2026-03 執筆）では outputs[-1].text から取得するコードを載せていました。

この違いは、ID の切り替えではなく Interactions API のスキーマ変更によるものです。changelog によると、2026-05-06 の告知で Interactions API のリクエストとレスポンスのスキーマが outputs から steps に変わりました。新しいスキーマは 2026-05-26 に既定となり、旧スキーマは 2026-06-08 に削除されています。旧コードが outputs を参照している場合は、ID を替える前に steps[-1].content[0].text への修正が必要です。ただし新しい ID で interactions.create を実行した結果は確かめていないため、移行後に 1 回実行して本文の位置を確認してから本番に反映してください。

4. ストリーミングを使っている場合

ドキュメントによると、ストリーミングは stream=True と background=True を併用し、思考の要約が必要なら agent_config の thinking_summaries を "auto" にします。接続が切れたときに再接続できるよう、ストリームから受け取った interaction_id と last_event_id を保存しておく必要があります。

UI へのストリーミングを前提にしているなら、移行先は公式が「クライアント UI へのストリーミング向き」と説明する deep-research-preview-04-2026 が第一候補です。

5. 現行ドキュメントで変わった記述を反映する

以前の記事と現行の Deep Research ドキュメントを比べると、ID 以外にも記述が変わっている箇所があります。

項目 以前の記事（2026-03・旧 ID 前提） 現行ドキュメントの記述
本文の取得位置 outputs[-1].text steps[-1].content[0].text
既定のツール Google Search、URL Context Google Search、URL Context、Code Execution
MCP 非対応 MCP と File Search を指定可能
追加機能 記載なし collaborative_planning、visualization、画像・PDF 入力

既定のツールに Code Execution が加わっている点は、ツール利用料の見積もりに影響しうるため、移行時に料金ページと突き合わせておくと安心です。

Flash モデルとの違い：Deep Research には自動転送の記載がない

同じ 2026-10-08 の changelog には、Flash モデル 2 件の置き換えも載っています。

旧モデル 後継 changelog の記述
gemini-3.7-flash gemini-3.8-flash 非推奨。既存リクエストは自動で gemini-3.8-flash へ転送
gemini-3.5-flash gemini-3.6-flash 非推奨。既存リクエストは自動転送。モデル名の更新を推奨
deep-research-pro-preview-12-2025 2 種類から選択 非推奨。2026-10-23 に停止

Flash の 2 件は、何もしなくてもリクエストが後継へ流れると明記されています。これに対して Deep Research の旧 ID には転送の記載がなく、書かれているのは停止日だけです。同じ日の告知を Flash の感覚で読み、「放っておいても新しいほうに切り替わる」と受け取ると判断を誤ります。Flash 側も、changelog の推奨どおりモデル名を更新しておけば転送の有無を気にせずに済みます。

移行チェックリスト

停止日までに、次の項目を順に確認します。

  • deep-research-pro-preview-12-2025 の使用箇所を、本番コード・設定・テスト・サンプルまで洗い出した
  • 用途に応じて deep-research-preview-04-2026 か deep-research-max-preview-04-2026 を選んだ
  • agent パラメータを新しい ID に差し替え、ID を設定値から読む形にした
  • background=True とポーリング（completed / failed の判定）が入っている
  • 本文の取得位置を steps[-1].content[0].text に直し（旧スキーマの outputs は 2026-06-08 に削除済み）、新しい ID で 1 回実行して確かめた
  • ストリーミング利用時に interaction_id と last_event_id を保存している
  • Max を選んだ場合、公式の目安（約 $3.00〜$7.00/タスク）と実際の請求を突き合わせる段取りがある
  • gemini-3.5-flash / gemini-3.7-flash のモデル名も後継に更新した
  • 2026-10-23 より前に本番へ反映する日程を決めた
  • changelog と deprecations ページを定期的に確認する担当か仕組みを決めた

最後の項目は、models.list の結果から導いたものです。今回表示した項目には非推奨状態が出てこなかったため、次に新しい ID が非推奨になったときも、一覧の監視だけでは気づけない可能性があります。

検証できていない範囲

本記事で実際に実行したのは、2026-10-12 JST の models.list だけです。次の点は確認できていません。

  • 停止後の失敗の仕方: 2026-10-23 以降に旧 ID で interactions.create を呼んだとき、どのようなエラーが返るか
  • 実際の料金: 公式の概算（標準版 約 $1.00〜$3.00、Max 約 $3.00〜$7.00/タスク）はドキュメントで確認しましたが、実際の請求額は測っていません
  • ベースモデル: 新旧エージェントがどのモデルを基盤にしているか（以前の記事は旧 ID を Gemini 3.1 Pro ベースと書いていましたが、新しい ID については確認していません）
  • 一覧とドキュメントの食い違い: models.list が Deep Research の ID に generateContent を表示する一方、ドキュメントは Interactions API のみと記載している理由。3 つの ID の version が共通している理由
  • 関連ページ: 「Interactions breaking changes (May 2026)」「Migrate to Interactions API」と題したページの本文は確認していません（スキーマ変更の日付は changelog の記述に基づきます）
  • 移行後の動作: 新しい ID での interactions.create の実行結果。本文のコード例はドキュメントの基本例に沿っており、store は指定していません。バックグラウンド実行で store の指定が要るかは、ドキュメントの記述を読み取りきれていません

いずれも、移行作業の中で新しい ID を 1 回動かせば確かめられる項目が多いため、本番反映の前にステージングで確認してください。

おわりに

冒頭の問いに戻ると、直すべき箇所は agent パラメータの 1 行が中心で、加えてレスポンスの読み取り位置を確かめれば移行はほぼ終わります。難しいのは修正そのものより、動いているコードに停止日があると気づくことのほうです。2026-10-12 時点のモデル一覧には旧 ID が何事もなく並んでおり、一覧だけを見ていても非推奨には気づきにくい状態でした。

旧 ID を使っているなら、2026-10-23 という日付は「この日より前には止まらない」最短の日付として扱い、それより前に差し替えを済ませておくのが安全です。新しい 2 つの ID も停止日は未発表のプレビューなので、ID を設定値に逃がしておくことが、次の移行を軽くします。

関連記事

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?