agent-desktop とは

agent-desktop は、AI エージェントが OS のアクセシビリティツリーを通じてデスクトップアプリを操作するための、Vercel Labs 製のオープンソース CLI（兼 C ライブラリ）である。スクリーンショットや画素照合を使わず、アプリの画面構造を JSON で受け取り、要素ごとに振られた ref（参照ID）に対して click や type を実行する。README は「Computer use CLI for AI agents」と説明している。ライセンスは Apache-2.0 で、LLM は内蔵していない。

GitHub のリリースページで確認すると、v1.0.0 は2026年10月28日、v1.1.0 は2026年11月3日、最新の v1.2.0 は2026年11月5日である。注意点として、MCP サーバー機能（agent-desktop mcp）が入ったのは v1.2.0 で、1.0・1.1 ではない。本稿は GitHub の README とリリースノート、公式ドキュメント（agent-browser.dev/desktop）を一次情報として、できること・仕組み・導入手順・既存ツールとの違い・安全面の注意を整理する（2026年11月9日時点）。

- 何か: macOS（AX API）・Windows（UI Automation）・Linux（AT-SPI）のアクセシビリティ API を使い、デスクトップアプリの UI を「読んで・操作する」Rust 製 CLI と C ライブラリ（libagent_desktop_ffi）
- 方式: 画面画像ではなく UI ツリー（JSON）を読み、ref を指定して操作する。操作後に再度 snapshot して結果を確認するループは、呼び出す側のエージェントが回す
- 入手: npm install -g agent-desktop または brew install agent-desktop。Apache-2.0。2026年11月9日時点で GitHub のスターは約2.0万

同じ Vercel Labs の agent-browser はブラウザを対象にしたツールで、agent-desktop は「同じ発想をブラウザの外のデスクトップアプリへ広げたもの」と位置づけるとわかりやすい。公式ドキュメントのサイトも agent-browser.dev の /desktop 配下に置かれている。

README によると、CLI のコマンド名は60個で、うち56個が実際に動作する。残りの key-down・key-up・mouse-down・mouse-up は、押しっぱなしのキーやボタンを解放できるデーモンが入るまで実行を拒否する仕様である。README はコマンド名の一覧のみを載せており、各コマンドの説明は公式ドキュメントの Commands ページにある。

どのコマンドも、version・ok・command・data を持つ1つの JSON エンベロープを標準出力に返す。エラーコードも決まっており、たとえば ref が古くなると STALE_REF、候補が複数あると AMBIGUOUS_TARGET が返る。README は、error.disposition.retry が safe のときだけ再試行するよう求めている。

画面のスクリーンショットをモデルに見せ、座標を指定してクリックさせる方式（スクショ型）は、見た目さえあればどのアプリにも使える反面、画像を読む分のトークンと時間がかかり、解像度や配置が変わると座標がずれる。agent-desktop は、アプリが OS に公開している UI 構造（ボタン、テキスト欄、メニューなど）を直接読む。これをアクセシビリティツリーと呼び、スクリーンリーダーが使うのと同じ情報源である。

操作の流れは次の3ステップで、README ではこれを繰り返すと説明している。

- snapshot: 対象アプリの UI ツリーを JSON で取得する。各要素に ref_id と available_actions が付く
- act: ref を指定して click や type などを実行する
- verify: 再度 snapshot（または get・is・wait）で結果を確認する

ref は取得した snapshot に属する。README の例では @s8f3k2p9:e8 のように snapshot ID を含む形で指定し、@e8 のような裸の ref は INVALID_ARGS になる（v0.10.0 で裸の ref の入力は廃止）。画面が変わると STALE_REF が返るので、新しい snapshot を取り直す。ウィンドウが複数ある場合は AMBIGUOUS_TARGET になり、--window-id で指定する。

既定はヘッドレスで、ref 操作はアクセシビリティ API 経由で行われ、マウスポインタを動かさず、フォーカスも奪わない。実際のマウス・キー入力が必要なときだけ、グローバルフラグ --headed を付ける。なお、アクセシビリティ API は「成功」を返しても実際には何も起きないことがあり、macOS のドキュメントは「効果を確かめる手段は観察だけ」と明記している。操作のたびに再観察するループは、この性質への備えでもある。

macOS ではアクセシビリティの許可が必要である。macOS のドキュメントによると、許可が要るのは agent-desktop を起動するアプリ（ターミナル、iTerm2、VS Code、エージェントのホストなど）で、バイナリが別に一覧に出る場合はそれも許可する。screenshot を使うときだけ「画面収録」、通知センターを開くなど一部のコマンドだけ「オートメーション（System Events）」が追加で必要になる。agent-desktop permissions --guide が System Settings の該当画面を開いてくれる。許可後にアプリの再起動は不要とされている。

macOS の headless では、double-click（要素が AXOpen を持つ場合を除く）・triple-click・hover・drag などのポインタ操作は POLICY_DENIED で拒否され、--headed が必要になる。cmd+q など終了系のショートカットも --force なしでは拒否される（アプリを終了するなら close-app を使う）。他のOSでの可否は、各プラットフォームのページに一覧がある。

README の手順は次のとおり。npm パッケージにはネイティブバイナリが含まれ、Bun・Yarn・pnpm でも入る。Homebrew は macOS と Linux 向けで、Scoop の公式パッケージはまだない。

使い方の基本は snapshot → 操作 → 再 snapshot である。README のクイックスタートそのままの例を示す。-i は操作可能な要素だけを返すオプションで、出力の ref を次のコマンドに渡す。

