developer-device-platform-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developer Device Platform

开发者设备平台（DDP）

Developer Device Platform (DDP) is a Google fully managed, global infrastructure providing access to a wide variety of physical and virtual devices.

[!WARNING] Developer Device Platform (DDP) is currently at Preview.

[!IMPORTANT] For all devicerun and devicestreaming API operations (reserving, status checking, stopping/canceling, updating, or listing a session), always verify and use the exact instructions and curl commands provided in the linked reference
.md
files.

开发者设备平台（DDP）是谷歌提供的全托管式全球基础设施，支持访问各类物理与虚拟设备。

[!WARNING] 开发者设备平台（DDP）目前处于预览阶段。

[!IMPORTANT] 对于所有devicerun和devicestreaming API操作（预约、状态检查、停止/取消、更新或列出会话），请务必验证并使用关联参考
.md
文件中提供的准确指令与curl命令。

Authentication & Setup

认证与设置

CRITICAL: Before running any requests, you MUST ensure the environment is correctly initialized by following these steps:

Before running any requests, verify if the

gcloud

executable is present. If missing, refer to the official Google Cloud CLI Installation Guide to install it on the current platform (Linux, macOS, Windows, etc.).

Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for the Developer Device Platform:
bash
```
gcloud auth login --no-browser
gcloud auth application-default login --no-browser
```

Enable APIs (if not already enabled):

bash

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

[!NOTE] Cloud Testing API is needed for Device Streaming API during Preview.

Setup Environment Variables: Set up the required project variable and access token:

bash

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

Python Environment: For instructions on setting up the python virtual environment, see [start_adb_forwarder.md].

关键提示：在执行任何请求前，必须按照以下步骤确保环境已正确初始化：

执行请求前，请确认

gcloud

可执行文件是否存在。若缺失，请参考官方Google Cloud CLI安装指南，在当前平台（Linux、macOS、Windows等）上进行安装。

Google Cloud认证：使用你的Google Cloud凭据进行认证，并为开发者设备平台配置有效的应用默认凭据（ADC）：
bash
```
gcloud auth login --no-browser
gcloud auth application-default login --no-browser
```

启用API（若尚未启用）：

bash

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

[!NOTE] 在预览阶段，Device Streaming API需要依赖Cloud Testing API。

设置环境变量：配置所需的项目变量与访问令牌：

bash

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

Python环境：关于Python虚拟环境的设置说明，请查看[start_adb_forwarder.md]。

Listing Available Devices

列出可用设备

To find the correct

modelCode

and

osVersion

to use when starting a session, you can list the available devices:

List Models: Run the following command to list available Android device models:
bash
```
gcloud alpha device-run devices list
```
Use the
```
ID
```
column to find the value for the
```
CATALOG_ID
```
parameter to describe a specific device (e.g.,
```
shiba-36
```
).
Describe a Model: Run the API request to get more details about a specific model (e.g., supportedProducts, resolution). Always rely on the exact curl command and instructions provided in [describe_device.md].

要找到启动会话时需使用的正确

modelCode

与

osVersion

，你可以列出可用设备：

列出设备型号：运行以下命令列出可用的Android设备型号：
bash
```
gcloud alpha device-run devices list
```
使用
```
ID
```
列查找
```
CATALOG_ID
```
参数的值，用于描述特定设备（例如：
```
shiba-36
```
）。
查看设备型号详情：运行API请求获取特定型号的更多详情（例如：支持的产品、分辨率）。请务必遵循[describe_device.md]中提供的准确curl命令与说明。

Starting a Device Session

启动设备会话

When the user asks to reserve or connect to a device:

Check Device Availability:
Look up
```
CATALOG_ID
```
of the device using
```
Listing Available Devices
```
instructions. Check the device availability of the
```
CATALOG_ID
```
by using the exact curl command and instructions provided in [describe_device.md]. The device MUST contain "deviceStreaming" in "supportedProducts" to be reserved.
If no specific device is specified, use
```
CATALOG_ID=shiba-34
```
(Pixel 8 on SDK 34).
If
```
OS_VERSION
```
was not specified by the user, ask the user to select a version from the device list (preferring the version with the highest availability {"available": "AVAILABILITY_HIGH" }).
If
```
OS_VERSION
```
is unavailable for
```
deviceStreaming
```
, do not reserve one. Prompt the user for an alternative
```
OS_VERSION
```
.
Extract Parameters:
- ```
model_id
```
  :
```
modelCode
```
  from device details. Required.
