agent-desktopとは｜エージェントにデスクトップ操作をさせるVercel Labs製CLIを確認

agent-desktop は、AIエージェントにデスクトップアプリの操作をさせるための、Vercel Labs 製の CLI／C ライブラリだ。肝は、スクリーンショットのピクセルを当てる方式ではなく、OS のアクセシビリティツリー（UI の構造）を読んで操作すること。要素ごとに安定した参照（ref）が付き、操作してから再度観測して結果を確かめる。Rust 製・star 4.4k・Apache-2.0、最新は v1.0.2。まずは公式のデモを見てほしい。

エージェント基盤の全体像はAIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証にまとめてある。本記事はその「手足」側、エージェントが現実のアプリを触るための部品を1本見る。記憶側のdeja-vuやmem0と同じく、エージェントを現実で動かすための周辺部品の1つだ。

agent-desktop とは：ピクセルでなくUI構造で操作する

やりたいことは「エージェントに人間と同じようにアプリを使わせる」ことだ。その実現方法が、既存の computer use とは違う。Claude や OpenAI の computer use は、画面のスクリーンショットを撮り、座標や OCR で「ボタンはこのあたり」と推定してクリックする。agent-desktop は代わりに、OS が元々持っているアクセシビリティツリー——スクリーンリーダーなどが使う、アプリの UI 構造そのもの——を読む。

観測すると、操作できる要素1つずつに ref（@snapshotID:eN の形）が付いた JSON が返る。エージェントはその ref を指定して click や type を実行し、もう一度観測して結果を確かめる。ピクセルの一致も OCR も使わない。この「構造を読む」方式が、後述の安定性につながる。agent-desktop 自身は判断をしない。エージェントの『目と手』であって、ループ（次に何をするか）は呼び出すエージェント側に残る。

仕組み：参照(ref)で操作して、見て確かめる

基本の3拍子は「観測 → ref で操作 → 再観測で検証」だ。

この設計には、取り違えを防ぐ仕掛けが入っている。ref はそのスナップショットに属するので、古い ref や裸の @e8 は INVALID_ARGS で弾かれ、UI が変わった後は STALE_REF や AMBIGUOUS_TARGET が返る。撮り直して新しい ref を使え、という契約だ。ネイティブのアクセシビリティ・オブジェクトを保持することで、「消えた行が、同じ識別子を持つ別の生き残った行に静かにすり替わる」事故も防いでいる。出力は常に1つの JSON エンベロープ（ok と data か error）で、エラーには code・disposition・suggestion が付き、retry してよいのは disposition.retry が safe のときだけ。既定はヘッドレス（ポインタも前面化も動かさない）で、物理入力が要るときだけ --headed を付ける。

コマンドは 60個（うち操作系56個）で、観測（snapshot/find/screenshot）、ref 操作（click/type/scroll/select…）、キーボード・マウス、アプリ/ウィンドウ管理、通知、クリップボード、セッションまで揃う。典型的な一巡はこうだ。

agent-desktop snapshot --app Finder -i      # 操作できる要素を観測（各要素に ref）
agent-desktop click @s8f3k2p9:e8            # その ref に対して操作
agent-desktop snapshot --app Finder -i      # もう一度観測して結果を確認

要素数の多い画面には、段階的に絞り込む口が用意されている。まず snapshot --skeleton --compact で全体の骨組みだけを取り、目星がついたら snapshot --root @ref でその領域だけを詳しく観測する。Slack のような密なアプリでも、毎回全要素を取らずに済む。複数ウィンドウがあると AMBIGUOUS_TARGET になり、候補のウィンドウ id が error.details に並ぶので、--window-id で1つ指定する。こうした「曖昧さは黙って進めず、エラーで返して指定させる」姿勢が全体に通っている。複数の操作を1回でまとめる batch、一連の操作を束ねる session、記録用の trace も用意されていて、手数の多い作業を1呼び出しに畳んだり、後から再現・点検したりできる。

どんな用途に効くか

