チュートリアル2026年3月30日by K.hirano

Gemini 2.5→3.1 移行失敗の原因Top3と即使える代替コード

Gemini Live API 2.5系から3.1へ移行すると壊れやすい3点を整理。非同期関数、thinkingBudget、プロアクティブ音声の変更点と代替実装をまとめます。

#gemini live api#移行#音声エージェント#tutorial

Gemini Live API を 2.5 → 3.1 に上げると、非同期関数呼び出し・thinkingBudget・プロアクティブ音声の3つが廃止されてコードが壊れます。Google は「drop-in upgrade として扱うな」と公式に明記。本記事では各廃止理由と代替実装を解説します。

対象モデル: gemini-3.1-flash-live-preview / 情報基準日: 2026-03-26（Google公式発表日）

まず前提：3.1 は「上位互換の差し替え」ではない {#前提}
2.5 → 3.1 変更点一覧表 {#変更表}
Top1: 非同期関数呼び出しが廃止された {#top1}
Top2: thinkingBudget は thinkingLevel に変わった {#top2}
Top3: プロアクティブ音声が廃止された {#top3}
移行の実務チェックリスト {#checklist}
こういう人は今すぐ上げない方がいい {#wait}
私ならどう判断するか {#judgement}
まとめ：壊れる前提で、先に逃がす
よくある質問 {#faq}
参考リンク
関連記事
この記事を書いた人

まず前提：3.1 は「上位互換の差し替え」ではない {#前提}

ここを最初に押さえないと、移行判断を誤ります。

2.5系でうまく動いていた音声エージェントは、たいてい次の3層に分かれています。

会話制御
ツール呼び出し
音声の自律動作

3.1 ではこのうち、ツール呼び出しのやり方と発話の自動化と推論コントロールが変わっています。つまり、見た目は同じ「Live API」でも、内部の設計前提が少し違う。

なので、移行の順番はこうです。

まず壊れる箇所を特定する
次に代替実装へ置き換える
最後に音声フロー全体を再検証する

ここを飛ばして「型だけ直す」と、あとで会話の途切れや無音、ツール実行の詰まりが出ます。これは現場でかなり面倒です。

2.5 → 3.1 変更点一覧表 {#変更表}

設定・機能	2.5系	3.1系	影響度
非同期関数呼び出し	✅ 対応	❌ 廃止	高：ツール構成の再設計が必要
thinkingBudget	`thinkingBudget: 256`（数値）	`thinkingLevel: "medium"`（段階）	中：設定ファイルの修正が必要
プロアクティブ音声	✅ 対応	❌ 廃止	高：UXの再設計が必要
出力トークン上限	8,192	65,536（8倍）	プラス変更
対応言語数	24言語	90言語以上	プラス変更
コンテキスト長	—	131,072トークン	プラス変更

Top1: 非同期関数呼び出しが廃止された {#top1}

何が変わったか

非同期、と聞くとなんとなく「賢そう」な印象がありますが、3.1 は「賢くやるより、素直にやれ」という設計に寄っています。

2.5系では、会話を止めずにツール実行を待つような設計を組めました。ところが 3.1 では、非同期関数呼び出しが廃止され、同期的な扱いに寄ったと理解しておくのが安全です。

要するに、「呼び出しておいて裏で待つ」前提のコードが危ないです。

ポイント: 2.5系で「非同期ツール呼び出し」を使っていた実装は、3.1 では動作保証がない。ツール数が多いほど影響範囲が広い。

どんなときに壊れるか

よくあるのはこのパターンです。

天気取得やDB参照をバックグラウンドで走らせる
返答生成を続けながら、ツール結果だけ後から差し込む
複数のツールを並列で投げて、結果を順番に束ねる

2.5系ではこれで通っていた実装が、3.1 では期待通りに進まないことがあります。

代替方針

基本はシンプルです。ツール結果が必要なら、その場で待つ設計に寄せる。

会話ターンを区切る
ツール結果が返るまで次の応答を進めない
非同期の「裏回し」はアプリ側で制御する

Before / After

Before（2.5系・動作するが3.1では危険）

python

# 裏で走らせて後で回収 → 3.1では期待通りに動かない可能性
async def handle_user_input(user_input):
    tool_future = asyncio.create_task(fetch_weather(user_input))
    # ツール結果を待たずに会話を続ける
    response = model.generate_response_stream(conversation_state)
    weather_result = await tool_future  # 後から差し込む

After（3.1対応・同期寄りに再設計）

python

# ツール結果が返るまで待つ設計
def handle_user_input(user_input):
    result = tool_call_sync(user_input)
    if result is None:
        raise RuntimeError("tool call failed")
    response = model.generate_response(
        conversation_state=conversation_state,
        tool_result=result,
    )

ポイントは、モデルに非同期の都合を押し付けないことです。

音声エージェントでやるなら、特に「ユーザーが話している最中に何かを返す」系の体験は、アプリのイベント制御に寄せた方が安定します。

この変更が効く場面

予約、注文、在庫確認など、外部I/Oが多い音声エージェント
1回の応答で複数ツールを叩く構成（影響が出るのはここ。ツール1本なら変更量は最小限）
会話中のレスポンス遅延を厳密に管理したいケース

不要な人

そもそもツール呼び出しを使っていない人
単純な音声入出力だけのデモアプリ

Top2: `thinkingBudget` は `thinkingLevel` に変わった {#top2}

何が変わったか

これは地味ですが、移行時にハマりやすいです。

2.5系で使っていた thinkingBudget は廃止方向で、3.1 では thinkingLevel に置き換わっています。

つまり、これまでの「何トークン考えさせるか」という発想から、どの程度考えさせるかへ寄った、と見ておくとわかりやすいです。

何が困るか

thinkingBudget をそのまま残すと、設定が無視されるか、エラーになるか、少なくとも期待通りに効かない可能性があります。

そして厄介なのは、エラーで落ちないのに品質だけ変わることです。音声エージェントはこれが一番やっかいです。レスポンスは返るのに、要約が浅い、ツール選択が雑、説明が不安定、みたいな症状になります。実際に試したところ、thinkingBudget を指定したまま 3.1 を呼び出してもエラーは一切出ず、minimal 相当の動作になっていました。

ポイント: thinkingBudget の残骸は「サイレントに効かなくなる」。エラーログに出ないぶん、気づかないまま品質劣化が続く可能性がある。

Before / After

Before（2.5系）

python

config = {
    "thinkingBudget": 256,  # トークン数で指定
}

After（3.1対応）

python

config = {
    # thinkingBudget は削除
    "thinkingLevel": "medium",  # low / medium / high で指定
}
client = live_api_client.configure(
    model="gemini-3.1-flash-live-preview",
    generation_config=config,
)

ここで大事なのは、単純に名前を置換して終わりにしないことです。

thinkingBudget は「どれだけ考えるか」を数値で縛る発想でしたが、thinkingLevel は運用上の感覚が少し違います。なので、移行後は以下を見ます。

応答の遅延
ツール選択の精度
返答の詳細度
長文指示への追従性

どんなときに効くか

会話品質と遅延のバランスを詰めたい音声エージェント
推論コストを雑に増やしたくないケース
本番で「なんとなく賢い」より、再現性を優先したいケース

不要な人

低頻度の社内デモだけで、品質差が問題にならない人

Top3: プロアクティブ音声が廃止された {#top3}

何が変わったか

これが一番体験に効きます。

プロアクティブ音声は廃止です。つまり、モデルが勝手に話し出す前提で作ったフローは、そのままでは成立しません。

2.5系で「沈黙を埋める」「先に気の利いた一言を返す」「ユーザー入力待ちの間に自然に話す」ような体験を作っていた場合、3.1 ではそのまま再現しづらいです。

どこが壊れるか

無音を埋めるための自動発話
ユーザーの入力完了前の先回り発話
状況に応じてモデルが自律的に話し始める演出

これらは、単にUIの見た目ではなく、会話の主導権をモデルに預けていた実装です。そこを3.1では見直す必要があります。

代替方針

代替は、モデルに任せるより アプリ側でイベント駆動にする ことです。

マイク入力開始・停止をアプリで持つ
無音時の文言はルールベースで出す
「今考えています」「少し待ってください」などの補助音声は明示的に発火する

Before / After

Before（2.5系・モデルが自律的に話す）

javascript

// モデルが無音を検知して自動発話していた（3.1では動かない）
const session = await liveApi.connect({ proactiveAudio: true });

After（3.1対応・アプリ側でイベント制御）

javascript

function onUserSilence(timeoutMs) {
  // アプリ側で明示的にTTSを発火する
  playTTS("少し確認しています。お待ちください。");
}

function onToolPending() {
  playTTS("情報を取得しています。");
}

function onModelReady(text) {
  playTTS(text);
}

この設計にすると、体験は少し機械的になります。そこは正直に言うと、2.5系の"それっぽさ"は減ることがあります。

ただし、その代わりに得られるのは、挙動の予測しやすさです。音声エージェントは、予測しやすさの方が本番では大事な場面が多いです。

どんなときに効くか

コールセンター補助
社内案内ボット
手順誘導系の音声UI

不要な人

「モデルが勝手に気を利かせる」演出を最優先する実験用途

移行の実務チェックリスト {#checklist}

ここはそのままチームに共有しても使えるように、確認項目だけ並べます。

1. 非同期関数呼び出しの確認

ツール呼び出しを裏で待つコードが残っていないか
並列実行前提の処理を、同期フローへ落とせるか
ツール結果の遅延時に会話が破綻しないか

2. thinking 設定の確認

thinkingBudget が設定ファイルに残っていないか（grep で全プロジェクト確認推奨）
thinkingLevel の値を本番相当で試したか
応答速度と品質の両方を再計測したか

3. 音声フローの確認

プロアクティブ音声依存のUXがないか
無音時の補助発話をアプリ側で出せるか
ユーザー発話中にモデルが割り込まないか

こういう人は今すぐ上げない方がいい {#wait}

ここは大事です。移行は常に正義ではありません。

次のどれかに当てはまるなら、3.1 を急いで入れる理由は薄いです。

2.5系で音声フローがすでに安定している
ツール呼び出しと音声演出を強く結びつけている
QA の余力がなく、回帰検証が十分にできない
「差し替えだけ」で済むと考えている

逆に、次の人は移行検討の価値があります。

3.1 の制約を前提に設計を組み直せる
ツールフローを整理したい
音声UXより、運用の安定性を優先したい

私ならどう判断するか {#judgement}

ちょうどDIYで棚を作り直すときに似ています。「ネジ1本替えるだけ」のつもりが、開けてみたら設計ごと変わっていた、という体験です。

現場目線で言うと、2.5系から3.1への移行は、仕様差分を埋める作業というより、会話制御の再設計です。

特に、

非同期ツール
自動的な気の利いた発話
推論量の細かな調整

この3つに依存していたなら、移行コストはそれなりに出ます。

一方で、ここを整理できるなら、コードはむしろ読みやすくなります。モデルに曖昧な役割を持たせず、アプリ側で責任分界を持つ形です。地味だけど、本番ではこちらの方が断然強い。

本記事の内容はGoogle公式ドキュメントと公式発表（2026-03-26）をもとに構成しています。プレビュー段階のため、GA時に仕様が変更される可能性があります。

まとめ：壊れる前提で、先に逃がす

Gemini Live API 2.5→3.1 の移行でまず見るべきは、次の3つです。

非同期関数呼び出しの廃止 → ツール実行は同期寄りに再設計する
thinkingBudget の廃止 → thinkingLevel に合わせて品質を再調整する
プロアクティブ音声の廃止 → 自動発話はアプリ側のイベント制御へ移す

Google が drop-in upgrade として扱うな、と明記している以上、これは「軽いアップデート」ではありません。

移行前にやるべきことは、コードを一気に置換することではなく、壊れる3点を先に洗い出し、代替実装を切って、回帰テストの観点を決めることです。

読者のチームで共有するなら、この記事のチェックリストから始めてください。そこから、実際にどの会話フローが壊れるかを一つずつ潰していくのが一番早いです。

今回の変更は、派手さはありませんが、音声エージェントの本番運用ではかなり効きます。逆に言うと、ここを雑に見ると、あとで地味に苦しむ。それだけ。

よくある質問 {#faq}

Q. Gemini 2.5 Flash Live はいつまで使えますか？

A. 現時点（2026-03-26）では廃止時期は公式発表されていません。3.1はプレビュー段階のため、GA後も2.5が一定期間並行提供される可能性があります。公式ドキュメントで最新情報を確認してください。

Q. 3.1 はすでに本番利用できますか？

A. 現在は gemini-3.1-flash-live-preview というプレビューステータスです。本番環境での利用は自己判断になります。GAアナウンス後に改めて移行を検討するのが安全です。

Q. thinkingLevel の有効な値は何ですか？

A. 公式では low / medium / high が使用可能とされています。ただしプレビュー段階のため、GA時に変更される可能性があります。公式ドキュメントで常に最新仕様を確認することを推奨します。

参考リンク

この記事を書いた人

HW系エンジニアとして20年以上、10,000件を超える顧客訪問と2,000件を超える単独ソリューション実績。AIツールを使った個人開発やIoT農園など、Raspberry Piを使ったオートメーション化なども実践中です！エンジニア専門結婚相談所も運営中、ClaudeCodeで解決できない心の課題も解決いたします！