agent-device

---

agent-device

AI コーディングエージェント向けのモバイルアプリ自動化と検証。 CLI、組み込み MCP サーバー、または型付き Node.js API を通じて、コーディングエージェントに実行中のアプリのフィードバックループを提供します。

コーディングエージェントが実行中のアプリで変更を検証できるようにします。agent-device を使うと、エージェントは iOS、Android、HarmonyOS（シミュレーター、エミュレーター、実機）に加え、tvOS、Android TV、Fire TV（Fire OS）、Amazon Vega OS TV（Vega Virtual Device）、Web、macOS、Linux のアプリを調査、操作、デバッグ、検証できます。エージェントはスクリーンショットだけを基に推論するのではなく、トークン効率の高いアクセシビリティスナップショットを読み取り、ref とセレクターを使って操作し、レビュー用の証拠を保存します。また、並行して作業するエージェントのワークツリー間でデバイスへのアクセスを調整し、リモートデバイスクラウドにも接続します。

Claude Code、Codex、Cursor、Windsurf、Cline、Goose、CLI を実行できる、または MCP 経由で接続できるあらゆるエージェントで利用できます。また、AI SDK または Eve で構築するエージェントのランタイムとしても利用できます。Expensify、Shopify、そしてその他の企業の開発者が、アプリの検証に利用しています。

agent-device は、以下のモバイル自動化を支えています。 e2e と T3 Code。

クイックスタート

CLI をインストールしてセットアップを確認します。Node.js 22.12 以降が必要です。Web 自動化には Node.js 24 以降が必要です。対象ごとの要件については、インストールを参照してください。

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

CLI をエージェントに渡す前に、自分で doctor を実行してください。help workflow から、デバッグ、リプレイ、プロファイリングのガイドを参照できます。

CLI からアプリを操作する

組み込みの iOS Contacts アプリで連絡先を追加します。

# Start a session.
agent-device open Contacts --platform ios

# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"

# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"

agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"

# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close

ref は最新の出力でのみ有効です。--settle コマンドの後はその差分に含まれる ref を使い、必要な情報が差分にない場合にのみ新しいスナップショットを取得します。スナップショットはアプリのアクセシビリティツリーから取得されます。そのため、明確なラベル、ロール、テスト ID があると、エージェントの実行がより安定します。スクリーンショットや動画は、証拠として、またはアクセシビリティデータの質が低い場合に使用してください。

エージェントに MCP ツールを追加する

agent-device mcp を実行すると、公式の stdio MCP サーバーが起動し、インストール済みのコマンドを CLI と同じ実行経路を通じて構造化ツールとして公開します。

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

クライアントごとのセットアップ方法や、MCP より通常の CLI を選ぶべき状況については、AI エージェントのセットアップをご覧ください。

Node.js からスクリプトを実行する

createAgentDeviceClient() を使うと、Node.js コードから同じコマンドに型安全にアクセスできます。独自のエージェント内でモデルツールとして使うことも、オーケストレーションコードから使うこともできます。

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  const button = snapshot.nodes.find((node) => node.role === 'button');
  if (button) await client.interactions.press({ ref: button.ref });
} finally {
  await client.sessions.close();
}

Node.js API、実行可能なサンプル、および AI SDK と Eve の統合ガイドをご覧ください。

エージェントにできること

• アクセシビリティスナップショット、参照、セレクターを使ってアプリの状態を調査し、React Native のレンダリングをプロファイリングして、操作が遅くなる原因を特定します。
• 要素のタップや押下、フィールドへの入力、スクロール、ジェスチャーの実行、待機、状態のアサート、アラートへの対応を通じて、画面に表示されている UI を操作します。
• スクリーンショット、動画、ログ、トレース、ネットワークデータ、パフォーマンスサンプル、クラッシュの詳細、React プロファイルを使って、失敗を診断します。
• 動作する手順を .ad スクリプトとして保存し、ローカルまたは CI で実行することで、ワークフローを繰り返し実行します。必要に応じて、厳密な Maestro YAML をエクスポートできます。

各ターゲットでサポートされているコマンドと証跡については、コマンドをご覧ください。

エージェントへの依頼例

CLI をインストールすると、次のようなプロンプトを最初から最後まで実行できます。

• 「オンボーディング画面を実装し、iOS シミュレーターと Android エミュレーターで実行して、スクリーンショットを添付してください。」
• 「このクラッシュを再現し、発生直前までのログを取得してください。」
• 「この変更によって、不要な React Native の再レンダリングが発生しないか確認してください。」
• 「チェックアウトのフローを一度試し、リプレイスクリプトとして保存して、CI で実行してください。」
• 「このプルリクエストを実機で検証し、レビュー可能な証跡を添付してください。」

次のステップ

• AI エージェントのセットアップ：Cursor、Codex、Claude Code、Windsurf などに向けたスキル、プロジェクトルール、クライアントごとのセットアップ方法。
• クイックスタート：コマンドラインからアプリを開き、UI を読み取り、操作します。
• リプレイと E2E と デバッグとプロファイリング：再現可能なテストとバグの調査。

agent-device の実行場所

同じセッションと証跡のモデルをあらゆる段階で利用できます。エージェントがアプリを調査して証跡を取得し、リプレイを保存して CI で実行し、リモートデバイスへ移行します。

