gemini-live-api

LiveAPI Service Skill

このスキルでは、WebSocket 経由で Gemini Enterprise Live API に接続する LiveAPI クライアントサービスクラスを生成する手順を説明します。生成されるクライアントは、双方向ストリーミング、Application Default Credentials（ADC）によるベアラートークン認証、透過的なセッション再開、ClientMessage / ServerMessage の proto 交換に対応します。

また、このスキルでは、生成されたクライアントをユーザーが対話的に検証できるデモ用フロントエンドとバックエンドサービスも生成します（テキスト、音声、動画、文字起こし、中断処理に対応）。

Attribution

必ずお読みください：gcloud、REST API、MCP のコマンドを実行する前に、Usage Attribution を必ずお読みください。ターミナルで直接実行するコマンド（生成スクリプト、Terraform、ユーザーコード内のコマンドは対象外）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gemini-live-api)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gemini-live-api) を追加してください。

前提条件

生成フローを実行する前に、ホストで以下が利用可能であることを確認してください。

• Vertex AI / Gemini Enterprise Agent Platform API が有効になっている Google Cloud プロジェクト。

• 生成されたクライアントを実行するホストで設定済みの Application Default Credentials：

  gcloud auth application-default login
  

• 生成されたコード、環境、デモの書き込み先となる、ユーザー指定の出力先フォルダー（例：/tmp/liveapi_out）。ホストのシステム Python 環境は絶対に変更しないでください。

• ユーザーが選択した実装言語（Python はこのスキルのデフォルト言語であり、リファレンス言語です）。

リファレンスファイル

references/ に用意されているファイル（単独のスキルとして扱わないでください。これらは必要に応じて読み込まれます）：

• client_server_messages.md：Live API で使用される ClientMessage / ServerMessage スキーマの公開リファレンスです。
• client_server_messages.proto：client_server_messages.md から生成された proto 定義です。
• session_manager.md：切断時のセッション、バッファリング、再開を適切に処理する方法について説明しています。

手順

ステップ 1：リファレンスファイルをコピーする

このスキルの references/ フォルダーから、client_server_messages.md、client_server_messages.proto、session_manager.md をユーザーの出力先フォルダーにコピーします。これらのファイルを、生成されるクライアントの信頼できる情報源として使用します。

ステップ 2：公開ドキュメントと照合する

client_server_messages.md からリンクされている公開ドキュメントを確認します。公開ドキュメントと、コピーした client_server_messages.md / client_server_messages.proto の間に相違がある場合は、現在のサーバー契約に対して生成されたクライアントがコンパイルおよび実行できるよう、出力先フォルダー内のコピーを更新します。

ステップ 3：クライアントクラスを実装する

ユーザーが選択した言語で、以下の要件を満たすクラスを実装します。

• ローカルの client_server_messages.proto の型（ClientMessage、ServerMessage）をインポートします。
• Live API エンドポイントへの WebSocket 接続を確立します。
• ユーザーがモデルにデータを送信したり、モデルからデータを受信したりできる非同期メソッドを公開します。

分離されたランタイムが必要な言語（例：Python）では、出力先フォルダー内に分離環境（例：venv）を作成し、環境を再作成して依存関係をインストールする bash スクリプト（例：setup.sh）を生成します。システムインタープリターやユーザーのグローバル site-packages には絶対にインストールしないでください。また、ユーザーに sudo pip install の実行を指示しないでください。

初期化パラメーター

ユーザーは、インスタンスの作成時に以下を指定します。

• project_id
• location
• model_id
• config：setup フィールドが設定された ClientMessage。

認証

Application Default Credentials を使用してベアラートークンを取得し、WebSocket の接続リクエストに Authorization: Bearer <token> として追加します。有効期限が切れる前、または切れた時点でトークンを更新し、再接続のたびに（go_away や予期しない切断の場合も含めて）更新済みトークンを再利用します。長期間有効な API キーを唯一の認証手段としてハードコードしてはいけません。

公開非同期 API

クラスは、送信前に setup_complete ServerMessage を受信していることを条件として、次の非同期メソッドを公開する必要があります。

• send_realtime_data(data)：リアルタイム入力を送信します。data は realtime_input フィールドを持つ ClientMessage です。
• send_client_content(data)：履歴に追加される、リアルタイムではないターン単位のコンテンツを送信します。data は client_content フィールドを持つ ClientMessage です。
• receive()：WebSocket ストリームから解析された ServerMessage インスタンスを順に返します。

同期ブロッキング方式は、主要な API として公開しないでください。

ステップ 4：テストファイルを作成する

