Agent Desktop: thao tác desktop qua accessibility tree và ref theo snapshot

Agent Desktop là CLI và thư viện C cho agent đọc, thao tác ứng dụng desktop qua accessibility tree trên macOS, Windows và Linux. Mỗi ref gắn với một snapshot, giúp agent quan sát, hành động rồi xác minh lại bằng JSON.

Hãy hình dung một agent cần bấm vào mục “Documents” trong Finder. Nếu nó dựa vào ảnh màn hình, việc đổi kích thước cửa sổ, thay theme hoặc dịch chuyển danh sách có thể làm thao tác theo tọa độ trở nên mong manh.

vercel-labs/agent-desktop đi theo hướng khác: agent đọc accessibility tree — cây cấu trúc UI do hệ điều hành cung cấp — lấy ref của phần tử, thao tác qua ref, rồi chụp snapshot mới để kiểm tra kết quả.

Với developer xây agent local, agent QA hoặc harness nội bộ, đây là một contract đáng chú ý: dữ liệu vào/ra là JSON, ref gắn với snapshot và lỗi có thông tin để quyết định có nên retry hay không.

Agent Desktop là gì?

Agent Desktop là CLI và thư viện C cho macOS, Windows và Linux. Công cụ đọc và vận hành ứng dụng desktop thông qua accessibility tree của hệ điều hành.

Vòng lặp cốt lõi là:

Gọi snapshot để nhận cây UI và ref của các phần tử có thể thao tác. Gọi hành động như click, type hoặc select bằng ref đó. Chụp snapshot mới để xác minh trạng thái UI.

Ví dụ trong README cho thấy một phần tử treeitem tên Documents có ref @s8f3k2p9:e8. Ref này không phải selector theo tên đơn thuần: nó gắn với snapshot s8f3k2p9.

Trên macOS, CLI dùng command host riêng theo từng snapshot namespace và binary build, đồng thời giữ native accessibility object. Theo README, cơ chế này nhằm tránh việc một hàng đã bị xóa lại âm thầm được ánh xạ sang hàng khác còn tồn tại nhưng có cùng identifier.

Cài đặt và kiểm tra môi trường

Cài package bằng npm trên macOS, Windows hoặc Linux:

bash npm install -g agent-desktop agent-desktop version

Package gồm native binary và platform helper cho x64 lẫn ARM64. Bun, Yarn và pnpm cũng có thể cài cùng package.

Nếu không muốn chạy qua JavaScript launcher, bạn có thể tải native archive phù hợp từ GitHub Releases và giữ helper cạnh file thực thi.

Các yêu cầu theo nền tảng:

macOS: cần cấp quyền Accessibility.

bash agent-desktop permissions --guide

Windows: không cần cấp quyền cho ứng dụng chạy ở cùng integrity level với terminal. Linux: cần graphical session của người dùng và at-spi2-core.

README cũng lưu ý các package Homebrew và Scoop chính thức đang được gửi lên catalog, nhưng chưa có trong catalog mặc định. Repository không còn duy trì Homebrew tap hoặc Scoop bucket riêng.

Vòng lặp: quan sát, hành động, xác minh

Ví dụ với Finder trên macOS, trước hết lấy snapshot của các phần tử tương tác:

bash agent-desktop snapshot --app Finder -i

Mỗi lệnh in một JSON envelope. Phản hồi mẫu có dạng:

json { "version": "2.5", "ok": true, "command": "snapshot", "data": { "app": "Finder", "window": { "id": "w-204749", "title": "Downloads" }, "snapshotid": "s8f3k2p9", "refcount": 59, "complete": true } }

Trong cây UI đi kèm, Documents có ref @s8f3k2p9:e8. Có thể thao tác bằng ref đó:

bash agent-desktop click @s8f3k2p9:e8

Sau đó, chụp snapshot mới:

bash agent-desktop snapshot --app Finder -i

Agent hoặc harness của bạn vẫn phải tự định nghĩa điều kiện thành công từ snapshot mới: chẳng hạn vùng chọn, cửa sổ hoặc cấu trúc cây UI đã phản ánh trạng thái mong muốn.