実行環境	最適な用途	はじめ方
ローカル	シミュレーター、エミュレーター、実機、macOS、Linux でのコマンドの試行やアプリのデバッグ。	クイックスタートに従ってください。
CI/CD	リプレイスクリプトと取得した成果物を使った、プルリクエストとマージの自動検証。	EAS ワークフローテンプレートをお試しください。
クラウド／リモート	Linux ランナー、マネージドデバイス、リモートジョブ。	リモートプロキシをセットアップして、デバイスクラウド（BrowserStack、AWS Device Farm、TestMu AI、Limrun）に接続するか、チーム QA については Callstack にお問い合わせください。

仕組み

agent-device はセッション内でデバイスの状態を保持します。iOS Simulator のスナップショットにはローカルのアクセシビリティブリッジを使用し、iOS の操作、実機の iOS、tvOS には XCTest を使用します。Android、Android TV、Fire OS には ADB とスナップショットヘルパーを、HarmonyOS には HDC と ArkUI uitest を、Vega Virtual Device には Vega CLI/VDA を使用します。また、Electron やその他の Chromium ベースのアプリではアクセシビリティツリーを通じて macOS のローカルヘルパーを使用し、Linux では AT-SPI を使用します。

サポートの範囲はターゲットによって異なります。HarmonyOS や Vega OS など、一部のバックエンドでは対応するコマンドが限られています。ターゲットが対応している機能を確認するには、agent-device capabilities --platform <platform> を実行してください。機能マトリックスでは、各ターゲット、デスクトップ、ウェブ、クラウドプロバイダーが対応するコマンドを確認できます。

セッションは呼び出し元の git worktree にスコープされ、ホストローカルのデバイス使用権によって、並行して動作するエージェントが互いのシミュレーターやエミュレーターを奪い合うことを防ぎます。デーモンを使わずに所有状況を確認するには agent-device device status を実行し、所有者が動作していないことが確実な使用権を解放するには agent-device device release --stale を実行してください。同じコマンドで、BrowserStack、AWS Device Farm、TestMu AI、Limrunのホスト型デバイスも操作できます。

agent-device は、Vercel の agent-browser が採用する「確認・操作・検証」のプロセスを、モバイル、テレビ、デスクトップアプリに使用します。基本的な --platform web のサポートでは、同じセッションおよびリプレイシステムで agent-browser を実行します。

よくある質問

agent-device とは何ですか？

agent-device は、AI コーディングエージェントがモバイルアプリを確認、操作、検証し、レビュー用の証拠を保存できるコマンドラインツール兼 MCP サーバーです。iOS、Android、HarmonyOS、テレビ、ウェブ、macOS、Linux に対応しています。

モバイルアプリの自動化に使える MCP サーバーはありますか？

はい。agent-device mcp を実行すると、公式の stdio MCP サーバーが起動します。クライアント設定については上記のクイックスタートを、クライアントごとの詳細については AI エージェントのセットアップをご覧ください。

React Native、Expo、Flutter、ネイティブアプリで使えますか？

はい。agent-device はネイティブの iOS アプリと Android アプリに加え、対応ターゲット上の React Native、Expo、Flutter アプリもサポートしています。使用できるコマンドと証拠はターゲットによって異なります。

モバイル MCP サーバーとは何が違いますか？

MCP サーバーは、CLI および型付き Node.js API と同じランタイムを利用するためのエントリーポイントの一つです。セッション、デバイスの所有権、セレクター、証拠、リプレイ、CI ワークフロー、クラウドへのルーティングは、これらすべてで一貫しています。

agent-device を使って独自のエージェントや QA 製品を構築できますか？

はい。型付き Node.js クライアントは、同じランタイムを利用する公開インターフェースなので、構築したエージェントは上記の機能をすべて利用できます。Node.js API、AI SDK、または Eve のガイドから始めてください。

Appium、Detox、Maestro とは何が違いますか？

agent-device では、エージェントがアプリの状態を読み取り、実行時に各コマンドを選択します。チームは Appium、Detox、Maestro を使ってテストスイートを作成し、保守します。agent-device は、実行結果を .ad スクリプトとして保存したり、厳密な Maestro YAML としてエクスポートしたりすることで、これらを補完できます。

agent-device は CI で実行できますか？

はい。実行を .ad スクリプトとして記録し、CI でリプレイして、スクリーンショットとログをアーティファクトとして保存できます。EAS ワークフローテンプレートは実用例です。

記事と動画

記事

• EAS Workflows で Expo アプリ向けの AI QA エージェントを構築する
• Agent Device：AI エージェント向け iOS・Android 自動化
• Vercel Eve でモバイル QA エージェントを構築する
• モバイルアプリ自動化向けに Agent Device を最適化した方法

動画

• agent-device でモバイルアプリを検証する
• AI コーディングワークフローで agent-device を使用する
• 実機でモバイルアプリをテストするクラウドエージェント

agent-device の利用者

Callstack、JPMorgan Chase、Expensify、Shopify、Kindred、Total Wine & More、LegendList、HerLyfe、App & Flow などのチームや開発者が agent-device を利用しています。

ドキュメント

• ドキュメント
• エージェント向けドキュメント

コントリビューション

CONTRIBUTING.md をご覧ください。

Callstack で開発

agent-device は MIT ライセンスのオープンソースです。agent-device.dev にアクセスするか、Callstack にお問い合わせください。