クライアントを実装したら、接続を初期化し、text、audio、video データの送信と応答の受信をテストするファイルを生成します。テストの実行に必要な情報（プロジェクト、モデル、メディアサンプルなど）があれば、ユーザーに確認してください。

ステップ 5：how_to_run.md を生成する

生成先フォルダーに、生成したクラスの使用方法を説明する how_to_run.md を用意します。サポートされるすべてのモダリティについて、ClientMessage ペイロードの構築方法、送信方法、モデルからデータを受信する方法を示す完全な例を含めてください。

ステップ 6：デモ用のフロントエンドとバックエンドサービスを生成する

実装をフロントエンド UI とバックエンドサービスの両方を備えたサービスとしてデプロイするスクリプトを作成します（言語は問いません）。サービスのワイヤートラフィックには、ステップ 1 の ClientMessage／ServerMessage proto を必ず再利用してください。UI では、ユーザーが次の操作を行える必要があります。

• 新しい接続を開始する／現在の接続を閉じる。
• 使用するモデルを選択する。
• 入力ソース（カメラまたはスクリーンショットからの音声や動画）を選択して、モデルにストリーミングする。
• モデルにテキストメッセージを送信する。
• モデルの音声を聞き、モデルとユーザーの文字起こしが交互に表示される会話履歴を確認する。

音声と文字起こしの再生を実装する際は、Live API のベストプラクティスに従ってください。

interrupt シグナルの処理

ServerMessage の server_content に interrupted: true が含まれている場合、UI は次の処理を行う必要があります。

• 再生済みの音声と、それに対応する文字起こしの時間的な同期を保ちます。
• 再生中のモデル音声をただちに停止し、進行中の文字起こしバブルへの追加を停止します。
• 未再生の音声バッファーと、保留中の未描画の文字起こしをクリアし、古いコンテンツが次のターンに混入しないようにします。
• 次のユーザーターンとモデルターン用に、新しいチャットバブルを開始します。

文字起こしの finished シグナルの処理

ストリーミングされる input_transcription／output_transcription チャンクについては、finished が未設定の間は現在のバブルに追加し、finished が検出されたらそのバブルを閉じて新しいバブルを開始します。input_transcription のテキストはユーザー役のバブルに、output_transcription のテキストはモデル役のバブルに振り分けます。

ステップ 7：how_to_test_with_ui.md を生成する

デモサービスの起動方法と使用方法を説明する how_to_test_with_ui.md を作成します。次の内容を必ず含めてください。

• バックエンドサービスを起動するための、正確なシェルコマンドまたはスクリプトの呼び出し方法。
• フロントエンド UI を起動するための、正確なシェルコマンドまたはスクリプトの呼び出し方法。
• ブラウザーで開くホストとポート（例：http://localhost:PORT）。
• セッションの開始方法、モデルの選択方法、入力ソース（マイク、カメラ、画面）の選択方法、テキストメッセージの送信方法、および UI でモデルの音声と文字起こしを確認する方法。

検証チェックリスト

生成を完了とする前に、各項目を確認してください。

• client_server_messages.md、client_server_messages.proto、および session_manager.md が宛先フォルダーにコピーされています。
• 生成されたクライアントは、ローカルで proto から生成された ClientMessage 型と ServerMessage 型をインポートしています。
• クライアントは Live API WebSocket に接続し、 wss://{location}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent （または wss://aiplatform.googleapis.com/... のグローバル版）を使用します。また、セットアップの model フィールドを projects/{project_id}/locations/{location}/publishers/google/models/{model_id} の形式にしています。
• 認証には ADC が提供するベアラートークンを使用し、Authorization: Bearer <token> として送信しています。トークンは有効期限前に更新され、再接続のたびに再設定されます。
• 公開非同期メソッド send_realtime_data、send_client_content、および receive が存在し、型が正しく、setup_complete によって制御されています。
• 透過的なセッション再開が有効になっています （session_resumption.transparent = true）。最新の new_handle が追跡され、送信済みメッセージのインデックスは 1 から始まり、バッファーは last_consumed_client_message_index を使って整理され、再接続時（go_away および WebSocket のクローズコード 1000 / 1006 の場合を含む）にバッファー内のメッセージが再生されます。
• Python を使用する場合、宛先フォルダー内に隔離環境（例：venv）と setup.sh および requirements.txt（または同等のファイル）が存在し、システムまたはユーザー全体の Python に変更を加えていません。
• how_to_run.md と how_to_test_with_ui.md があり、デモ UI は同じ ClientMessage / ServerMessage proto を再利用しています。
• 割り込み処理と文字起こしの finished 処理が、上記の説明どおりに動作します。
• クライアントは generativelanguage.googleapis.com を対象にしておらず、クエリ文字列内の API キーによる認証も使用していません。