- ```
version_id
```
  :
```
osVersion
```
  from device details. Required.
Reserve Device:

Rule: Explicit User Confirmation Required. Reserving a device incurs billing charges and create cloud resources. The agent MUST ALWAYS warn the user explicitly about the potential extra billing costs. You MUST STOP and ask for explicit approval before proceeding with any session creation commands.
Then, run the API request with
```
model_id
```
and
```
version_id
```
to reserve the device. Always rely on the exact curl command and instructions provided in [reserve_device.md].
Parse the response to get
```
session_name
```
(the session name, e.g.,
```
projects/${PROJECT_ID}/deviceSessions/session-xxxxxx
```
). If reservation fails, report the error.
Wait for Session to be Active:
While waiting for the device session to be provisioned, poll the session status until
```
"state"
```
is
```
"ACTIVE"
```
. See [session_status.md] for the exact curl command.
Repeat this check every 5 seconds to prevent hitting API rate limit. If it does not become active within 2 minutes (typically under 1 minute), report failure and cancel the session. Once active, extract
```
expireTime
```
from the session JSON response and convert it to the user's local time in a human-readable format (e.g., "June 9, 2026 at 2:44 PM PDT").
Start Connection Forwarder: Start the ADB forwarder script to forward connection to the remote device. Always rely on the exact command and instructions provided in [start_adb_forwarder.md]. Ensure you record the Command ID.
Wait for Online and Parse Port: Wait for the forwarder to be online and extract the listening port. Always rely on the exact logic and instructions provided in [start_adb_forwarder.md].
Provide Instructions to User:
Once online, run
```
adb -s localhost:{port} shell getprop ro.product.model
```
to retrieve the device model name. Then, print a message directly to the user in the chat (do NOT create any artifact file) with the following instructions:
Device is ready!
```
Device Model: {device_model}
OS Version: {version_id}
ADB Address: localhost:{port}
Session Expiration: {expire_time_human_readable_local}
```
Save Session State: Save the
```
{session_name}
```
and
```
{command_id}
```
in your conversation memory/context so you can clean it up later.

当用户要求预约或连接设备时：

检查设备可用性：
使用“列出可用设备”中的说明查找设备的
```
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
```
。
提取参数：
- ```
model_id
```
  ：设备详情中的
```
modelCode
```
  ，必填项。
- ```
version_id
```
  ：设备详情中的
```
osVersion
```
  ，必填项。
预约设备：

规则：必须获得用户明确确认。预约设备会产生计费费用并创建云资源。助手必须明确警告用户可能产生的额外计费成本。在执行任何会话创建命令前，必须暂停操作并获得用户的明确批准。
然后，使用
```
model_id
```
与
```
version_id
```
运行API请求以预约设备。请务必遵循[reserve_device.md]中提供的准确curl命令与说明。
解析响应以获取
```
session_name
```
（会话名称，例如：
```
projects/${PROJECT_ID}/deviceSessions/session-xxxxxx
```
）。若预约失败，请报告错误。
等待会话激活：
在等待设备会话配置完成期间，轮询会话状态，直到
```
"state"
```
变为
```
"ACTIVE"
```
。具体curl命令请查看[session_status.md]。
每5秒检查一次，避免触发API速率限制。若2分钟内（通常不到1分钟）仍未激活，请报告失败并取消会话。激活后，从会话JSON响应中提取
```
expireTime
```
，并转换为用户本地时间的易读格式（例如：“2026年6月9日下午2:44 PDT”）。
启动连接转发器：启动ADB转发器脚本，将连接转发至远程设备。请务必遵循[start_adb_forwarder.md]中提供的准确命令与说明。请记录命令ID。
等待上线并解析端口：等待转发器上线并提取监听端口。请务必遵循[start_adb_forwarder.md]中提供的准确逻辑与说明。

向用户提供操作说明：

上线后，运行

adb -s localhost:{port} shell getprop ro.product.model

以获取设备型号名称。然后，直接在聊天中向用户打印以下信息（请勿创建任何工件文件）：

设备已就绪！

设备型号: {device_model}
操作系统版本: {version_id}
ADB地址: localhost:{port}
会话到期时间: {expire_time_human_readable_local}

保存会话状态：将
```
{session_name}
```
与
```
{command_id}
```
保存至对话记忆/上下文，以便后续清理。

Viewing the Device Screen of a Reserved Device

查看已预约设备的屏幕

The coding agent can directly interact with the remote device using

adb

