ライブエージェント向けサポート対象モデル¶
ライブエージェントには双方向接続を維持できるモデルが必要であり、標準の Gemini モデルでは対応できません。ライブエージェント以外で ADK がサポートするモデル、および非 Gemini プロバイダーについては、エージェント用モデル を参照してください。
ライブモデル¶
ライブエージェントは、中間の Text-to-Speech（音声合成）段階を経由せず、音声を入力として受け取り音声を直接出力するモデル上でエンドツーエンドで実行されます。これにより、自然な抑揚（プロソディ）を持つ人間のような音声が実現されます。これは、標準の Gemini モデルが双方向接続上で実行できないことです。
同じモデルでもバックエンドごとに異なる ID を持ちます。
| モデル | AI Studio | Agent Platform |
|---|---|---|
| Gemini 2.5 Flash Live | gemini-2.5-flash-native-audio-preview-12-2025 (Preview) |
gemini-live-2.5-flash-native-audio (GA) |
| Gemini 3.1 Flash Live | gemini-3.1-flash-live-preview (Preview) |
利用不可 |
Gemini 2.5 Flash Live はバックエンドごとに異なる ID を持つ単一のモデルであり、提供される機能は同じです。gemini-live-2.5-flash-native-audio は ADK の LlmAgent.DEFAULT_LIVE_MODEL であり、一般公開されている唯一の Live モデルであり、このセクションの例で使用されているモデルです。
Gemini 3.1 Flash Live はより新しいモデルで低レイテンシですが、AI Studio 専用であり、2.5 が持つ機能の一部が削除されています。切り替える前に モデルごとの機能サポート を確認してください。
バックエンドの選択¶
ライブモデルには 2 つのバックエンドのいずれかを介してアクセスします。ADK は同じコードで両方と通信します。環境変数で切り替えることができるため、一方の開発環境で開発し、もう一方の本番環境にデプロイできます。
| AI Studio | Agent Platform | |
|---|---|---|
| 正式名称 | Google AI Studio | Gemini Enterprise Agent Platform |
| 最適な用途 | プロトタイピング、開発 | 本番運用、エンタープライズ |
| 認証 | API キー (GOOGLE_API_KEY) |
Cloud 認証情報 (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) |
| セットアップ | API キーのみ | Cloud プロジェクトのセットアップ |
| 制限 | セッション時間と同時実行数 | セッション時間と同時実行数 |
GOOGLE_GENAI_USE_ENTERPRISE 環境変数（AI Studio は FALSE、Agent Platform は TRUE）で切り替えます。コードの変更は不要です。セットアップについては クイックスタート を参照してください。
Agent Platform: global ロケーションはサポートされていません
ライブモデルは GOOGLE_CLOUD_LOCATION=global では利用できません。us-central1、us-east1、または asia-northeast1 などのリージョン エンドポイントを使用し、デプロイする前に Agent Platform のロケーション のエンドポイントとロケーションの対応表で確認してください。
これらのモデルは、自然なプロソディを持つ音声を直接生成し、会話の言語を独自に検出します。音声、文字起こし、ターン検出など、その上に設定する項目については 設定 で説明されています。
モデルレベルで固定されている特性が 1 つあります。ライブモデルは音声のみを出力します。TEXT レスポンスモダリティをサポートしていないため、発話とともにテキストを取得するには 音声の文字起こし を使用します。
モデルごとの機能サポート¶
一部の RunConfig およびツール設定は、実行しているモデルに依存します。
| 機能 | Gemini 2.5 Flash Live | Gemini 3.1 Flash Live |
|---|---|---|
| プロアクティブおよび感情的な対話 | RunConfig によるオプトイン |
サポートされていません |
ツールの response_scheduling |
サポート | サポートされていません。関数呼び出しは同期式であるため、ツールのレスポンスが返されるまでモデルは沈黙します |
| 思考制御 (Thinking control) | thinking_budget |
thinking_level (minimal, low, medium, high) |
2.5 から 3.1 への移行時の注意
RunConfig.proactivity または RunConfig.enable_affective_dialog を設定したままにすることが最も一般的なアップグレード失敗の原因です。これらを削除してください。また、クライアント コードに影響する 2 つの相違点があります。1 つ目は、単一のサーバー イベントが複数のコンテンツ パートを一度に運ぶことができるようになったため、parts[0] を読み取るのではなく event.content.parts を反復処理してください。2 つ目は、ターンの対象範囲に検出されたすべての音声アクティビティとビデオ フレームがデフォルトで含まれるようになり、ビデオを連続してストリーミングする場合にトークン コストが変化します。アップストリームの 移行ガイド を参照してください。
プラットフォームの制限と割り当て¶
両方のバックエンドで、接続とセッションの実行時間、および同時に実行できるセッション数に上限が設けられています。これらの数値は変更される可能性があるため、アップストリームの公式ドキュメントを正式な情報源として扱い、本番環境で制限に依存する前に確認してください。
| 制限 | AI Studio | Agent Platform |
|---|---|---|
| セッション時間（音声のみ） | 15 分 | 15 分 |
| セッション時間（音声 + 動画） | 2 分 | 2 分 |
| 接続の存続時間 | 約 10 分 | 約 10 分 |
| 同時実行セッション数 | レート制限 を参照 | 従量課金制でプロジェクトあたり最大 1,000。プロビジョニングされたスループットの場合は無制限 |
Agent Platform では、上記の音声のみの制限とは別に、会話セッションがデフォルトで 10 分に制限されます。
コンテキストウィンドウの圧縮 を有効にすると、セッションを期間制限を超えて延長できます。Agent Platform では、Cloud Console の割り当てページ の 「Bidi generate content concurrent requests」 から同時セッション数の増加をリクエストできます。最新の数値については、AI Studio、Gemini API のレート制限、および Agent Platform のドキュメントを確認してください。
モデル名の扱い方¶
モデル名をハードコードするのではなく、環境変数から読み取ります。同じモデルでも AI Studio と Agent Platform で ID が異なるため、.env 変数を使用することで 1 つのコードベースで両方のバックエンドに対応でき、モデルの非推奨化（deprecation）からも保護されます。
推奨パターン:
import os
from google.adk.agents import Agent
# 適切なデフォルト値へのフォールバックを伴う環境変数の使用
agent = Agent(
name="my_agent",
model=os.getenv("DEMO_AGENT_MODEL", "gemini-live-2.5-flash-native-audio"),
tools=[...],
instruction="..."
)
環境変数を使用する理由:
- バックエンド固有の ID: 同じモデルでも AI Studio と Agent Platform で名前が異なるため、両者間を移動するにはモデル ID を変更する必要があります。環境変数を使用することで、コードからそれを排除できます。
- モデルの利用可能性の変化: モデルは定期的にリリースされ、非推奨化されます。1年前に書かれたライブエージェントが、存在しなくなったモデルにコード上で固定されるべきではありません。
- 環境固有の設定: 開発、ステージング、本番の各環境で異なるモデルを使用します。
.env ファイルの設定:
# AI Studio
DEMO_AGENT_MODEL=gemini-2.5-flash-native-audio-preview-12-2025
# AI Studio（プロアクティビティ、感情対話、ノンブロッキングツールが不要な場合）
# DEMO_AGENT_MODEL=gemini-3.1-flash-live-preview
# Agent Platform
# DEMO_AGENT_MODEL=gemini-live-2.5-flash-native-audio
環境変数の読み込み順序
python-dotenv で .env ファイルを使用する場合、環境変数を読み取るモジュールをインポートする前に load_dotenv() を呼び出す必要があります。そうしないと、os.getenv() は None を返し、.env の設定を無視してデフォルト値にフォールバックします。
main.py での正しい順序:
from dotenv import load_dotenv
from pathlib import Path
# エージェントをインポートする前に .env ファイルをロード
load_dotenv(Path(__file__).parent / ".env")
# これで環境変数を使用するモジュールを安全にインポート可能
from google_search_agent.agent import agent
間違った順序（機能しません）:
from dotenv import load_dotenv
from google_search_agent.agent import agent # エージェントはここで環境変数を読み取ってしまう
# 遅すぎます！ エージェントはすでにデフォルトモデルで初期化されています
load_dotenv(Path(__file__).parent / ".env")
これは Python のインポート動作によるものです。モジュールをインポートすると、そのトップレベルコードが即座に実行されます。エージェントモジュールがインポート時に os.getenv("DEMO_AGENT_MODEL") を呼び出す場合、.env ファイルはすでに読み込まれている必要があります。
適切なモデルの選択:
- バックエンドの選択: プロトタイピングには AI Studio、本番環境には Agent Platform を選択します。これにより、上の表の ID 列が決まります。また、Agent Platform ではモデルも決定されます（Gemini 2.5 Flash Live がそこにある唯一の Live モデルです）。
- 現在の利用可能性の確認: 上のモデル表と公式ドキュメントを参照してください。
- 環境変数の設定:
.envファイルにモデル名を設定し、エージェント作成時にそこから読み取ります。
モデルの互換性と利用可能性¶
モデルの互換性と利用可能性に関する最新情報については、以下を参照してください。
- AI Studio: Gemini モデルドキュメント および Live API 機能ガイド
- Agent Platform: Live API の概要 および Agent Platform モデルドキュメント
本番環境にデプロイする前に、必ず公式ドキュメントでモデルの利用可能性と機能サポートを確認してください。