agent-desktopとは。AIにパソコンのアプリを操作させる道具を整理して、試す前に決める3つ

家事と子育てのスキマで経営する3方よしAI共創コンサルタントの田中啓之、ひろくん（@passion_tanaka）です。今回は、minheoさんのXの投稿が紹介した、AIにパソコンのアプリを操作させる道具agent-desktopのREADMEを読んで整理します。READMEは、Vercel LabsのGitHubのリポジトリに置かれている説明書のことです。

この投稿は、私が保存したブックマークの1つです。取り上げた理由は、確かめることと変えることを分けて考える話や、AIの作業に私の窓と入力先を取られる困りごとを、過去に私の記事で書いてきたからなんですよね。同じ向きで読める実例だと感じました。

読み進める順番は、agent-desktopとは何か、画面の写真で見る方式との違い、見る・触る・確かめるの繰り返し、邪魔しない動かし方、つなぎ方、読み取られる情報とできないこと、試す前に決める3つ、の7章です。私はagent-desktopを動かして確かめたわけではなく、元ネタを読んで整理した記事です。

GitHubのREADME（agent-desktopとは）

agent-desktop gives an AI agent computer use without screenshots or pixel matching.

READMEの冒頭の一文は、スクリーンショットも、画素の見た目合わせも使わずに、AIエージェントがコンピューター操作をできるようにする、と言っています。

READMEによると、agent-desktopはVercel Labsのリポジトリにある道具で、デスクトップのアプリをAIエージェントが見て操作するためのものです。

macOS・Windows・Linuxに対応します。対象は、手元のパソコンのアプリ。

仕組みの中心は、アプリのアクセシビリティツリーです。画面の読み上げソフトなどが使う、ボタンや文字欄の一覧を木の形で持った情報のことなんですよね。

agent-desktopはこれをJSON、つまり項目を波かっこで並べた、機械が読みやすい文字の形式で返し、押せる要素ごとに名札、READMEの言葉でいうrefを付けます。

動かし方は2つの形があります。コマンドの形で動かすCLI、つまり文字の命令で道具を動かす方式と、プログラムから呼べるC言語のライブラリです。どちらも中身は同じ、とREADMEは書いています。

READMEは、見る・触る・確かめるの繰り返しは呼び出す側のエージェントが持ち、agent-desktopの中にAIのモデルは入っていない、とも書いています。

公式ドキュメントはさらに、専用の画面も、対話の問いかけも持たず、コマンドは1回動くとJSONの答えを1つ返して終わる、と説明しています。

公式ドキュメントの言い方は「エージェントが呼ぶ道具で、エージェントそのものではない」。ここは大事な線引きです。

私の読みでは、私たちが使っているClaude Codeのようなエージェントに、パソコンの画面を触る手足を足す部品です。

例えば、予定表や請求書のアプリをAIに触らせたい時に、考え始める入口になる部品かな、と読みます。

minheoさんのXの投稿（韓国語・写真を見る方式）

기본 컴퓨터 유즈는 스크린샷을 보고 좌표를 눌러요.

章頭の引用は韓国語で、日本語にすると「標準のコンピューターユースは、スクリーンショットを見て座標を押します」という意味です。

minheoさんの投稿（2026年11月9日）は、GrokBotやClaude Codeにコンピューター作業をさせるなら、agent-desktopを付けてみてほしい、と書いています。

画面を写真として見る代わりにアプリの構造を直接読むので、AIが読み書きする文字の量をかなり節約できて、自分はこれに乗り換えた、という内容です。

読む文字が減れば、AIの仕事も軽くなる、という話なんですよね。

投稿が挙げる違いは4つです。(1)画像でなく文字で読むので、画面上の位置を合わせる必要がない。(2)既定ではマウスとフォーカス、つまりキーボードの入力先を触らないので、ほかの作業とぶつからない。

(3)画面が変わるとSTALE_REFという知らせで教えてくれるので、読み直して続けられる。(4)やり直してよい失敗かどうかが応答に書いてある。

投稿の最後は、ボットのコンピューター作業で困るのは遅さか、的外れな所を押してしまうのか、それとも読み書きする文字の量なのか、という問いかけです。読む人にも答えを聞く形なんですよね。

投稿は韓国語で書かれていて、紹介先はGitHubのvercel-labs/agent-desktopです。macOS・Windows・Linuxで使える道具だと添えています。

私の読みでは、同じ画面を触る作業でも、写真の中から押す所を目で探す方式と、名前の付いた部品を一覧表から探す方式では、探し方が違います。後者は、位置がずれても名前で見つけられる形かな、と受け取りました。

GitHubのREADME（見る・触る・確かめる）

The agent clicks or types on a ref, reads the UI again to check the result, and repeats.

章頭の引用は、エージェントが名札を指定して押すか入力し、もう一度画面を読んで結果を確かめ、それを繰り返す、という意味です。

