developer-device-platform-basics

開発者向けデバイスプラットフォーム

Developer Device Platform（DDP）は、幅広い種類の物理デバイスと仮想デバイスへのアクセスを提供する、Google の完全マネージド型グローバルインフラストラクチャです。

警告

Developer Device Platform（DDP）は現在プレビュー段階です。

重要

devicerun および devicestreaming のすべての API 操作（セッションの予約、ステータス確認、停止／キャンセル、更新、一覧表示）では、リンク先の .md ファイルに記載されている正確な手順と curl コマンドを必ず確認し、使用してください。

クレジット表記

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

認証とセットアップ

重要：リクエストを実行する前に、以下の手順に従って環境が正しく初期化されていることを必ず確認してください。

リクエストを実行する前に、gcloud 実行ファイルが存在するか確認してください。存在しない場合は、公式の Google Cloud CLI Installation Guide を参照して、現在のプラットフォーム（Linux、macOS、Windows など）にインストールしてください。

1. Google Cloud 認証：Google Cloud の認証情報で認証し、Developer Device Platform 用のアクティブな Application Default Credentials（ADC）を設定します。

   gcloud auth login --no-browser
   gcloud auth application-default login --no-browser
   

2. API を有効にする（まだ有効になっていない場合）：

   gcloud services enable devicerun.googleapis.com devicestreaming.googleapis.com testing.googleapis.com --quiet
   

メモ

プレビュー期間中、Device Streaming API には Cloud Testing API が必要です。

3. gcloud beta コンポーネントを有効にする：

   gcloud components install beta
   

4. 環境変数を設定する：必要なプロジェクト変数とアクセストークンを設定します。

   export PROJECT_ID=$(gcloud config get project)
   export ACCESS_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
   

5. Python 環境：Python 仮想環境のセットアップ手順については、start_adb_forwarder.md を参照してください。

使用可能なデバイスの一覧表示

セッションの開始時に使用する正しい modelCode と osVersion を確認するには、使用可能なデバイスを一覧表示します。

1. モデルの一覧表示：使用可能な Android デバイスモデルを一覧表示するには、次のコマンドを実行します。

   gcloud beta device-run devices list
   

   特定のデバイスを説明するための CATALOG_ID パラメーターの値は、ID 列から確認してください（例：shiba-36）。

2. モデルの詳細表示：API リクエストを実行して、特定のモデルの詳細（supportedProducts、解像度など）を取得します。必ず describe_device.md に記載されている正確な curl コマンドと手順に従ってください。

デバイスセッションの開始

ユーザーからデバイスの予約または接続を求められた場合：

1. デバイスの空き状況を確認する：

   Listing Available Devices の手順に従って、デバイスの CATALOG_ID を調べます。describe_device.md に記載されている正確な curl コマンドと手順を使用して、CATALOG_ID のデバイスの空き状況を確認します。予約するには、デバイスの supportedProducts に「deviceStreaming」が含まれている必要があります。

   特定のデバイスが指定されていない場合は、CATALOG_ID=shiba-34（SDK 34 の Pixel 8）を使用します。

   ユーザーが OS_VERSION を指定していない場合は、デバイスリストからバージョンを選ぶようユーザーに依頼します（空き状況が最も高いバージョン {"available": "AVAILABILITY_HIGH" } を優先します）。

   OS_VERSION が deviceStreaming で利用できない場合は、予約しないでください。代わりの OS_VERSION をユーザーに尋ねます。

2. パラメーターを抽出する：

   • model_id：デバイスの詳細にある modelCode。必須です。
   • version_id：デバイスの詳細にある osVersion。必須です。

3. デバイスを予約する：

   ルール：ユーザーの明示的な確認が必須です。デバイスの予約には課金が発生し、クラウドリソースが作成されます。エージェントは、現在の Google Cloud プロジェクト（例：${PROJECT_ID}）に発生する課金について、必ずユーザーに明示的に警告しなければなりません。セッション作成コマンドを実行する前に必ず停止し、明示的な承認を求めてください。

   その後、model_id と version_id を指定して API リクエストを実行し、デバイスを予約します。reserve_device.md に記載されている正確な curl コマンドと手順に必ず従ってください。

   レスポンスを解析して session_name（セッション名。例：projects/${PROJECT_ID}/deviceSessions/session-xxxxxx）を取得します。予約に失敗した場合は、エラーを報告します。

