title: "agent-desktop入門メモ：CLIのコマンド、エラーの意味、つまずきやすい点を公式READMEから整理する"
tags:
- AI
- AIエージェント
- Rust
- CLI
- agent-desktop
private: false
はじめに
Vercel Labsのagent-desktopは、AIエージェントがデスクトップアプリを操作するためのRust製CLIである（※1）。2026-11-05時点でGitHubのスターは約11.8kで、ある自動ダイジェストでは1日で+3,791と記録されていた（※2）。
この記事は、使い方とつまずきやすい点を手早く確認するためのメモである。仕組みの全体像や評価は、別に書いたZennの記事にまとめる予定である。
重要な前置き：筆者は今回、インストールも実行もしていない。作業環境で、外部コードを実行するコマンドが許可されなかったためである。以下のコマンドは、公式READMEの記述を引用・整理したもので、動作はすべて未検証である。
1. 何ができるツールか
OSのアクセシビリティの仕組みを使い、アプリの画面を「操作可能な要素の一覧」として読み取る。各要素にrefという参照IDが付き、clickなどの操作にそのrefを渡す（※1）。画像から座標を推定する方式ではない。
出力は、すべてJSONである。okと、成功時のdata、失敗時のerrorが入る。
2. インストール
READMEに書かれている方法は、次のとおりである（※1）。
npm install -g agent-desktop
agent-desktop version
- npmのパッケージには、x64とARM64向けのネイティブバイナリと、OSごとの補助部品が含まれる。
- Bun、Yarn、pnpmでも入れられる。
- GitHubのReleasesから直接ダウンロードする方法もある。
- HomebrewとScoopのパッケージは、申請中で、標準のカタログにはまだない。
確認しておきたいこと
リリースページが空だったため、版数と公開日は一次情報で確認できなかった。READMEの例にある"version": "2.6"は、出力JSONの形式のバージョンで、製品の版数ではない。必ずagent-desktop versionの出力を記録しておく。
3. OSごとの事前設定
| OS | 必要なこと（READMEの記述） |
|---|---|
| macOS | アクセシビリティの許可。agent-desktop permissions --guideで案内が出る |
| Windows | ターミナルと同じ権限レベルのアプリなら、特別な許可は不要 |
| Linux | グラフィカルなセッションとat-spi2-core
|
macOSの許可は、強い権限である。許可を与えるターミナルは、必要なものだけにしておきたい。
4. 基本の3ステップ
READMEの例である（※1）。
agent-desktop snapshot --app Finder -i # interactive elements, each with a ref
agent-desktop click @s8f3k2p9:e8 # act on a ref from that snapshot
agent-desktop snapshot --app Finder -i # observe again to verify
-
snapshot：対象のアプリ（--app）の、操作可能な要素（-i）を取得する。 -
click：snapshotの結果にあったrefを指定して、クリックする。 - もう一度
snapshot：画面が変わったかを確認する。
図：snapshotから再確認までのループ
refの読み方
@s8f3k2p9:e8は、@のあとに「スナップショットのID」、:のあとに「要素の番号」が続く形と読める。この読み方は、READMEの例と説明からの推測で、正式な仕様の説明は確認できていない。
5. エラーの意味と対処
READMEには、次のエラーが出てくる（※1）。
| エラー | 意味 | 対処 |
|---|---|---|
STALE_REF |
refが、すでに古くなっている | snapshotを取り直し、新しいrefを使う |
AMBIGUOUS_TARGET |
対象が1つに決まらない |
--window-idでウィンドウを指定する（複数ウィンドウの場合） |
エラーには、コード、対処の区分（disposition）、多くの場合は提案（suggestion）が付く。エージェントに渡すときは、errorの部分をそのまま見せると、次の行動を選びやすくなる。
6. つまずきやすい点
READMEの「制限」の記述から、実際に引っかかりそうな点を整理した（※1）。
6.1 refは単独で書けない
@e8のように、スナップショットIDのない書き方は拒否される。必ず、スナップショットIDを含む形で指定する。
6.2 PowerShellでは引用符が要る
PowerShellでは、先頭の@が「スプラッティング」という別の機能の記号になる。refは、引用符で囲む。
agent-desktop click '@s8f3k2p9:e8'
上のコマンドは、READMEの注意書きを受けて筆者が書いた例である。実行して確かめてはいない。
6.3 ウィンドウが複数あると曖昧になる
同じアプリのウィンドウが複数あると、AMBIGUOUS_TARGETになる。--window-idでウィンドウを指定する。
6.4 押しっぱなしの操作は未対応
key-down、key-up、mouse-down、mouse-upの4つのコマンドは、一覧には載っているが、押したキーやボタンを確実に離すデーモンが用意されるまで、実行が拒否される。ドラッグのような操作は、現時点では難しい可能性がある。
6.5 Linuxは環境差が大きい
Linuxの対応は、表示サーバーによって異なる。Waylandでは、スクリーンショット、クリップボード、マウス入力に制限がある。クリップボードにはwl-clipboardが要る。X11では、マウス入力に--headedを使う。
7. 既定の動きと--headed
refを使う操作は、既定でアクセシビリティAPIを使い、ポインタの移動やフォーカスの奪取をしない。物理的な入力が必要なときだけ、グローバルオプションの--headedを付ける（※1）。
人間が作業しているパソコンで、裏側でエージェントを動かす場合は、この既定の動きが助かる。
8. エージェントに使い方を調べさせる
次のコマンドで、バイナリが持つドキュメントを取得できる（※1）。
agent-desktop skills get desktop
agent-desktop skills get platform
エージェントのプロンプトに、「まずこれを実行して、使い方を読むこと」と書いておけば、外部のドキュメントを渡す手間を減らせると思われる。ただし、この使い方の有効性は、未検証である。
9. 自作エージェントから呼ぶときの設計メモ
ここからは、筆者の設計案である。動作確認はしていない。
9.1 ループの形
エージェントの基本ループは、次のようになる。
-
snapshotを取る。 - JSONの
treeから、操作する要素を選ぶ。 -
clickや入力のコマンドを実行する。 -
okがfalseなら、errorを読む。STALE_REFなら、手順1に戻る。 - 成功なら、もう一度
snapshotで、画面の変化を確認する。
READMEが「操作したら、もう一度観察して確かめる」流れを例示しているため、ループの形は、公式の想定に沿っていると考える。
9.2 JSONをどう扱うか
出力は1コマンドにつき1つのJSONエンベロープである。そのため、標準出力を丸ごとJSONとして読み取れる。次は、Pythonで読み取る場合の最小の例である（筆者の例で、未実行）。
import json
import subprocess
def run(*args: str) -> dict:
# agent-desktopを呼び、JSONエンベロープを辞書にして返す
out = subprocess.run(
["agent-desktop", *args],
capture_output=True,
text=True,
check=False,
)
return json.loads(out.stdout)
result = run("snapshot", "--app", "Finder", "-i")
if result.get("ok"):
print("snapshot ok")
else:
print("error:", result.get("error"))
- 言語とバージョン：Python 3.10以上を想定（標準ライブラリのみ）。
-
ok、data、errorのキー名は、READMEの説明に基づく。内部の構造は、実際の出力を見て確認する必要がある。
9.3 JSONの大きさに注意
アプリによっては、要素の数が多くなる。LLMに渡す前に、必要な部分だけに絞る工夫が要るかもしれない。どれくらいの量になるかは、筆者は確認していない。
10. セキュリティのメモ
- スナップショット、スクリーンショット、クリップボードの読み取りには、個人的なデータが入りうる。公開のログに出さない（※1）。
- オプションの「JEV」ヘルパーは、画面の説明を、設定したモデルのプロバイダーへ送る（※1）。使う前に、送られる情報を確認する。
- メールやパスワード管理のアプリは、エージェントの対象から外しておくのが無難である。これは筆者の運用案である。
11. 試すときのチェックリスト
-
agent-desktop versionで版数を記録した -
OSの権限（macOSなら
permissions --guide）を確認した -
テスト用のアプリで
snapshotを実行できた -
古いrefで
STALE_REFを確認した -
複数のウィンドウで
AMBIGUOUS_TARGETを確認した - ログに機微な情報が残らないことを確認した
12. 評価（簡単に）
失敗がエラーとして返る設計と、一貫したJSON出力は、エージェントから使いやすそうである。一方で、リリースの版数を確認できず、未対応コマンドがあり、Linuxの環境差も大きい。急にスターが増えた理由も、筆者は確認していない。仕組みと比較は、Zennの記事で整理した。
図：操作方式の定性的な比較。数値の比較ではない
まとめ
agent-desktopは、snapshotで要素の一覧とrefを取得し、clickなどで操作し、もう一度snapshotで確かめるという、シンプルな流れで使う。PowerShellの引用、複数ウィンドウの指定、押しっぱなし操作の未対応、Waylandの制限に注意したい。本稿の内容は公式READMEに基づくもので、筆者は未実行である。試すときは、版数と環境を記録しながら、小さく始めることを勧める。
※本記事の記載内容は筆者個人の見解であり、所属する会社や組織の立場や方針とは一切関係ありません。
筆者情報
【Tomcat-zhou】｜AI/AX/AIセキュリティ専門家
AI戦略洞察、AI駆動開発の方法論設計と現場で回る仕組みづくりをしています。
noteで戦略洞察 / Zenn・Qiitaで技術・方法論を書いています。
AIセキュリティ・AIコンサル・AIエージェント開発・AI活用・AI駆動開発教育、AI人材育成サービスを一体で提供。
X: @ZY20240528
LinkedIn: Tomcat-zhou
Facebook: zhou yi
note: Tomcat-zhou
zenn: Tomcat-zhou
参考資料
- vercel-labs/agent-desktop（GitHubリポジトリ・README）
- AI Open Source Trends 2026-11-04（agents-radar Issue #412）
タグ
AI AIエージェント Rust CLI agent-desktop