READMEのクイックスタートは3手です。Finderを対象に、押せる要素を名札つきで一覧にして（snapshot）、その名札を指定して押して（click）、もう一度一覧にして結果を確かめる。

FinderはMacの標準のファイル管理アプリです。

READMEの例では、Finderの一覧に名札が59個あり、「Documents」というフォルダの項目に、押せる印が付いています。

名札は、その一覧を作った時の画面にだけ有効で、名札だけを裸で指定すると受け付けられません。

画面が変わると、STALE_REF、つまりその名札はもう古い、という知らせか、AMBIGUOUS_TARGET、つまり対象が複数あって決められない、という知らせが返ります。

その時は、新しく一覧を取り直す。窓が複数ある時も同じで、候補の窓の番号が返ります。

AI氣道『MCPとは。AIが外部サービスを使う共通の窓口と、CLIとの違いを整理』より

「確かめることと、変えることは、別の承認として分けておきます」

確かめることと変えることを分けると、私は『MCPとは。AIが外部サービスを使う共通の窓口と、CLIとの違いを整理』で書いています。

Slackのように要素が多いアプリは、先に骨組みだけを見る機能（skeleton）で全体を見てから、気になる領域だけを掘り下げる、とREADMEは書いています。地図を先に見てから拡大する順番ですよね。

名札を取った時の画面が基準になる、というのがこの方式の約束事です。

私の読みでは、一覧を読むだけの操作は「確かめること」、押す、入力するといった操作は「変えること」と分けて眺められます。

AIにどこまで押させるかを決める時に、確かめる段と変える段を別々に見る物差しになる、と読みました。

GitHubのREADME（既定の動き）

Headless by default. Ref actions use the accessibility API without moving the pointer or taking focus.

章頭の引用は、既定では物理的な入力を使わず、名札を使う操作はポインタを動かさず、フォーカスも奪わない、という意味です。

READMEによると、名札を使う操作は、アクセシビリティのAPI、つまりアプリが公開している操作の窓口を通して行います。ポインタは動かず、フォーカスも奪わない。

実際のマウスやキーボードの入力を許す時だけ、「–headed」という指定を付けます。

AI氣道『Cua Spaces SDKとは。AI専用のデスクトップをコードで作る方法を、動画と私の仮想Macの記録で読む』より

「中身は、ブラウザを開く作業が、私の窓とキーボードの入力先を横取りすること。」

AIの作業に窓と入力先を取られる困りごとを、私は『Cua Spaces SDKとは。AI専用のデスクトップをコードで作る方法を、動画と私の仮想Macの記録で読む』で書いています。

失敗した時の扱いも書かれています。READMEは、応答の中でretryが安全と書かれた場合だけ、再試行してよい、と言っています。うまくいかない時に、むやみに繰り返さない約束なんですよね。

押した後の待ち方も細かいです。待つ時は、名札を取った時の元の窓を見続けます。窓の中の名札は、その窓に結び付いたまま。macOSのアプリのメニューは、書類の窓がなくても使える、とREADMEは書いています。

私の読みでは、私が書いた困りごと、つまりAIの作業に窓と入力先を取られることと、agent-desktopの既定の動きは、向きが同じ側にあります。

邪魔をしないのが既定で、実際の入力を許すのは指定した時だけ。この順番は、使う側が考えやすい形かな、と読みます。

GitHubのREADME（MCP）

agent-desktop mcp serves every command as an MCP tool over stdio.

章頭の引用は、agent-desktop mcpというコマンドが、全部のコマンドをMCPの道具として、標準入出力の形で提供する、という意味です。MCPは、AIが外部の道具を使うための共通の窓口のことです。

MCPの形では、各コマンドが、desktop_snapshot、desktop_click、desktop_session_startのように、コマンド名のついた道具として呼べます。

名札を取る、押す、セッションを始める、が別々の道具になるんですよね。

使い方を教える方法は、READMEに2つ書かれています。1つ目は、スキル、つまりエージェントに覚えさせる手順書として入れる方法。2つ目は、AGENTS.mdに短い文を足す方法です。

AGENTS.mdは、エージェント向けの指示書のこと。書く内容は、最初に手引きを読んで従う、という短い文です。どちらも、実行ファイルに入っている手引きを、エージェントに読ませる形です。

手引きはそのバージョンに合う内容で、desktopの手引きと、OSごとの違いの手引きがあります。

コマンドは全部で61個あり、そのうち実際に動くのは57個。残る4つ、キーやマウスのボタンを押し続けて離す操作は、押したままの状態を離す仕組みが整うまで動かない、とREADMEは書いています。

コマンドのグループは10です。

観察（snapshotなど）、名札への操作（clickなど）、キーボードとマウス、アプリと窓、通知、クリップボード（コピーした内容の一時置き場）、待つ、セッション、サンドボックス（隔離した試し用の環境）、システム。