要素の多いアプリでは、まず snapshot --skeleton --app Slack -i --compact で全体の地図だけを取り、気になる領域を snapshot --root @s8f3k2p9:e3 -i --compact で掘り下げる方法が README に紹介されている。パスワードなどは type・set-value・clipboard-set に --stdin を付けると、プロセスの引数に文字列が残らない。ただし batch の JSON は引数に現れるため、秘密情報を扱う手順は別コマンドにするよう README は注意している。

MCP で使う場合は agent-desktop mcp が全コマンドを stdio の MCP ツールとして公開する（v1.2.0 で追加）。ツール名は desktop_snapshot・desktop_click・desktop_session_start のようにコマンド名に desktop_ を付けた形で、戻り値は同じ JSON エンベロープである。README の設定例は次の1つだけである。

この mcpServers 形式は、Claude Code や Cursor など、mcpServers を使う MCP クライアントの設定にそのまま書き足す形である。ただし README と公式ドキュメントにはクライアントごとの設定手順は載っておらず、Claude Code・Cursor での動作確認は一次情報では確認できなかった。MCP の仕組み自体は MCP 公式ロードマップの解説も参考になる。

MCP を使わず、エージェントに CLI を直接叩かせる場合は skills コマンドが使える。agent-desktop skills get desktop（基本ループと規則）と agent-desktop skills get platform（OS固有の違い）が、バイナリに埋め込まれたエージェント向けガイドを出力する。README は、AGENTS.md に「最初にこの2つを実行する」と書く運用と、npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop による静的コピーの導入を案内している。静的コピーは CLI 更新後に古くなりうるため、版に合う内容は skills get で取るのが推奨されている。

1.0 の前の v0.10.0（2026年10月18日）が実質的な転換点で、Windows 10 1809 以降の対応が加わった一方、C ABI のメジャーバージョンが5になり、裸の ref 入力が廃止されるなどの破壊的変更があった。v1.0.0 のノートはこれに触れていないため、0.9 系以前から上げる場合は v0.10.0 のノートを確認したい。

AI エージェントに画面を操作させる方式は、大きく3つに分かれる。agent-desktop は「アクセシビリティ型」のうち、ブラウザの外のネイティブアプリを対象にするものだ。

要するに、スクショ型は「どのアプリでも見た目さえあれば動く」代わりに画像の解釈が必要で、アクセシビリティ型は構造化テキストで軽く速い代わりに、アプリがアクセシビリティ情報を正しく公開していることが前提になる。独自描画のゲームや、アクセシビリティ対応が不十分なアプリでは UI ツリーが貧弱になりうるが、これは一般的な性質で、agent-desktop の個別アプリごとの動作は一次情報では確認できていない。

OpenAI 側の動向は Codex の Computer Use（Windows対応）とGPT-5.4 の computer use API の解説、デスクトップアプリ型の例は Manus Studio の記事にまとめている。

agent-desktop は、エージェントにログイン済みのデスクトップを操作する権限を渡す道具である。macOS ではアクセシビリティを許可した時点で、そのアプリが操作できる範囲はほぼ画面全体に及ぶ。README も、snapshot・クリップボード読み取り・スクリーンショット・コマンド出力・デバッグ用の成果物に私的な内容が含まれうるとして、公開ログやアップロードに載せないよう求めている。

- 専用環境で動かす: Anthropic は computer use で、最小権限の専用の仮想マシンかコンテナを使い、アカウントのログイン情報などの機密データに触れさせず、インターネット接続を許可ドメインに絞るよう推奨している。agent-desktop にも同じ考え方が当てはまる
- 画面上の文章を命令として扱わない: OpenAI も「画面の内容は信頼できないものとして扱う」と案内している。メールやWebページに書かれた指示で操作が乗っ取られるプロンプトインジェクションは、ツリー型でも起こりうる
- 重要な操作は人が承認する: 購入・送信・削除・同意のクリックなどは、人の確認を挟む
- 終了系の保護を外さない: macOS では終了ショートカットが既定で拒否される。--force は必要なときだけ使う
- 秘密は --stdin で渡す: パスワードなどを引数に書かない
- ログを管理する: snapshot やトレースの保存先を決め、共有しない

なお、リポジトリの SECURITY.md は脆弱性の報告方法（GitHub の private vulnerability reporting を使い、公開 issue にしない）を定めたもので、利用者向けの安全運用の指針は載っていない。業務PCに導入する場合の運用は、利用者側で決める必要がある。

プロダクトとして完成した「エージェント」を求める場合は注意が要る。agent-desktop は操作の部品であり、判断するモデルや計画のロジックを含まない。自分のエージェントやコーディングエージェントに組み込んで使う前提のツールである。

- GitHub: vercel-labs/agent-desktop（README、リリースページ、SECURITY.md）— https://github.com/vercel-labs/agent-desktop
- 公式ドキュメント（Quick start、macOS、Skills）— https://agent-browser.dev/desktop
- npm パッケージ agent-desktop（v1.2.0、Apache-2.0）— https://www.npmjs.com/package/agent-desktop
- agent-browser — https://github.com/vercel-labs/agent-browser
- Playwright MCP — https://github.com/microsoft/playwright-mcp
- Anthropic computer use tool — https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
- OpenAI computer use — https://developers.openai.com/api/docs/guides/tools-computer-use
- 確認できなかった事項: 報道にある「週間トレンド上位」の数値、Claude Code・Cursor での MCP 接続手順の公式記載、個別アプリごとの動作