lahfir/agent-desktop

これは何か

agent‑desktop は、macOSとWindows上でAIエージェントがグラフィカルなデスクトップアプリケーションを見るおよび制御することを可能にするコマンドラインツール（および付属のCライブラリ）です。オペレーティングシステムのアクセシビリティツリーを読み取り、UI要素のJSON記述をエクスポートし、安定したIDでこれらの要素を参照することで、クリック、タイピング、ウィンドウ管理、クリップボードアクセスなどを発行できます。

なぜ重要か

コードからGUIを制御することは、自律エージェントにとって古典的なボトルネックです。ほとんどのLLMベースのアシスタントはテキストAPIでのみ動作するため、人間が使用するアプリと直接やり取りできません。UIを構造化された機械可読なツリーとして公開し、豊富なアクションセットを提供することで、agent‑desktop はそのギャップを埋め、エージェントがマウスを動かしたりフォーカスを奪ったりすることなく、現実のデスクトップワークフロー（Finderでのレポート作成、Slackメッセージの送信、通知の却下など）を自動化できるようにします。

仕組み（高レベル）

1. スナップショット – agent-desktop snapshot --app <名前> はOSのアクセシビリティAPIを走査し、UI要素のJSONツリーを出力します。各要素には、属するスナップショットをエンコードする @s8f3k2p9:e3 のような参照が付けられます。
2. アクション – click、type、press、scroll、launch などのコマンドは、参照（またはキーショートカット）を受け取り、アクセシビリティレイヤーを通じて対応する入力を送信します。デフォルトではアクションはヘッドレス（目に見えるカーソルの動きなし）です。
3. 反復 – アクションの後、別のスナップショットを取得してUIが期待どおりに変更されたかを確認します。古いまたは曖昧な参照は報告され、エージェントは更新できます。
4. ライブラリモード – 同じ機能はC互換の共有ライブラリ libagent_desktop_ffi としてパッケージ化されており、他の言語のプログラム（例：Pythonの ctypes 経由）がCLIプロセスを起動せずに直接APIを呼び出せます。

誰が使うか

対象	ユースケース
AI研究所がデスクトップソフトウェアを操作する必要がある自律エージェントを構築。
パーソナルアシスタントの開発者（例：ChatGPTスタイルのボット）がテキストのみのアクションを超えて拡張したい。
自動化エンジニアが、壊れやすい画面スクレイピングツールを使わずにUIタスクをスクリプト化するプログラム的でクロスプラットフォームな方法を探している。
ツールメーカーがFFIライブラリを介してデスクトップ制御機能を自社アプリケーションに組み込みたい。

はじめに（クイックステップ）

# CLIをインストール（ネイティブバイナリを含む）
npm install -g agent-desktop

# macOSのアクセシビリティ権限を付与（またはWindowsで必要に応じて実行）
agent-desktop permissions --request

# Finderのスナップショットを取得し、インタラクティブな要素を一覧表示
agent-desktop snapshot --app Finder -i

# 最初の要素をクリック（参照を取得したものに置き換えてください）
agent-desktop click @s8f3k2p9:e3

# UIが変更されたか確認
agent-desktop snapshot --app Finder -i

プログラムでの使用については、READMEのPythonスニペットが共有ライブラリの読み込みと初期化を示しています。

強みと制限