対応OSは、macOS 13以降（AX API）、Windows 10 1809以降（UI Automation）、Ubuntu 24.04以降（AT-SPI）です。

私の読みでは、MCPで道具として呼ぶことと、手引きを読ませて使い方を教えることは、別の話です。手元のエージェントが何を使っているかで、組み合わせ方が変わるかな、と読みます。

GitHubのREADME（私的な内容の扱い）

Snapshots, clipboard reads, screenshots, command output, and debug artifacts can contain private desktop content. Keep them out of public logs and uploads.

章頭の引用は、画面の一覧・クリップボードの読み取り・スクリーンショット・コマンドの出力・デバッグ用の記録に、手元の画面の私的な内容が入りうるので、公開のログやアップロードには出さない、という意味です。

READMEが挙げているのは、5種類です。画面の一覧（スナップショット）、クリップボードの読み取り、スクリーンショット、コマンドの出力、デバッグ用の記録。

どれも、手元の画面に映っていた内容が残りうる、ということです。

入力や貼り付けは、文を別の入力経路（–stdin）で渡せば、プロセスの引数、つまり動かしている最中の命令の一部に残さずに済む、とREADMEは書いています。

パスワードのような秘密を扱う手順は、独立した別のコマンドにする、とも書いています。

AI氣道『ローカルLLMはどこまで実用か、外のAIに渡す前に手元で個人情報を置き換える』より

「私なら、AIに渡す前に、家族とクライアントの情報を、渡す物と渡さない物に分けます！」

渡す物と渡さない物を先に分ける話を、私は『ローカルLLMはどこまで実用か、外のAIに渡す前に手元で個人情報を置き換える』で書いています。

公式ドキュメントは、できないことも書いています。デスクトップのアプリだけが対象で、ウェブページの自動操作はしません。ウェブはagent-browserという別の道具を使う、という分担です。

アプリが公開している情報の範囲しか読めず、画素を見て合わせることはしないので、アクセシビリティツリーを出さない画面は見えない、とも書いています。

私の読みでは、画面の中身を読まれる道具だからこそ、使う前に、渡す物と渡さない物を分けておく。見えない画面がある、という限界も、最初に知っておくと期待がずれにくいかな、と考えます。

公式ドキュメント（ループは呼ぶ側が持つ）

The observe, act, and verify loop lives in the calling agent or script.

章頭の引用は、見る・触る・確かめるのループは、呼び出す側のエージェントやスクリプトが持つ、という意味です。

公式ドキュメントがこう書いている、ということは、何を任せ、どこで止めるかは、使う人が決める所に残る、ということですよね。道具が決めてくれるわけではない。

この記事の読み手が最後に持ち帰る1つは、試す前に、自分のことで人が決める所を3つ書き出す、です。あなたの仕事に置き換えて、紙に3行書くくらいの気持ちで十分です。

1つ目は、何を任せるか。どのアプリで何をする作業かと、最後に人が確かめる所。2つ目は、画面に映る情報のうち、AIに読ませてよい物と読ませない物の線。3つ目は、最初に試す1つ。

設定の変更も送信もしない、押さずに読むだけの小さな作業のような、すぐ戻せるものです。

AI氣道『AIエージェントに作業は任せても判断は任せない、まさおさんが語るマネジメントの習慣』より

「私なら、入口と出口は自分が持ち、中間はAIに任せます。」

入口と出口は自分が持つ考え方を、私は『AIエージェントに作業は任せても判断は任せない、まさおさんが語るマネジメントの習慣』で書いています。

私の考えでは、任せる前、つまり入口と、任せたあと、つまり出口を自分で持つ、というのは、3つの書き出しの1つ目にそのまま当たります。何を任せるかが入口、最後に確かめる所が出口です。

最初は、お客様や取引先に関わる画面ではなく、自分だけが見る画面から。そう考えると、2つ目の線も引きやすくなると思います。この記事の末尾に、AIエージェントに渡す依頼文の囲みがあります。

agent-desktopは、AIが画面の写真ではなく、アプリの構造を文字で読み、名札を押して操作する道具でした。READMEによると、見る・触る・確かめるの繰り返しは呼び出す側のエージェントが持ち、中にAIのモデルは入っていません。

minheoさんの投稿は、4点を挙げていました。文字で読むので位置を合わせる必要がない。マウスとフォーカスを触らない。STALE_REFで読み直せる。再試行してよい失敗かどうかが書いてある。あわせて、AIが読み書きする文字の量を節約できること、自分は乗り換えたことも書いています。

私の読みでは、確かめることと変えることを分ける、AIの作業に窓と入力先を取られない、渡す物と渡さない物を分ける、入口と出口は自分が持つ。私の過去の記事の考え方が、この道具の説明と同じ向きに並びました。

最初は、自分だけが見る画面の、押さずに読むだけの作業から考えてみませんか？ 決めることの中身は、第7章に書いたとおりです。

この記事で学んだことを誰かに教えて恩送りして学びを深めよう！