Ba quy tắc nên đưa vào agent harness

1. Không dùng bare ref

@e8 sẽ bị từ chối với INVALIDARGS. Ref phải chứa cả snapshot ID, ví dụ:

text @s8f3k2p9:e8

2. Ref cũ không được dùng khi UI đã thay đổi

Khi UI đổi trạng thái, thao tác có thể trả về STALEREF hoặc AMBIGUOUSTARGET. Lúc đó, hãy lấy snapshot mới và dùng ref từ snapshot mới.

3. Chỉ retry khi lỗi cho phép

Mỗi lỗi có code, disposition và thường có suggestion. README nêu rõ chỉ nên retry khi error.disposition.retry là safe.

Dự án cũng cung cấp tài liệu theo đúng phiên bản binary đang chạy:

bash agent-desktop skills get desktop agent-desktop skills get platform agent-desktop <command> --help

Nếu dùng agent harness hỗ trợ skills, có thể cài skill bằng:

bash npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

Hoặc thêm hướng dẫn sau vào AGENTS.md:

markdown Use agent-desktop to see and operate desktop apps. Before the first use, run agent-desktop skills get desktop and agent-desktop skills get platform, and follow them.

Làm việc với UI dày đặc và nhiều cửa sổ

Với ứng dụng có nhiều phần tử như Slack, README gợi ý chụp skeleton trước, rồi đi sâu vào một vùng bằng ref:

bash agent-desktop snapshot --skeleton --app Slack -i --compact agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact

Cách làm này giúp agent không phải luôn xử lý toàn bộ cây UI trong một lần.

Nếu có nhiều cửa sổ, tool có thể trả AMBIGUOUSTARGET và liệt kê các window ID ứng viên trong error.details. Khi đó, truyền window ID cụ thể bằng --window-id.

Trên PowerShell, cần quote ref vì @token là cú pháp splatting:

bash agent-desktop click '@s8f3k2p9:e8'

Headless mặc định, nhưng vẫn cần kiểm soát quyền và dữ liệu

Theo README, các hành động qua ref mặc định đi qua accessibility API, không di chuyển con trỏ và không lấy focus. Cờ toàn cục --headed cho phép physical input khi cần.

Tool có các nhóm lệnh để quan sát UI, thao tác trên ref, dùng bàn phím/chuột, quản lý ứng dụng và cửa sổ, làm việc với clipboard, notification, session và trace.

Tuy nhiên, README cảnh báo rằng snapshot, clipboard reads, screenshots, command output và debug artifacts có thể chứa nội dung desktop riêng tư. JEV helper tùy chọn có thể gửi mô tả màn hình tới model provider đã cấu hình; helper này tách biệt với native CLI.

Vì vậy, khi triển khai trong môi trường công việc:

Không đưa snapshot, screenshot hoặc trace vào log công khai. Xem kỹ dữ liệu clipboard trước khi đưa vào context của model. Phân tách quyền quan sát và quyền thực hiện thao tác có hậu quả. Sau một thay đổi UI quan trọng, lấy snapshot mới thay vì lặp lại mù quáng lệnh cũ.

Khi nào nên thử?

Agent Desktop phù hợp khi agent cần làm việc với ứng dụng desktop có accessibility tree tốt, chẳng hạn kiểm tra luồng UI nội bộ, hỗ trợ thao tác lặp trong công cụ desktop hoặc xây agent local cần giao tiếp bằng JSON có cấu trúc.

Dự án phát hành dưới giấy phép Apache-2.0. Mỗi bản phát hành cũng có libagentdesktopffi cho macOS, Linux và Windows, dành cho trường hợp chương trình cần gọi tool in-process thay vì khởi chạy CLI cho từng lệnh.

Với phần lớn agent harness, điểm khởi đầu hợp lý là CLI: buộc agent tuân thủ vòng lặp snapshot → action → verify, dùng ref đúng snapshot và chỉ retry khi phản hồi JSON đánh dấu an toàn.