4. セッションがアクティブになるまで待機する：

   デバイスセッションがプロビジョニングされる間、"state" が "ACTIVE" になるまでセッションの状態をポーリングします。正確な curl コマンドについては、session_status.md を参照してください。

   API のレート制限に達しないよう、この確認を 5 秒ごとに繰り返します。通常は 1 分以内ですが、2 分以内にアクティブにならない場合は、失敗を報告してセッションをキャンセルします。アクティブになったら、セッション JSON レスポンスから expireTime を取得し、ユーザーの現地時間に変換して、人が読みやすい形式（例：「2026年6月9日午後2時44分 PDT」）で表示します。

5. 接続フォワーダーを開始する：ADB フォワーダースクリプトを開始して、リモートデバイスへの接続を転送します。start_adb_forwarder.md に記載されている正確なコマンドと手順に必ず従ってください。コマンド ID を必ず記録します。

6. オンラインになるまで待機し、ポートを解析する：フォワーダーがオンラインになるまで待機し、待ち受けポートを取得します。start_adb_forwarder.md に記載されている正確なロジックと手順に必ず従ってください。

7. ユーザーに手順を案内する：

   オンラインになったら、adb -s localhost:{port} shell getprop ro.product.model を実行して、デバイスのモデル名を取得します。その後、次の手順を記載したメッセージをチャットでユーザーに直接表示します（アーティファクトファイルは作成しないでください）。

   デバイスの準備ができました！

   Device Model: {device_model}
   OS Version: {version_id}
   ADB Address: localhost:{port}
   Session Expiration: {expire_time_human_readable_local}
   

8. セッションの状態を保存する：後でクリーンアップできるよう、{session_name} と {command_id} を会話のメモリ／コンテキストに保存します。

予約済みデバイスの画面を表示する

コーディングエージェントは、adb を使用してリモートデバイスを直接操作できます。ユーザーはユーティリティを使って画面を表示し、DDP で予約済みデバイスを手動で操作できます。ユーティリティの例については、view_device.md を参照してください。

デバイスセッションの停止

ユーザーからデバイスの停止、クリーンアップ、または解放を依頼された場合：

1. セッションの特定：コンテキストからアクティブな {session_name} と {command_id} を取得します。これらがない場合は、まずアクティブな セッションを一覧表示し（以下のヘルパーコマンドを参照）、セッション名を 確認します。

2. API 経由でセッションをキャンセル：API 経由でセッションをキャンセルします。cancel_session.md に記載された正確な curl コマンドと手順を必ず使用してください。

3. 接続フォワーダーの終了：環境のプロセス管理機能を使用して、{command_id} に一致するバックグラウンドプロセスを終了します。

4. 確認：セッションがキャンセルされ、リソースが解放されたことをユーザーに伝えます。

デバイスセッションの有効期限の変更

ユーザーからアクティブなデバイスセッションの有効期限の変更を依頼された場合：

ルール：ユーザーによる明示的な確認が必須です。デバイスセッションの延長には追加料金が発生し、クラウドリソースが作成されます。エージェントは、アクティブな Google Cloud プロジェクト（例：${PROJECT_ID}）で発生する追加料金について、必ずユーザーに明示的に警告しなければなりません。セッション延長コマンドを実行する前に、必ず停止して明示的な承認を求めてください。

1. パラメーターの抽出：

   • session_name：アクティブなセッション名。
   • ttl：新しい残り時間（例：3600s）。別の形式で指定されている場合は、ttl に換算します。

2. API 経由でセッションを変更：updateMask=ttl を使用して、API 経由でセッションを変更します。update_session_expiration.md に記載された正確な curl コマンドと手順を必ず使用してください。

3. 接続フォワーダーの再起動：

   • 古いフォワーダー接続を確実に閉じるため、adb disconnect localhost:{port} を実行します。
   • {command_id} に対応する古い接続フォワーダーを停止します。
   • 「デバイスセッションの開始」の手順 5 に従って新しい接続フォワーダーを起動します（新しい --ttl を秒単位で計算し、新しく返された Command ID を保存します）。

4. 確認：セッションの有効期間が更新され、新しい TTL で接続フォワーダーが再起動されたことをユーザーに伝えます。

ヘルパー：アクティブなセッションの一覧表示

コンテキストを失った場合にアクティブなセッションを確認するには、list_sessions.md に記載された curl コマンドと手順を必ず使用してください。

参考資料

• gcloud device-run CLI
• Device Streaming API
• describe_device.md
• reserve_device.md
• session_status.md
• start_adb_forwarder.md
• view_device.md
• cancel_session.md
• update_session_expiration.md
• list_sessions.md