. Users may use a utility to display the screen and manually control the reserved device in DDP. See [view_device.md] for an example utility.

编码助手可通过

adb

直接与远程设备交互。用户可使用工具显示屏幕并手动控制DDP中已预约的设备。示例工具请查看[view_device.md]。

Stopping a Device Session

停止设备会话

When the user asks to stop, cleanup, or release the device:

Identify Session: Retrieve the active
```
{session_name}
```
and
```
{command_id}
```
from your context. If you don't have them, list active sessions first (see helper command below) to find the session name.
Cancel Session via API: Cancel the session via the API. Always rely on the exact curl command and instructions provided in [cancel_session.md].
Terminate Connection Forwarder: Terminate the background process matching
```
{command_id}
```
using your environment's process management capability.
Confirm: Confirm to the user that the session has been cancelled and resources released.

当用户要求停止、清理或释放设备时：

识别会话：从上下文中获取活跃的
```
{session_name}
```
与
```
{command_id}
```
。若未保存，请先列出活跃会话（见下方辅助命令）以查找会话名称。
通过API取消会话：通过API取消会话。请务必遵循[cancel_session.md]中提供的准确curl命令与说明。
终止连接转发器：使用环境的进程管理功能终止与
```
{command_id}
```
匹配的后台进程。
确认：向用户确认会话已取消且资源已释放。

Change Device Session Expiration Time

修改设备会话到期时间

When the user asks to change the expiration time of an active device session:

Rule: Explicit User Confirmation Required. Extending a device session incurs additional billing charges and create cloud resources. The agent MUST ALWAYS warn the user explicitly about the potential extra billing costs. You MUST STOP and ask for explicit approval before proceeding with any session extension commands.

Extract Parameters:
- ```
session_name
```
  : The active session name.
- ```
ttl
```
  : The new remaining duration (e.g.,
```
3600s
```
  ). Derive the
```
ttl
```
  if it's provided in another format.
Change Session via API: Change the session via the API using
```
updateMask=ttl
```
. Always rely on the exact curl commands and instructions provided in [update_session_expiration.md].
Restart Connection Forwarder:
- Run
```
adb disconnect localhost:{port}
```
  to ensure the old forwarder connection is closed.
- Stop the old connection forwarder corresponding to
```
{command_id}
```
  .
- Start a new connection forwarder by following Step 5 in "Starting a Device Session" (calculating the new
```
--ttl
```
  duration in seconds and storing the newly returned Command ID).
Confirm: Confirm to the user that the session duration has been updated and the connection forwarder has been restarted with the new TTL.

当用户要求修改活跃设备会话的到期时间时：

规则：必须获得用户明确确认。延长设备会话会产生额外计费费用并创建云资源。助手必须明确警告用户可能产生的额外计费成本。在执行任何会话延长命令前，必须暂停操作并获得用户的明确批准。

提取参数：
- ```
session_name
```
  ：活跃会话的名称。
- ```
ttl
```
  ：新的剩余时长（例如：
```
3600s
```
  ）。若用户提供的是其他格式，请转换为该格式。
通过API修改会话：使用
```
updateMask=ttl
```
通过API修改会话。请务必遵循[update_session_expiration.md]中提供的准确curl命令与说明。
重启连接转发器：
- 运行
```
adb disconnect localhost:{port}
```
  以确保旧转发器连接已关闭。
- 停止与
```
{command_id}
```
  对应的旧连接转发器。
- 按照“启动设备会话”中的步骤5启动新的连接转发器（计算新的
```
--ttl
```
  秒数并保存新返回的命令ID）。
确认：向用户确认会话时长已更新，且连接转发器已使用新的TTL重启。

Helper: List Active Sessions

辅助功能：列出活跃会话

To find active sessions if you lost context, always rely on the curl command and instructions provided in [list_sessions.md].

若丢失上下文需查找活跃会话，请务必遵循[list_sessions.md]中提供的curl命令与说明。

References

参考资料

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

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

developer-device-platform-basics

Original

Translation

Developer Device Platform

开发者设备平台（DDP）

Authentication & Setup

认证与设置

Listing Available Devices

列出可用设备

Starting a Device Session

启动设备会话

Device is ready!

设备已就绪！

Viewing the Device Screen of a Reserved Device

查看已预约设备的屏幕

Stopping a Device Session

停止设备会话

Change Device Session Expiration Time

修改设备会话到期时间

Helper: List Active Sessions

辅助功能：列出活跃会话

References

参考资料