agent-desktop - OSのアクセシビリティツリーを参照IDで操作するCLI
agent-desktopは、OSのアクセシビリティツリーを参照ID付きのJSONへ変換し、そのIDでデスクトップアプリを操作するCLI・Cライブラリだ。READMEが示す中心的な流れは、観測、参照先への操作、再観測。画面から座標を推定する代わりに、要素の役割や名前、実行可能な操作をエージェントへ渡す。次に何をするかの判断は、呼び出し側に残す。 この分担を理解する鍵は、参照IDがスナップショットに属する点にある。UIが変われば再取得が必要になり、操作後の成功確認もエージェントが担う。また、既定の「ヘッドレス」は前面化と合成入力を禁止するモードを指す。Linuxではグラフィカルセッションが必要であり、画面環境なしで動くことを意味しない。
ポッドキャスト形式で聴く
約4分AI生成の会話音声です。記事の要点を短くまとめています。
なぜ注目されているか
11月3日の取得時点でGitHub日次Trending首位、当日増加2,275スターを記録した。リポジトリの後続取得では総スター数10,220、フォーク数687。これらは注目度の観測値であり、操作精度やOS間の機能同等性を裏付けるものではない。
なぜ重要なのか
注目したいのは、デスクトップ操作の対象と失敗を、呼び出し側が扱える契約として表す設計だ。参照ID、利用可能な操作、再試行可否を含むエラーがあれば、エージェントは状態を読み直す条件を明示できる。対象アプリが十分なアクセシビリティ情報を公開し、この契約が各OSで機能するなら、操作ループを組み立てる際の足場になる。ただし、画面理解や操作の成否をツールだけに委ねられるわけではない。観測の鮮度、対象の選択、結果確認を呼び出し側が管理するという責任分担まで含めて評価する必要がある。
この記事に出てくる言葉(6語)
- アクセシビリティツリー
アプリがOSのアクセシビリティ機構を通じて公開するUI要素の構造。agent-desktopはここから要素の役割、名前、利用可能な操作などを取得する。
- スナップショット
対象アプリとウィンドウの観測結果を、snapshot_id付きのツリーとして表したもの。操作に使う参照IDの取得元になる。
- 参照ID
スナップショットと要素を組み合わせて操作対象を指定する識別子。@s8f3k2p9:e8のように表し、要素部分だけの@e8は受け付けない。
- ヘッドレス実行
本ツールでは、アプリの前面化と合成入力を禁止し、アクセシビリティAPIで操作する既定モード。グラフィカルセッションの不要化とは異なる。
- JSONエンベロープ
各コマンドの結果を包む共通形式。okと、成功時のdataまたは失敗時のerrorを持つ。
- C ABI
提供ライブラリをプログラム内から呼び出すためのインターフェース。CLIの都度起動を避けられる一方、ABI整合やメモリ所有権などの確認が必要になる。
1. 読む前に知っておきたいこと
操作対象をどう表現するか
デスクトップを操作するエージェントには、対象の発見と、操作後の確認が必要になる。比較対象となるのは、スクリーンショットを読み、見た目や座標から対象を推定して入力し、再び画面を確認する方式だ。この方式では、視覚的な位置の推定だけから、要素の役割や実行可能な操作を直接扱うのは難しい。
READMEによれば、agent-desktopはピクセル照合を使わず、OSのアクセシビリティツリーを主要な観測経路にする。エージェントへ渡すのは、要素のrole、name、ref_id、available_actionsを含む構造だ。位置を手掛かりにする方式との違いは、操作対象を要素として表現できる点にある。ただし、両方式の速度や成功率を比較した定量データは取得資料にない。構造を得られることと、あらゆる画面で優位であることは分けて考えたい。
必要なのは観測を更新する仕組み
構造化した要素を得ても、UIが変化すれば以前の観測は古くなる。同じアプリに複数のウィンドウがあれば、アプリ名だけでは対象を決められない。要素の多い画面では、ツリー全体から対象領域を見つける負担もある。
agent-desktopは、スナップショットに属する参照ID、ウィンドウの明示選択、ツリーの絞り込みを用意する。ここでの設計課題は、要素一覧の取得だけではない。どの観測に基づく対象なのかを操作へ引き継ぎ、古い参照や曖昧な対象が返されたら観測し直すことだ。ツールはそのための情報を提供するが、目的を解釈して次の操作を選ぶループはエージェント側に置かれる。
注目の勢いと技術的な裏付け
2026年11月3日の観測ではGitHub日次Trending首位で、当日2,275スター増、総スター数10,218だった。後続のリポジトリ取得では10,220スター、687フォークとなっている。取得済みリリース一覧の先頭はv1.0.2で、公開日時は10月30日21時17分30秒UTC、日本時間では10月31日だ。
これらは関心の強さと公開状況を示す。操作精度や運用上の安定性を証明する数字ではなく、公開予定日の11月6日時点の勢いでもない。本稿の技術説明は取得済みREADMEに基づく。ソースコードやOS別の実行結果による独立検証はなく、READMEのHEAD取得内容がv1.0.2と一致するかも未確認だ。
2. どう動くのか
独立したCLI呼び出しをJSONでつなぐ
READMEによれば、CLIの各呼び出しは独立したプロセスとして動作し、結果は単一のJSONエンベロープで返る。成功時はokとdata、失敗時はokとerrorという共通形式になる。呼び出し側は、コマンドごとに返された状態やエラーを読み、次の呼び出しを組み立てる。
下にはmacOS、Windows、Linux向けのOS別アダプターがあり、それぞれ対象OS上でのみビルドする。LinuxのアクセシビリティツリーにはAT-SPIを使う。共通のCLIとJSON形式は、このOS別の処理を呼び出すための窓口になる。ただし、インターフェースが共通であることから、各環境で全操作が同じように使えるとは判断できない。
スナップショットから操作候補を読む
最初に対象アプリへsnapshotを実行する。READMEのJSON例では、結果にapp、window、snapshot_id、ref_count、complete、treeがあり、ツリー内の要素にはrole、name、ref_id、available_actionsが含まれる。エージェントは要素の役割と名前を読み、利用可能な操作を確認して対象を選ぶ。
同じアプリに複数ウィンドウがある場合は、AMBIGUOUS_TARGETと候補IDが返る。呼び出し側が--window-idで対象を指定し直すため、アプリ名だけで操作先を決める必要はない。密なUIには--skeletonで大枠を取得し、--rootへ参照IDを渡して対象領域を絞る経路がある。全要素を一度に読み込む以外の観測手段が用意されているわけだ。
参照は観測時点とセットで使う
READMEの操作例は、Finderのsnapshotを取得し、返された参照IDへclickを実行し、再度snapshotを取得する流れだ。参照の例は@s8f3k2p9:e8で、スナップショットと要素を組み合わせている。裸の@e8はINVALID_ARGSで拒否される。要素部分だけを切り出して使い回す契約にはなっていない。
UIの変化によりSTALE_REFやAMBIGUOUS_TARGETが返った場合は、新しいスナップショットを取得し、その参照へ切り替える。操作後も再観測し、目的の状態になったかを呼び出し側が判断する。参照IDは結果確認を省くための仕組みではなく、観測と操作を結び付ける仕組みと捉えると理解しやすい。
一方、独立したCLIプロセス間で参照情報をどこに保存するか、参照の具体的な寿命、対象照合のアルゴリズムは取得資料から分からない。形式と失効時の対応は説明されているが、対象を取り違えない保証の詳細まで確認できたわけではない。
入力の許可と再試行を明示する
既定のヘッドレス実行では、前面化と合成入力が禁止される。READMEによれば、参照先への操作はアクセシビリティAPIを通じて行い、ポインター移動やフォーカス取得を伴わない。物理入力を許可するには、グローバルな--headedフラグを指定する。操作経路の選択は、実行時に許す入力の範囲にも関わる。
失敗時の応答にはcode、disposition、通常はsuggestionが含まれる。READMEの契約では、disposition.retryがsafeの場合に限って再試行する。したがって呼び出し側には、エラーを受けたら同じ操作を無条件に繰り返すのではなく、再試行可否と再観測の必要性を読む処理が求められる。なお、前面化や合成入力の禁止を各OSでどう強制しているかは、取得資料だけでは確認できない。
プログラム内から使う経路
CLI以外には、C ABIライブラリのlibagent_desktop_ffiがある。READMEによれば各リリースで三つのOS向けに提供され、CLIを呼び出しごとに起動せず、プログラム内から機能を利用できる。CLIで確かめた操作をプログラムへ組み込む場合の選択肢になる。
この経路ではABIバージョンの整合、メモリ所有権、スレッド規則を確認する必要がある。呼び出し境界をプロセス間からプログラム内へ移すことで、利用側が守る契約も変わる。CLI起動時間やC ABIとの比較条件は取得資料にないため、速度向上の幅や実行コストの差は評価できない。
3. 使いどころと限界
再観測できるエージェントに組み込む
適するのは、アクセシビリティ情報を公開するデスクトップアプリを対象に、操作ごとにJSONを読み直せるエージェントだ。参照が古ければ取得し直し、ウィンドウが曖昧なら選び直す。こうした分岐を持つワークフローで、観測と操作の共通形式が役立つと考えられる。
画面の見た目や座標から対象を推定する方式に対しては、要素の役割と参照で対象を指定する経路を提供する。ただし、エージェントの判断ループは別途必要だ。また、アクセシビリティ情報が乏しい独自描画UIでは、対象が十分に現れるか個別検証が要る。これは観測経路からの推論であり、取得資料にアプリ別の対応検証はない。視覚・座標方式を全面的に置き換えられるとの根拠もない。
OS対応と実行環境の条件
macOSではアクセシビリティ権限が必要になる。Linuxではユーザーのグラフィカルセッションとat-spi2-coreが必要で、これらを用意できない実行環境は適さない。Windowsの「追加許可不要」という説明は、端末と同じ整合性レベルのアプリが対象だ。権限条件を外して一般化することはできない。
Linux内にも機能差がある。マウス入力とウィンドウ制御はX11、通知はGNOME Shell、Waylandのスクリーンショットはポータルを使い、Waylandのクリップボードにはwl-clipboardが必要になる。採用時は「Linux対応」という区分だけで判断せず、必要な操作と実行環境を照合したい。ヘッドレスのまま物理入力や前面化を必須とする処理も、この既定モードには合わない。
コマンド数より実行可能範囲を見る
READMEでは60コマンド名のうち実動作するのは56とされる。key-down、key-up、mouse-down、mouse-upは、保持したキーやボタンを解放できるデーモンが用意されるまで実行を拒否する。名前が列挙されていることと、実行できることには差がある。保持入力を前提にした処理では、この制約が直接効く。
v1.0.2というリリース番号だけから、APIの安定性や全OSでの動作範囲は判断できない。取得資料には操作成功率や定量ベンチマークもない。導入判断では、必要なアプリと操作について、観測、操作、再観測が成立するかを確かめる必要がある。
観測データの扱いも運用に含める
スナップショット、クリップボード読み取り、スクリーンショット、コマンド出力、デバッグ成果物には、私的なデスクトップ情報が含まれ得る。JSONで扱えることは、内容の機密性が低いことを意味しない。呼び出し側で結果をどう保存し、扱うかも導入時の確認対象になる。
さらに、任意のJEVヘルパーは画面の説明を設定済みモデルプロバイダーへ送る。OSのアクセシビリティ情報を読む経路と、この外部送信の条件は区別して確認したい。取得資料だけでは、機密情報の保存先、保持期間、削除方法、JEVの詳しい送信内容と送信条件を確定できない。権限の付与だけでなく、観測結果の流れまで把握する必要がある。
このツールから考える
ここからは、一次情報と限界を踏まえた編集上の考察です。
READMEのFinderの例は、snapshot、参照IDへのclick、再度のsnapshotという短い流れで、この設計の責任分担を示している。ツールが観測と操作を提供し、エージェントが結果を読んで次を決める。アクセシビリティ情報が十分に得られるなら、デスクトップ自動化を、状態と対象を明示して進めるワークフローとして設計しやすくなるだろう。
その場合、エンジニアが引き受けるのは、観測を更新する条件と、結果を確認する基準の設計になる。同時に、機械可読になったデスクトップ情報をどこへ保存し、どこへ送るかも管理対象になる。構造化は判断の材料を増やすが、情報の扱いまで自動で決めてはくれない。今後確かめたいのは、実際のアプリで再観測がどこまで有効に働くかと、その観測データを扱う運用条件だ。
検証に使用した一次情報
DevTool Lensでは、第三者の二次情報やREADMEの宣伝文句に依存せず、以下の公式リポジトリ・ドキュメント・リリース情報を精査して記事を作成しています。
- [readme]vercel-labs/agent-desktop README
- [repo]vercel-labs/agent-desktop GitHub Repository
- [release]vercel-labs/agent-desktop Releases
- [github_trending]GitHub Trending Daily (2026-11-03)