agent-desktop が読むのはスクリーンショットではなくアクセシビリティツリーです

スクリーンショットで動くコンピュータ操作エージェントは、どれも同じ高くつくループを回しています。画面を撮る。ボタンがどこにあるかを視覚モデルに尋ねる。答えをピクセル座標に変換する。クリックする。何か起きたかを確かめるために、もう一度撮る。
動きます。OCR が動くのと同じ意味で、見事ではあるけれど、放っておけるほど信頼できたことはありません。失敗の仕方はどれも同じ話に帰着します。ユーザーインターフェースの写真は、ユーザーインターフェースの非可逆な表現だということです。
Vercel Labs が公開した agent-desktop は別の道を行きます。現在およそ 23,300 スターで、この一週間で約 5,400 増えました。画面を見ません。対象アプリのアクセシビリティツリーを読んで JSON として返し、エージェントが操作できる要素のそれぞれに参照を付けます。エージェントは参照に対してクリックや入力を行い、結果を確かめるために UI をもう一度読み、それを繰り返します。

ループはあなたのエージェントの中にあります。バイナリにモデルは入っていません。
インストールと最初の接触
パッケージは npm のグローバルインストールです。
npm install -g agent-desktop
agent-desktop status
`status` はプラットフォーム、権限、対応しているサーフェスを報告します。最初に打つコマンドとしてこれは正解です。コンピュータ操作は、ロジックの段階より権限の段階でつまずくことのほうがずっと多いからです。macOS での次のコマンドは `agent-desktop permissions --guide` で、アクセシビリティの許可を順に案内してくれます。Homebrew も macOS と Linux で使えます。Bun、Yarn、pnpm でも同じパッケージが入ります。x64 と ARM64 のネイティブバイナリが同梱されています。
3 コマンドのループはこうなります。
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
`-i` フラグはスナップショットを操作可能な要素に絞ります。クリックはその特定のスナップショットから取った参照に対して行います。2 回目のスナップショットは気休めの後片付けではありません。クリックが思ったとおりに働いたかを知る手段が、これだからです。
効いてくる設計上の判断
このツールの上に何かを作る前に、理解しておく価値のある選択が 4 つあります。
参照はそのスナップショットに属します。単独の `@e8` は `INVALID_ARGS` で拒否されます。観察と操作の間にインターフェースが変われば、操作は `STALE_REF` か `AMBIGUOUS_TARGET` を返します。正しい対応は新しいスナップショットを取り、その参照を使うことです。多くの自動化ツールより厳しく、そのぶん気づかない誤クリックをまとめて消してくれます。
要素の多いアプリには 2 段階の調べ方が用意されています。Slack のようなアプリでは、まず `snapshot --skeleton --app Slack -i --compact` でアプリ全体を地図にし、次に `snapshot --root @s8f3k2p9:e3 -i --compact` で 1 つの領域に降ります。これがないと、複雑なアプリのツリー全体はエージェントが抱えるには多すぎる JSON になります。
既定はヘッドレスです。参照ベースの操作はアクセシビリティ API を通り、ポインタを動かさずフォーカスも奪わないので、エージェントが働いている間もマシンは使えます。グローバルの `--headed` フラグで物理入力に切り替わります。アプリが本物のイベントを検査する場合には必要で、それ以外では要りません。
秘密はプロセスの引数から外に出せます。`type`、`set-value`、`clipboard-set` は `--stdin` を受け取り、パイプからテキストを読みます。コマンドライン引数はプロセス一覧から見えるので、これはパスワードが `ps` の出力に現れるか現れないかの違いになります。README の助言は、秘密を扱う手順を別々のコマンドに分けることです。まとめて渡した JSON のテキストは引数リストに再び現れるからです。
PowerShell についての脚注が 1 つあり、これで 1 時間救われる人がいるはずです。参照はすべて引用符で囲んでください。裸の `@token` は splatting 演算子だからです。
プラットフォーム層の正体
CLI の下には C ライブラリがあり、その両方の下に同じコアがあります。各バイナリは 1 つの OS 向けにコンパイルされ、そのシステムのアクセシビリティ API と話します。macOS なら AX API、Windows なら UI Automation、Linux なら AT-SPI です。コアが OS に触れるのは `PlatformAdapter` トレイトを通してだけなので、1 つのコードベースが大きく異なる 3 つのアクセシビリティモデルの上で同じ JSON の封筒を出せます。
この構造はツールの上限も説明します。アクセシビリティツリーがさらしているものにしか働きかけられません。自前でキャンバスにインターフェースを描き、何もさらさないアプリは、アダプタがどれほどよくできていても見えないか、ほとんど見えません。スクリーンショット型のエージェントはそういうアプリを扱えます。参照型のエージェントには扱えません。よくできたアプリでの正確さと、できの悪いアプリへの対応範囲を引き換えにしているわけです。
動く例での比較
スクリーンショット型が苦手とする小さな作業を考えます。デスクトップのファイルマネージャで 12 個のファイルの名前を変える作業です。
スクリーンショット型のエージェントはウィンドウを見て、12 個のファイル名のラベルを見つけ、12 組の座標を作ります。1 つ目をクリックし、テキストを選択し、新しい名前を入力し、Enter を押し、リストが並べ替わるのを待ちます。この時点で残りの座標はすべて古くなっています。リストの順序が変わったからです。名前を変えるたびに観察し直す必要があり、それは 12 回の視覚呼び出しと、12 回の行を間違える機会を意味します。
参照ベースのやり方は 1 回だけ観察します。スナップショットは各行に参照を付けたウィンドウのツリーを返し、スナップショット id も添えます。名前の変更はそれぞれ特定の参照への操作で、操作のたびにエージェントはツリーを読み直し、新しい名前が出たことを確かめます。リストが並べ替われば元のスナップショットの参照は古くなり、ツールはそう告げます。これはまさに望ましい挙動です。間違ったファイルへの黙った操作ではなく、速くて明示的な失敗が返ります。
信頼性の差は、構造をどこで計算するかから来ます。前者ではモデルがピクセルからファイル一覧を再構成し、ときどき間違えます。後者では OS がもともと管理しているファイル一覧を報告し、まず間違えません。
セキュリティの注意は定型文ではありません
README には、言い換えずにそのまま引用する価値のある警告があります。スナップショット、クリップボードの読み取り、スクリーンショット、コマンド出力、デバッグ用の生成物には私的なデスクトップの中身が含まれうるので、公開ログやアップロードから遠ざけるべきだ、というものです。
これは現実の危険で、しかも新しい種類の危険です。スクリーンショット型のエージェントはピクセルを漏らします。ツリー型のエージェントは構造化されたテキストを漏らし、こちらは索引にも検索にも、うっかりしたコミットにもずっと引っかかりやすくなります。デバッグのためにエージェントの軌跡を記録しているなら、そのとき画面にあったものを記録しています。しかも grep が見つけられる形式で。
長く効いていく部分
Vercel Labs はこれをすでに 2 つ出しています。ウェブ向けの agent-browser と、ローカルアプリ向けの agent-desktop で、どちらも Rust 製、どちらも同じ週にトレンド入りしました。共通する型は、OS がすでにやった仕事をモデルにやらせない、という拒み方です。
ここで役に立つ考えはその一点にあり、個々のコマンドより重要です。スクリーンショットを読む視覚モデルは、アクセシビリティツリーにすでに存在する構造を推測していて、その推測に遅延とトークンと誤り率を払っています。ツリーを読むのはほとんどコストがかからず、返ってきたものはエージェントが検証できます。
本番に残るエージェントは、いちばん目がいいものではありません。見る必要がなくなったものです。
関連記事
Pinky は agent に自分のスマホを操作させる。送信ボタンは、あなたが許可を押すまで押さえたまま
Pinky はどんな MCP agent でも本物の iPhone や Android につなぎ、承認をプロンプトではなく自前のゲートウェイで強制する。銀行アプリは見えず、パスワード欄は通行止め、Android 13 では agent に隠れた2枚目の画面が渡される。
サーバー1台、AI配信者1人:夜のライブ配信を動かすコードの中身
open-yoki は、毎晩 Binance Square で配信する AI ホストの本番コードで、人格・声・お金に関わる機能は取り除かれています。headless Chrome がフレームを描き、ffmpeg が RTMP を押し、Markdown フォルダが彼女の気分と投稿内容を決めます。
SoduWork の依頼は、チャットが止まったときではなく、依頼した人が承認したときに終わる
SoduWork はセルフホストのワークベンチだ。依頼には着手前に受け入れ基準が書かれ、納品は別の harness がレビューし、最後は人が承認する。うまくいった進め方はプラグインとして保存され、チームの他の人がそのまま実行できる。
世界の法律を git に入れた人がいる。だから法令も blame できる
global-law は各国の法令を git リポジトリとして持ち、1 つの commit が既知の日に効力を持った 1 つの法律にあたる。条文に対して log、blame、show、diff を実行でき、ある日の各国の施行状況を調べ、コーパス全体を MCP 経由でアシスタントに渡せる。