agentic-device

agentic-device

npm パッケージ · CLI · ライブラリ · 安全性 · 制限事項

agentic-device は、ご自身が所有するスマートフォンを操作するための TypeScript ライブラリ、CLI、MCP サーバーです。WebDriverAgent または ESP32 HID ブリッジを介して iPhone を操作し、エージェントがセットアップを目的とした UI 操作を実行したり、監査可能なスマートフォン投稿タスクをキューに登録したりできます。 同意を最優先するデバイスパックです。操作はデフォルトでドライランとなり、人間の対応が必要なもの（パスコード、CAPTCHA、確認コード）がある場合は、進行したふりをせずに needs-human で停止します。

インストール

npm install agentic-device

Node.js と、公開済みの dist/ ビルドが必要です。ランタイム依存関係は MCP SDK と zod の 2 つです。

最初のタスクを投稿する

agentic-device device register --udid MY_PHONE_UDID --label "My iPhone" --connection simulator
agentic-device device action --udid MY_PHONE_UDID --action '{"type":"home"}'
agentic-device device post-task --udid MY_PHONE_UDID --platform instagram --text "Ship day"
agentic-device device queue

device action と post-task は --execute を指定するまでドライランです。また、device action は指定後も確認のためのゲートとして機能します。実行結果には、ドライバーが行った操作、または発生した VendorError が報告されます。

CLI

agentic-device device register --udid <id> --label <label> --connection <wda|esp32-hid|simulator>
agentic-device device list
agentic-device device action --udid <id> --action <json> [--execute]
agentic-device device post-task --udid <id> --platform <name> --text <text> [--media <path>]
agentic-device device queue [--claim|--complete|--fail <task-id>]
agentic-device costs
agentic-device mcp

ライブラリ

import { DeviceRegistry, SimulatorDriver, runAction } from "agentic-device";

const registry = new DeviceRegistry();
const phone = registry.register({ udid: "mine", label: "My iPhone", connectionType: "simulator" });
await runAction(phone, new SimulatorDriver(), { type: "home" }); // dry run

MCP サーバー

agentic-device mcp（または npx agentic-device-mcp）を実行すると、同じレジストリ、キュー、ドライバー、コストレポートを stdio 経由のツールとして提供します。そのため、Claude Code や Cursor などのホストから、デバイスの登録、操作のプレビュー、タスクキューの読み取りができます。

ユースケース

• サポートエージェントが、デスク上のデバイス向けに製品発表の投稿をキューに登録し、実行を承認します。
• QA エージェントが自身のシミュレーターを操作して、アプリのオンボーディングを進め、スクリーンショットを撮影します。
• 投稿パイプラインでは、追跡されないスクリプトではなく、監査可能なキュー項目として各デバイスタスクを記録します。

代替ツールと関連ツール

• Appium は汎用のモバイル自動化フレームワークです。WebDriverAgent はその iOS ドライバーであり、agentic-device は投稿タスクの一部について同じプロトコルを使用します。
• ESP32-BLE-Keyboard は、Bluetooth HID 経由の操作に使うリファレンスファームウェアです。
• デバイスファーム製品（BrowserStack App Automate、Firebase Test Lab）はデバイスを大規模に貸し出します。このパックは、ご自身のデスクにあるスマートフォン向けです。

安全性

• UDID を使って、ご自身が所有するスマートフォンのみを登録してください。
• device action はデフォルトでドライランです。確認後に限り --execute を指定してください。
• humanCheckpoint は、パスコード、CAPTCHA、確認コードの手順では常に needs-human を返します。このパックがプラットフォームのチェックを回避することはありません。
• ドライバーは失敗を VendorError として表し、失敗したハードウェア操作やネットワーク処理を成功として報告することはありません。

制限事項

• パスコード、CAPTCHA、二要素認証、App Store の審査を回避することは一切できません。
• WebDriverAgent を使うには、物理デバイスから到達可能な WDA エンドポイントが必要です。ハードウェアを使わない場合は simulator を選べます。
• 投稿キューはデフォルトでプロセス内に保持されます。本番環境で実行する場合は、ご自身のストアにタスクを永続化してください。

上流の基盤

WDA ドライバーは、appium/WebDriverAgent が公開するプロトコルに従います。ESP32 HID 経由の操作は、ESP32-BLE-Keyboard をベースに設計されています。これらの連携機能は、所有者自身が操作するデバイスのみを対象としています。

ライセンス

MIT