向くのは、API を持たないデスクトップアプリをエージェントに操作させたいケースだ。ブラウザだけの computer use と違い、ネイティブアプリ（Finder やメーラー、業務用のレガシーな社内アプリ、デザインツールなど）そのものを対象にできる。定型の入力作業、設定画面の一括変更、ネイティブ UI の E2E テスト、複数アプリをまたぐ段取りの自動化——いずれも「画面はあるが自動化の口が無い」領域だ。構造を読む方式なので、操作が効いたかを次の観測で確かめられる点も、こうした実務の自動化では効いてくる。

逆に、ツリーに要素が出ないアプリ（独自描画のクリエイティブツールの一部、ゲーム、Canvas 主体の画面）では力を発揮しにくい。そこは後述のとおり割り切りが要る。

ピクセル方式と何が違うか

強みと弱みは表裏一体だ。公平に見ておく。

ツリー方式の利点は、安定性と検証可能性だ。要素に構造上の id（ref）が付くので、座標のズレや再描画に強く、操作が効いたかを次の観測で機械的に確かめられる。retry してよいかもエラーの disposition で判断できる。弱点は、アクセシビリティツリーを公開しないアプリには届かないことだ。独自描画の UI、ゲーム、Canvas 主体の画面は、ツリーに要素が出てこないので苦手になる。そこはスクショ方式のほうが「見た目さえ映れば対象にできる」。どちらが上ではなく、構造で操作できるアプリにはツリー方式が堅い、という住み分けだ。実際、両者を組み合わせる設計もありうる。

対応環境とエージェントへの組み込み

対応 OS と主な機能は次のとおり。

インストールは npm で、ネイティブバイナリ（x64/ARM64）が同梱される。macOS はアクセシビリティ権限が要る（permissions --guide）。

npm install -g agent-desktop
agent-desktop version
agent-desktop permissions --guide   # macOS の権限付与を案内

エージェントへの組み込みは、CLI を叩くか、各リリース同梱の C ライブラリ（libagent_desktop_ffi）をプロセス内から呼ぶ。CLI を毎回起動せずに済むので、頻繁に叩くなら FFI が軽い。

import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_init(6)                    # ヘッダの ABI メジャーと一致で OK
adapter = lib.ad_adapter_create()
lib.ad_adapter_destroy(adapter)

バイナリは自分用のスキルを同梱していて、agent-desktop skills get desktop（ループ・ref・検証・retry の規約）と skills get platform（OS 差）を出力する。これを AGENTS.md に書くか、skills.sh からハーネスへ入れて、エージェントに手順ごと渡せる。

使うときの注意

・画面の内容は private を含む：スナップショット・クリップボード・スクショ・コマンド出力に機密が入りうる。公開ログやアップロードに混ぜない
・JEV ヘルパーは外部送信：任意機能の JEV ヘルパーは画面の説明を設定したモデルプロバイダーへ送る。ネイティブ CLI 単体とは別扱いで、送信先を把握しておく
・ツリー非対応UIは苦手：独自描画・ゲーム・Canvas はツリーに出ないので操作できないことがある。そこはスクショ方式の併用を検討
・既定はヘッドレス：物理入力は --headed のときだけ。無意識に前面化・入力しない設計だが、権限は OS ごとに要確認
・retry は safe のときだけ：エラーの disposition.retry を見る。当て推量での再試行は UI を壊しうる
・まだ v1 系で動きが速い：Homebrew/Scoop の公式配布は提出中（未反映）。版を固定して追うのが無難

総括。 agent-desktop は、エージェントの computer use を「スクショの当て推量」から「UI 構造の操作」へ寄せる部品だ。安定した ref と再観測による検証で、操作が効いたかを機械的に確かめられるのが最大の違いで、retry の安全判定まで契約に入っている。弱点はツリーを公開しないアプリに届かないことだが、そこは割り切りと併用で埋められる。エージェントに現実のデスクトップ作業をさせたい人にとって、『目と手』の堅い実装として見ておく価値がある。ブラウザ内で完結しない作業を任せたいなら、デスクトップ側の一手として、ブラウザ用の computer use を補完する位置づけで持っておきたい。

参照ソース

• vercel-labs/agent-desktop（公式リポジトリ） — README・Cargo.toml・assets/・コマンド表を 2026-11-01 に確認（v1.0.2）
• agent-desktop（npm） — 配布パッケージとバージョン
• AIエージェントフレームワーク比較2026 — エージェント基盤側の全体像（当サイト実測）