agent-desktop

agent-desktop

agent-desktop は、AI エージェントが OS のアクセシビリティツリーを通じてデスクトップアプリを観察し、操作できる CLI です。エージェントではなく、ツールです。各コマンドは 1 つの JSON エンベロープ（ok、data または error）を出力します。観察、操作、検証のループは、あなた自身が実行します。

シェル構文

例では POSIX シェルを使用しています。PowerShell では、すべての ref を引用符で囲んでください（'@s8f3k2p9:e1'）。引用符のない @token はスプラッティング演算子として扱われるためです。export の代わりに $env:NAME = 'value' を、$(...) と jq の代わりに | ConvertFrom-Json を使用してください。Windows スキルには PowerShell での記述形式が載っています。

初回実行

1. agent-desktop status を実行します。プラットフォーム、権限、supported_surfaces が表示されます。
2. agent-desktop skills get platform を実行します。バイナリが実行されている OS（macOS、Windows、Linux）向けのスキルが読み込まれます。
3. フラグと構文を確認するには、agent-desktop <command> --help を実行します。このスキルではフラグの一覧を繰り返しません。

ループ

ロールまたは正確な名前が分かっている場合は find を使用します。そうでない場合は、まずアプリ全体の構造を把握してから、目的の領域を詳しく調べます。

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # shallow map, children_count on cut branches
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verify: re-read the same region

• 小さなアプリでは、骨組みを作る必要はありません。snapshot -i で全体をスナップショットします。
• サーフェス（--surface menu、sheet、alert）の骨組みは作成しないでください。サーフェスにはすでにフォーカスがあります。
• メニュー、シート、アラートを開くアクションでは、data.surfaces にその内容が表示されます。次に、そのオーバーレイを対象にします。
• 非同期処理の後は、wait を使用します（commands-system.md を参照）。固定時間のスリープでは競合状態が発生します。

Refs

• 出力される ref は修飾されています。形式は @<snapshot_id>:e<N> です。例：@s8f3k2p9:e1。後続のコマンドには、そのまま渡します。
• ref は 1 つのスナップショットに対して有効です。UI に変更があった場合は、影響を受ける領域を再度詳しく調べるか、新しいスナップショットを取得してください。
• ref が割り当てられるのは、操作対象にできる要素だけです。静的テキストと操作できないコンテナーには割り当てられません。
• STALE_REF：ref が現在の UI と一致しなくなっています。新しいスナップショットを取得し、新しい ref を使用してください。
• AMBIGUOUS_TARGET：一致する要素が複数あります。find --role --name --exact または --root を使って対象を絞り込み、新しい ref を使用してください。
• SNAPSHOT_NOT_FOUND：スナップショット ID の有効期限が切れています。再度スナップショットを取得してください。

配信と再試行

アクションの結果には data.disposition が、エラーには error.disposition が含まれ、それぞれに delivery と retry があります。snapshot などの観察コマンドは、成功時にはこれらを持ちません。観察コマンドのエラーとすべての INVALID_ARGS 拒否には、not_delivered と retry: safe が含まれます。

• アクションの再試行や置き換えは、disposition.retry が safe の場合に限ります。安全なのは not_delivered の場合だけです。
• それ以外の delivery 値では、アクションがすでに反映されている可能性があります。再実行すると、クリック、入力、送信が二重に行われたり、toggle が元に戻ったりすることがあります。
• 安全でない結果が返された場合は、現在の状態（get、is、または新しいスナップショット）を読み取り、それに基づいて判断してください。存在する場合、details.post_state が参考になります。
• error.code と error.disposition に基づいて分岐してください。メッセージと提案のテキストは変更されることがあります。
• details.retryable: false は、待機しても結果が変わらないことを意味します。別の方法を試してください。

ヘッドレスとヘッデッド

ref アクションは、デフォルトではヘッドレスで実行されます。セマンティックなアクセシビリティ呼び出しを使用し、フォーカスの取得、カーソルの移動、キー入力の合成、クリップボードの使用は行いません。セマンティックな経路がない場合、アクションは安全側に倒して失敗します。ダブルクリック、ホバー、ドラッグ、フォーカスなど、ユーザーが物理入力を明示的に許可した場合に限り、グローバルな --headed フラグを使用してください。ヘッドレスでの失敗から復旧するために、ヘッデッドモードに切り替えてはいけません。生の座標（--xy）を指定しても、フォーカスが取得されることはありません。--headed が必要なアクションは OS によって異なります。プラットフォームのスキルを確認してください。

リファレンス

必要な場合にのみ、次のコマンドで1つ読み込みます：agent-desktop skills get desktop <reference>。

リファレンス	開くタイミング
commands-observation	snapshot、find、get、is、screenshot、list-surfaces のセマンティクス、部分ツリー、または --root のルールが必要な場合
commands-interaction	click、type、set-value、select、toggle、scroll、press、mouse の各コマンドから選ぶ場合、またはアクションエラーをデバッグする場合
commands-system	アプリを起動または終了する場合、ウィンドウを管理する場合、クリップボードを使用する場合、wait、batch、セッション、マルチエージェントカーソル、トレースを使用する場合、またはスキルを読み込む場合
workflows	実践的なパターン（フォーム、メニュー、ダイアログ、新しいウィンドウの待機、スクロールと検索、ドラッグ）と、アンチパターンの一覧を確認する場合