mobile-agent-harness

mobile-agent-harness

AI エージェント向けの Android デバイス自動化。 自己修復機能を備えた uiautomator2 ブリッジ上に構築された MCP サーバー、CLI、ホットリロード可能なプラグインランタイムです。デバイス側にアプリをインストールする必要はありません。

中文文档：README.zh-CN.md

これはベースランタイムのみです。プラグインはコミュニティカタログにあります：awesome-mobile-agent-harness-plugin。AI 向けのアプリの業務知識は app-lore にあり、このリポジトリの knowledge/ ローダーが直接読み込みます。

インストール

git clone https://github.com/Aelindra/mobile-agent-harness
cd mobile-agent-harness
pip install -e .          # add ".[ocr]" for vision.ocr / ui2.*

Python 3.9 以降が必要です。また、USB デバッグを有効にした状態で adb が PATH に通っている必要があります。

クイックスタート

1. ブリッジをデバイスに接続します。

export AGENT_SERIAL_DEFAULT=192.168.1.23:5555   # or "emulator-5555"

2. ツール一覧を確認し（デバイスがなくても実行できます）、オフラインテストを実行します。

python -m core.cli tools
python tests/test_runtime.py

3. ツールを呼び出します。

python -m core.cli call ui.snapshot
python -m core.cli call ui.click --args '{"selector":"text@^Network & internet$","pkg":"com.android.settings"}'

4. 任意の MCP クライアントに接続します。

{
  "mcpServers": {
    "phone": {
      "command": "python",
      "args": ["-m", "core.cli", "mcp"],
      "cwd": "/path/to/mobile-agent-harness",
      "env": { "AGENT_SERIAL_DEFAULT": "192.168.1.23:5555" }
    }
  }
}

すべてのツールは {"ok": bool, "error"?, ...} 形式の結果を返します。ok=false は業務上の結果（例：error_type=selector_not_found）を示します。再試行するのではなく、それに応じて対応してください。

ツール

グループ	ツール
観測	ui.snapshot ui.dump ui.find ui2.state ui2.screen_evidence ui2.timeline ui2.find_templates vision.screenshot vision.ocr vision.diff
操作	ui.click ui.click_handle ui.text_handle ui.hold_read ui.set_text ui.scroll ui.back ui.home input.tap input.swipe input.key
アプリ	app.launch app.current app.probe app.list app.stop app.wait_idle
シェルとデータ	shell.run state.prefs state.db file.push file.pull net.http
イベント	events.tail events.wait events.capture events.record_start events.record_stop
ナレッジとタスク	knowledge.list knowledge.guide ui2.check_states ui2.orient task.begin task.note task.end template.add sys.capabilities

ui.snapshot は要素ハンドル（e0、e1 など）を含む、簡潔なアクセシビリティツリーの一覧を返します。ui.click_handle はドリフト検出を行いながら、ハンドルを指定して操作します。ui2.state はアクセシビリティツリーと OCR を統合し、キャンバス描画 UI にも対応します。ui2.screen_evidence は画面の特徴（オーバーレイレベル、動き、色、レイアウト密度）を、解釈せずに測定して収集します。app.probe は、パッケージ、バージョン、向きなどの決定的な補助情報を返します。ui2.timeline は、軽量な証拠を時間順に N フレーム収集します。ui2.orient はコンテキストを調べ、一致するナレッジパックにルーティングし、それらの状態判別条件を評価します。一致した状態、または不足している証拠を示した優先順位付きの仮説を返します。

セレクター

セレクターは実際のアクセシビリティツリーに対して解決されます。座標は使用しません。

# ui.click selector examples
"id@d98 && [email protected]"       # resource-id, short form completed with pkg@
"text@^Settings$ && [email protected]"
"[email protected] && [clickable=true]"
"desc@^Search$"                        # content-desc regex

ハーネスとプラグイン

ハーネスファイルでは、アプリごとのフローを事前条件と事後条件付きのセレクターステップとして宣言します。distill はアプリを探索してフローの下書きを作成し、lint はセレクターの品質をチェックします。事後条件に失敗すると、ツールは古いものとしてマークされ、再蒸留が必要になります。組み込み例については harnesses/com.android.settings/harness.json5 を参照してください。

プラグインを plugins/ に配置すると、ロード時にツールまたは機能プロバイダーが登録されます。登録は取り消し可能で、ファイルの変更時にホットリロードされます。プラグイン開発ガイドについては README.zh-CN.md を、ナレッジパックの形式については knowledge/README.md を参照してください。

LLM の事前知識があてにならないアプリの業務コンテキストについては、エージェントに app-lore を参照させてください。これはオープンな Agent Skills 形式を採用した、アプリの構造調査レポートのコミュニティカタログで、複雑なアプリでは機能モジュールごとに分割されています。特にモバイルのシナリオはプライベートドメインであり、トレーニングデータでの取り扱いも少ないため、エージェントは使い慣れていないアプリを操作する前に、関連する調査レポートを読み込むと効果的です。ローカルの knowledge/ ディレクトリは引き続き、このリポジトリのランタイムレイヤー（パック、アイコンテンプレート、状態判別条件）として機能します。

設定

変数	説明	例
AGENT_SERIAL_DEFAULT	--serial／ANDROID_SERIAL が指定されていない場合に使用するデバイスのシリアル	192.168.1.23:5555
AGENT_SERIAL_USB	USB シリアルのフォールバック	0123456789abcdef
MAH_FRAME_STREAM	1 にすると、観測ツール向けの H.264 フレームストリームが有効になります	1
MAH_VISION_MODE	ビジョンの拡張機能：off／client／endpoint	client
MAH_VLM_URL / MAH_VLM_MODEL	外部ビジョンエンドポイント（OpenAI 互換）	http://127.0.0.1:11434/v1/chat/completions

比較

• mobile-mcp / agent-deviceとの比較：汎用的なデバイスツールセットです。このプロジェクトは、トランスポート層の上に、ファイルとしてのアプリごとのナレッジ（ハーネス）、機能の境界を備えたホットリロード可能なプラグインランタイム、明示的な adb／root 権限モデルを追加しています。
• droidrunとの比較：droidrun ではデバイス側にアクセシビリティアプリが必要ですが、このプロジェクトは adb 経由でインストール不要です。
• root 対応は宣言的です。デバイスにすでに su がある場合、コマンドの許可リストで制御される root プロバイダーがシェルの境界に追加されます。このプロジェクトは root を提供しません。

既知の制限事項

メッセージング、銀行、E コマースのアプリでは、自動化に対するアクティブなリスク制御が行われているため、adb 層は安定して動作しません。想定している用途は、開発、テスト、およびご自身のデバイスを使ったワークフローです。

コントリビューション

プラグインはawesome-mobile-agent-harness-pluginに、アプリのビジネス知識はapp-loreにコントリビューションしてください。各リポジトリのコントリビューションガイドをご覧ください。

ライセンス

MIT。