強み	制限
• macOSとWindowsの両方でそのまま動作。
• ヘッドレス操作でユーザーのマウス/キーボードを妨げない。
• 安定した参照を含む構造化JSONを返すため、エージェントがUI状態を推論しやすい。
• プロセス内使用のためのフル機能のFFIライブラリを提供。
• 幅広いアクション（クリック、タイピング、ウィンドウ管理、通知、クリップボードなど）をカバー。
• Apache-2.0の下でオープンソース、CIとテスト付き。
• Linuxサポートを計画中。
• エージェント向けの統合された「スキル」ガイド。
• npmを介したバイナリ配布でインストールが簡単。
• macOSの詳細な権限処理。
• 明確なエラーコード（STALE_REF、AMBIGUOUS_TARGET）。
• バッチコマンドとセッショントレースをサポート。
• Windowsのシェルサーフェス（タスクバー、スタートメニュー）で操作可能。
• OSのアクセシビリティAPIを使用 – ピクセルマッチングより信頼性が高い。
• SeleniumやAutoItなどの外部UI自動化ツールは不要。
• ARM64とx64の両方のアーキテクチャをサポート。
• エージェントアクションの視覚的デバッグ用の「カーソルオーバーレイ」を提供。
• LLMプロンプトのトークン数を減らすためのスケルトンスナップショットを取得可能。
• skills システムで拡張可能。
• CIバッジはアクティブなテストを示す。
• リリースバイナリはチェックサムで検証済み。
• CDPを介したChromiumアプリの起動をサポート。
• システム通知の一覧表示と却下が可能。
• クリップボードを直接操作可能。
• プログラムでウィンドウのサイズ変更/移動が可能。
• マルチエージェントセッションをサポート。
• 複数のアクションをまとめる batch コマンドを提供。
• エージェントの動作デバッグ用の trace コマンドを提供。
• エージェントカーソルを視覚化する cursor-overlay を含む。
• UIサーフェスを列挙する list-surfaces をサポート。
• screenshot コマンドでスクリーンショットを取得可能。
• 発見用の list-apps と list-windows を提供。
• Windowsで open-system-surface をサポート。
• ChromiumでCDPを介してアプリを起動可能。
• 同期用の wait コマンドをサポート。
• 永続コンテキスト用の session 管理を提供。
• エージェントガイダンス用の skills 取得を提供。
• ヘルスチェック用の status コマンドを含む。
• permissions のクエリとリクエストをサポート。
• version 情報を提供。
• list-notifications とそれらに対するアクションを提供。
• 通知と対話する notification-action をサポート。
• clipboard-get、clipboard-set、clipboard-clear を提供。
• マルチモニターセットアップ用の list-displays をサポート。
• focus-window、resize-window、move-window をサポート。
• minimize、maximize、restore をサポート。
• Windowsで open-system-surface をサポート。
• Chromiumアプリ向けCDPで launch をサポート。
• list-apps、list-windows をサポート。
• list-displays をサポート。
• list-notifications をサポート。
• clipboard コマンドをサポート。
• wait をサポート。
• session と trace をサポート。
• cursor-overlay をサポート。
• batch をサポート。
• skills をサポート。
• status をサポート。
• permissions をサポート。
• version をサポート。
• トークンサイズを減らす --skeleton と --compact 付きの snapshot をサポート。
• UI要素を照会する find、get、is をサポート。
• list-surfaces をサポート。
• scroll、scroll-to をサポート。
• expand、collapse をサポート。
• select、toggle、check、uncheck をサポート。
• clear、focus をサポート。
• type、set-value をサポート。
• click、double-click、triple-click、right-click をサポート。
• press、hover、drag、mouse-move、mouse-click、mouse-wheel をサポート。
• key-down、key-up、mouse-down、mouse-up（デーモン待ち）をサポート。
• launch、close-app をサポート。
• list-apps、list-windows をサポート。
• list-displays をサポート。
• focus-window、resize-window、move-window をサポート。
• minimize、maximize、restore をサポート。
• open-system-surface をサポート。
• list-notifications、dismiss-notification、dismiss-all-notifications をサポート。
• notification-action をサポート。
• clipboard-get、clipboard-set、clipboard-clear をサポート。
• wait をサポート。
• session、trace、cursor-overlay をサポート。
• status、permissions、version、batch、skills をサポート。
• list-surfaces をサポート。
• さまざまなフラグ付きの snapshot をサポート。
• find、get、is をサポート。
• scroll、scroll-to をサポート。
• expand、collapse をサポート。
• select、toggle、check、uncheck をサポート。
• clear、focus をサポート。
• type、set-value をサポート。
• click、double-click、triple-click、right-click をサポート。
• press、hover、drag、mouse-move、mouse-click、mouse-wheel をサポート。
• key-down、key-up、mouse-down、mouse-up をサポート。
• launch、close-app をサポート。
• list-apps、... をサポート。
• 現在はmacOSとWindowsのみ。Linuxは計画中。
• OSレベルのアクセシビリティ権限が必要。非技術者には設定が面倒な場合がある。
• Windowsではバイナリが署名されていないため、SmartScreen/AVがブロックする可能性がある。
• 一部のコマンド（key-down、mouse-down など）はデーモンが追加されるまでプレースホルダーです。
• JSON出力は冗長になる可能性があり、大規模なアプリでは巨大なスナップショット（数万トークン）が生成される場合があります。
• 組み込みのLLM統合はありません – JSONを独自のモデルプロンプトに配線する必要があります。
• ソースからビルドするにはRustツールチェーンが必要。純粋なJSパッケージではありません。
• スナップショットの精度はOSのアクセシビリティ実装に依存し、アプリによって異なる場合があります。

---

この概要はプロジェクトのREADMEのみに基づいています。