agent-device

callstackincubator/agent-device · v0.16.14 · Node.js 22+ · MIT

1 — 概要

何をする CLI か

agent-device は、iOS・Android・TV・デスクトップ上の実アプリを AI コーディングエージェントが検証・操作するためのデバイス自動化 CLI。コンパクトなアクセシビリティスナップショット、セマンティック ref（@e1 など）、必要時だけの証跡収集で、トークン効率のよいフィードバックループを提供する。

4+プラットフォーム

@e*スナップショット ref

MCPエージェント連携

.adリプレイ脚本

ネイティブ iOS/Android、Expo・Flutter・React Native アプリを対象に、シミュレータ・エミュレータ・実機・macOS/Linux デスクトップで動作する。Vercel の agent-browser が Web 向けなのに対し、agent-device はモバイル・TV・デスクトップ向けの同型ツール。

主な能力

Inspect — コンパクトな a11y スナップショット、@e3 形式の ref、セレクタ、React Native コンポーネントツリー
Interact — アプリ起動、タップ、入力、スクロール、ジェスチャ、待機、アサート、アラート処理、セッション終了
Capture — スクリーンショット、動画、ログ、トレース、ネットワーク、パフォーマンス、クラッシュ文脈、React プロファイル
Replay — 探索的操作を .ad 脚本として記録し、ローカル・CI で e2e チェックに再利用

2 — アーキテクチャ

リクエスト経路

CLI・MCP・Node.js クライアントは共通の Daemon にセッション付きコマンドを送る。Daemon は Command dispatch と Interactor を介して各プラットフォーム backend に委譲する。

flowchart TD
  Agent["AI Agent"]
  CLI["agent-device CLI"]
  MCP["MCP Server"]
  Node["Node.js Client"]
  Daemon["Daemon\n(session + HTTP)"]
  Dispatch["Dispatch / Interactor"]
  iOS["XCTest Runner\n(iOS / tvOS)"]
  Android["ADB +\nSnapshot Helper"]
  Mac["macOS Helper"]
  Linux["AT-SPI\n(Linux desktop)"]

  Agent --> CLI
  Agent --> MCP
  Agent --> Node
  CLI --> Daemon
  MCP --> Daemon
  Node --> Daemon
  Daemon --> Dispatch
  Dispatch --> iOS
  Dispatch --> Android
  Dispatch --> Mac
  Dispatch --> Linux

  classDef entryCls fill:#fff4e6,stroke:#c2410c,color:#1c1917,rx:6
  classDef coreCls fill:#ecfdf5,stroke:#15803d,color:#1c1917,rx:6
  classDef platCls fill:#f0f9ff,stroke:#0369a1,color:#1c1917,rx:6
  class Agent,CLI,MCP,Node entryCls
  class Daemon,Dispatch coreCls
  class iOS,Android,Mac,Linux platCls

エージェントの基本ループ

スキルおよび CLI の help workflow が正。典型フローは次のとおり。

open → snapshot -i → get / is / find / press / fill / scroll / wait → verify → close

スナップショットは画面上の要素に @e1、@e2 などの ref を付与する。最新スナップショットの ref は即操作可能。スクロールや画面遷移後は新しいスナップショットを取得する。

ドメイン用語（抜粋）

用語	意味
`Session`	選択したターゲットと開いたアプリ／サーフェスを Daemon が保持する状態
`Interactor`	コマンド dispatch とプラットフォーム挙動の間のセマンティック境界
`Command surface`	CLI・Node.js・MCP・batch で共有する公開コマンドのカタログとメタデータ
`Provider`	デバイス／runner／ホストツール実行を差し替える request-scoped アダプタ（統合テスト用）
`Target`	mobile / tv / desktop など、自動化対象の選択先

3 — モジュール構成

リポジトリ内の主要ディレクトリ

パス	役割
`src/cli.ts`・`bin/agent-device.mjs`	CLI エントリ。トピック別 `help`（workflow / debugging / replay 等）
`src/daemon/`	HTTP サーバ、セッションストア、リクエストルータ、ハンドラ群
`src/commands/`	公開コマンド定義、CLI grammar、コマンドメタデータ
`src/core/`	dispatch、Interactor、capabilities、バッチ処理
`src/platforms/`	iOS・Android・Linux・macOS の platform module
`src/mcp/`	MCP サーバ（`io.github.callstackincubator/agent-device`）
`src/client.ts`	型付き Node.js クライアント（bridge 連携向け）
`src/compat/maestro/`	Maestro 互換レイヤ（runtime / replay）
`ios-runner/`	iOS/tvOS 向け XCTest runner と RUNNER_PROTOCOL
`android-snapshot-helper/`	Android UI スナップショット取得ヘルパ APK
`android-multitouch-helper/`	マルチタッチジェスチャ用ヘルパ
`skills/agent-device/`	エージェント向けルータースキル（CLI help へ誘導）
`website/docs/`	公式ドキュメント（Rspress）

プラットフォーム backend

対象	backend
iOS / tvOS	XCTest runner（`ios-runner/`）
Android / Android TV	ADB + Android snapshot helper
macOS デスクトップ	ローカル macOS helper
Linux デスクトップ	AT-SPI（`atspi-bridge`）

4 — 使い方

インストール

npm install -g agent-device@latest
agent-device --version
agent-device help workflow

インストール済み CLI の help がエージェント向けの正。Node.js 22+ が必要。iOS/tvOS/macOS は Xcode、Android は Android SDK + ADB、macOS デスクトップ自動化は Accessibility 権限が前提。

最小ループ

# アプリ一覧
agent-device apps --platform ios
agent-device apps --platform android

# セッション開始
agent-device open SampleApp --platform ios

# インタラクティブ要素のみ（-i）
agent-device snapshot -i
# @e1 [heading] "Settings"
# @e2 [button] "Sign In"
# @e3 [text-field] "Email"

# 操作と証跡
agent-device fill @e3 "test@example.com"
agent-device screenshot ./artifacts/settings.png
agent-device close

実行環境: ローカル開発・デバッグに加え、CI/CD では .ad リプレイと artifact 収集、リモート実行では Agent Device Cloud や remote profile が使える。詳細は公式ドキュメントの Commands / Replay & E2E を参照。

5 — エントリポイント

利用経路と公開 subpath

経路	説明
`agent-device` CLI	エージェントターミナルから直接実行。Cursor / Codex / Claude Code 等
MCP	`io.github.callstackincubator/agent-device` — コマンドツール経由
`agent-device` npm パッケージ	`import … from 'agent-device'` — 型付きクライアント
`agent-device/android-adb`	ADB provider 契約、logcat / clipboard / keyboard 等
`agent-device/metro`	React Native Metro 連携
`agent-device/batch`	バッチ実行 API
`agent-device/selectors`・`finders`	セレクタ・finder ユーティリティの公開面

Appium / Detox / Maestro との違い

従来のモバイル自動化フレームワークは人間や CI スクリプト向けに設計されている。agent-device はAI エージェント向けに、コンパクトな状態表現・セマンティック操作・証跡収集・リプレイ可能な e2e へ変換することを優先する。Maestro 互換レイヤ（src/compat/maestro/）も用意されている。

6 — 参考リンク

公式・関連

GitHub: callstackincubator/agent-device — 本体リポジトリ
oss.callstack.com/agent-device — 公式ドキュメント
llms-full.txt — エージェント向け全文ドキュメント
npm: agent-device — パッケージ
agent-device.dev — プロダクトサイト
EAS workflow template — CI/CD 向けサンプル