developer-device-platform-device-run
Runs automated, non-interactive jobs on remote Android devices with Developer Device Platform (DDP) Device Run using `gcloud beta device-run sessions`: native Android executables or shell scripts (for example CLI tools, custom runners, test harnesses or benchmarks) and Android instrumentation tests, on one or many devices, then waits for completion and collects per-device outputs and logs. Use when running a binary or test suite on remote devices without an interactive connection. Don't use it for interactive device reservations, adb tunnels or screen streaming (use developer-device-platform-basics), or for local devices.
- License 许可
- Apache-2.0
- 所属仓库
- google/skills
- 最近更新
- 2026-11-14
- Stars
- ★ 2.4w
- Forks
- 2.0k
01 前言 Front Matter
- name
- developer-device-platform-device-run
- metadata
- { "version": "1.0.0", "category": "CloudInfrastructureAndServices" }
- description
- Runs automated, non-interactive jobs on remote Android devices with Developer Device Platform (DDP) Device Run using `gcloud beta device-run sessions`: native Android executables or shell scripts (for example CLI tools, custom runners, test harnesses or benchmarks) and Android instrumentation tests, on one or many devices, then waits for completion and collects per-device outputs and logs. Use when running a binary or test suite on remote devices without an interactive connection. Don't use it for interactive device reservations, adb tunnels or screen streaming (use developer-device-platform-basics), or for local devices.
02 资源文件 8
- 参考文档references/android_executable.md3.8 KB
- 参考文档references/attribution.md1.9 KB
- 参考文档references/device_selection.md5.1 KB
- 参考文档references/instrumentation.md1.6 KB
- 参考文档references/multi_config_runs.md5.3 KB
- 参考文档references/results.md2.4 KB
- 参考文档references/session_lifecycle.md2.4 KB
- 参考文档references/troubleshooting.md2.9 KB
03 SKILL.md 正文
Developer Device Platform: Device Run
Device Run executes a job on remote DDP devices and returns its artifacts (logs, pulled files) to a Cloud Storage bucket. One session fans out to one job per requested device.
[!WARNING] Developer Device Platform (DDP) is currently in Preview. The
gcloud beta device-runcommands might change without notice.
When to use this skill
| The user wants to... | Use |
|---|---|
| Run a native binary or shell script on remote devices | This skill (android-executable) |
| Run an Android instrumentation test APK on remote devices | This skill (instrumentation) |
| Reserve a device, connect with adb, stream the screen | developer-device-platform-basics |
| Extend or cancel an interactive device lease | developer-device-platform-basics |
| Work with a device connected over USB | Neither (not DDP) |
The setup below is complete; this skill doesn't depend on another skill for authentication, project selection or API enablement.
Requests this skill does not handle
For interactive use (reserve a device, adb, screen streaming, leases):
- If
developer-device-platform-basicsis installed: do not submit a Device Run session; switch todeveloper-device-platform-basics, and note that interactive reservations are also billed to the active project. - If
developer-device-platform-basicsis not installed: reply in a single message without calling any tools (no commands, searches, file reads or scheduling), then stop:- Say that Device Run is for non-interactive batch jobs, so you will not submit a Device Run session.
- Point the user to an interactive Device Streaming reservation with the
developer-device-platform-basicsskill (or https://docs.cloud.google.com/device-streaming/docs/overview.md.txt), and suggest installing the skill. - Warn that an interactive reservation is also billed to the active Google Cloud project.
Keep answers fast
Prefer this skill and gcloud beta device-run ... --help over broad web
searches for Device Run syntax. If gcloud or the beta component is not
installed, fall back to the official documentation at
https://docs.cloud.google.com/developer-device-platform/device-run.md.txt and
https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run. For dry
runs, show the commands instead of running them.
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read and follow the instructions in
Usage Attribution.
Setup
Run these checks once per environment. Do not assume tools are installed, and do not install or update software without the user's approval.
-
gcloud CLI: Check that gcloud is installed and has Device Run commands:
gcloud --version gcloud beta device-run sessions submit android-executable --help >/dev/nullIf gcloud is missing, point the user to https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt. If the
betacomponent or the Device Run commands are missing, ask the user before runninggcloud components install betaorgcloud components update. -
Authentication: Check the active account. On a Compute Engine or other remote VM, the active account may be the VM's default service account (
...@...iam.gserviceaccount.com), which often lacks the scopes Device Run and billing calls need (No service account scopes specified). If there is no active account, or only such a service account, ask the user to sign in.--update-adcalso updates Application Default Credentials in the same flow; add--no-launch-browserin SSH or remote terminals:gcloud auth list --filter=status:ACTIVE --format="value(account)" gcloud auth login --update-adc -
Project: Use the user's active project, or the one they name. Never hardcode a project, and don't change the active project without asking.
export PROJECT_ID=$(gcloud config get project) # Only if the user asks to switch: gcloud config set project PROJECT_ID -
Billing: Device Run is billed to the project. Check that billing is enabled; if it isn't, stop and tell the user.
gcloud billing projects describe "${PROJECT_ID}" \ --format="value(billingEnabled)" -
Enable the Device Run API (if not already enabled; ask first):
gcloud services enable devicerun.googleapis.com --project="${PROJECT_ID}" -
IAM roles: The user needs
roles/devicerun.admin,roles/serviceusage.serviceUsageConsumerandroles/vieweron the project. To read inputs from a bucket in another project, grant the DDP service agentroles/storage.objectVieweron that bucket (see https://docs.cloud.google.com/developer-device-platform/device-run/share-storage.md.txt). -
Bucket: Sessions store inputs and outputs in Cloud Storage. Without
--bucket-name, gcloud uses or createsgs://${PROJECT_ID}-devicerun. For project IDs that contain:,.orgoogle, gcloud replaces them (with-,-andelgoog) before adding-devicerun; read the actual bucket from theResult filesURI printed bysubmitordescribe. A bucket named explicitly with--bucket-nameMUST already exist. Pass the bucket name only (nogs://, no path). Inputs and outputs undergs://<bucket>/automation/are kept until you delete them or a Cloud Storage lifecycle rule expires them, and storage is billed meanwhile.
Core workflow
-
Pick devices. Users usually name devices the way they are sold ("Pixel 10", "Galaxy S22"), while
--deviceneeds a catalog ID such asfrankel-36(codename + Android API level). Resolve names to IDs from the live catalog with device_selection.md; never guess an ID from memory. If a device is offered on several Android versions and the user didn't name one, list the versions, recommend one, and let the user pick one, several (one job each) or all; never pick silently. Before submitting, show the user the resolved ID, the device name and the Android version, and call out any other choice you made for them (physical vs virtual, variant). -
Stage inputs.
--executable,--test,--target-appand the source side of--other-files-to-pushacceptgs://paths or local paths. Local files are uploaded automatically into a freshautomation/inputs/<timestamp>/folder, so prefer local paths for files that change between runs (scripts, freshly built binaries). Upload large, reused files (models, datasets) to the bucket once and reference them bygs://path. -
Confirm cost. Explicit user confirmation required. Device Run sessions are billed to the active Google Cloud project. Before submitting, tell the user the project (
${PROJECT_ID}), the devices, the number of jobs, and the timeout, warn that this incurs charges, and STOP until they approve. Include this billing warning in every answer that shows a submit command, even when you only explain the steps or the user will run the command themselves. -
Submit. Pick the submit type:
- Native executable or shell script: see android_executable.md.
- Instrumentation test APK: see instrumentation.md.
- Same binary with several configurations (different flags, inputs or environment variables) per device: see multi_config_runs.md.
-
Wait. For runs longer than a few minutes, submit with
--asyncand follow session_lifecycle.md. -
Collect results. Download and map artifacts to devices with results.md.
-
Report one row per device: device ID, job folder (
job-NNN), result, key outputs, and thegs://path of the session folder. Call out failed, timed-out or cancelled jobs explicitly instead of dropping them.
Rules
- Always set the timeout.
--executable-timeout(or--instrumentation-timeout) defaults to5m; the valid range is1mto3h. Estimate the run time and set it explicitly. - Arguments are comma-separated. Each element of
--executable-argsbecomes one argument. Rewrite space-separated command lines. If a value contains a comma, use the^SEP^prefix (see android_executable.md). - No shell in the direct call. With a binary as
--executablethere is no shell: set environment variables with--executable-env-vars, notexport. - Do not overwrite shared inputs. DDP fetches inputs when a job starts.
Never overwrite a
gs://script or binary that a pending session uses; use local paths (auto-uploaded) or a uniquegs://path per run. - Label sessions with
--labels(for examplepurpose=smoke,build=1234) so they are easy to find later. - Poll politely. Never poll in a tight loop; poll every 30 to 60 seconds and report progress (see session_lifecycle.md).
- Cancel on request. If the user wants to stop, cancel the session (see session_lifecycle.md) and tell the user it was cancelled.
- Do not use the Device Streaming API (
devicestreaming.googleapis.com,deviceSessions) to run batch jobs; that is for interactive leases.
Reference index
- device_selection.md: map device names such as "Pixel 10" to catalog IDs, OS versions, physical vs virtual.
- android_executable.md: flags, direct call, shared libraries, script as executable.
- instrumentation.md: APK tests, sharding, test targets.
- session_lifecycle.md: sync vs async, wait, describe, cancel, status and result types.
- results.md: bucket layout, job-to-device mapping, logs.
- multi_config_runs.md: run the same binary with several configurations per device.
- troubleshooting.md: common failures.
04 同仓库更多 Skills
cloud-operator-share-context
Shares Google Cloud operating context the user or their team already have — environments, projects, services and regions, product preferences, best practices, architecture guidance, runbooks — found in agent instruction files, local memory, skills and workflows, and the repository's GCP docs, with the operator agent's memory after the user reviews the list. Use when the user runs this skill, accepts the cloud-operator or cloud-operator-setup skill's offer to share their existing Google Cloud context, or asks to share, import or save that context or a GCP fact for the operator agent. Don't use for ordinary GCP requests, which go to the cloud-operator skill.
cloud-operator-setup
Sets up the operator agent in a Google Cloud project via the autocloud MCP server: picks the operator project, creates or checks the user's operator agent, saves the project, and offers to share the user's existing Google Cloud operating context with the operator agent's memory. Use when the user runs this skill, asks to set up the operator or create their operator agent, or chooses setup when the cloud-operator skill asks. Don't use for ordinary GCP requests or installing gcloud.
compute-vm-creation
Guides the planning, configuration, and provisioning of standalone Google Compute Engine virtual machines (VMs) and bare metal (-metal) instances using gcloud CLI commands or direct MCP tool execution. Use ONLY when the user wants to create, configure, or provision a new standalone Compute Engine VM or bare metal instance from conversational intents (hardware sizing, region selection, OS image, networking, security defaults). DO NOT read or use for Google Kubernetes Engine (GKE) Autopilot or Standard clusters, Kubernetes node pools or Pods, container orchestration, managing existing VMs, Managed Instance Groups (MIGs), or Instance Templates.
agent-platform-autorater-customization
Customizes an autorater (evaluation metric) for an AI agent so its grades match the user's own judgment, starting from the agent's real trajectories. Use when a user wants a metric tailored to their agent, wants to turn failing trajectories into rubrics, says an existing autorater grades their agent wrong, or wants an autorater to agree with human labels (autorater hillclimbing, judge calibration). Don't use for quick evals with built-in metrics or for improving the agent itself (use agent-platform-eval-flywheel).
iap-agent-platform-troubleshooting
Diagnoses Identity-Aware Proxy (IAP) denials of outbound requests from Gemini Enterprise Agent Platform agents that run on Agent Runtime and send traffic through Agent Gateway. Use when an agent request fails with "Egress request is not authorized", when Cloud Audit Logs show an IAP egressViaIAP decision with granted false, when IAP audit entries are missing while debugging agent egress, or when Access policies, IAP allow policies, policy bindings, or Agent Registry entries might block agent egress. Don't use for Gemini model IAM permission errors (such as aiplatform.endpoints.predict), Agent Platform API errors, or Agent Runtime deployment or 500 errors (use agent-platform-troubleshooting instead). Don't use for setting up, creating, or connecting an Agent Gateway, or for IAP web apps, IAP TCP forwarding, or SSH.
bigquery-migration-validator
Validates that tables migrated to BigQuery match their source (Teradata, Snowflake, Oracle, Redshift, Databricks, PostgreSQL, SQL Server, MySQL, MariaDB, Hive, Impala, Vertica) with the BigQuery Migration Service (BQMS) validation tool: schema and data type comparison, column aggregate comparison, and row-level data comparison. Use when generating or editing a validation config, running a validation, choosing sampling or partitioning, fixing connection or driver errors, or investigating validation results in BigQuery and Cloud Storage to decide which mismatches to fix. Don't use for SQL translation (use bigquery-migration-sql-translator), extracting source database catalog metadata or query logs, generating SQL scripts (such as COPY INTO) or exporting or unloading source tables to Parquet on Cloud Storage, loading staged files into BigQuery (such as bq load), or general BigQuery query failures and tuning (use bigquery-troubleshooting or bigquery-optimization).