agent-desktop: điều khiển desktop bằng accessibility tree

Bạn muốn nhờ AI agent bấm giúp một nút trong ứng dụng desktop, nhưng agent chỉ “nhìn” được màn hình qua ảnh chụp rồi đoán tọa độ. Cách đó chạy được với giao diện đơn giản, nhưng rất mong manh: cửa sổ đổi kích thước, một popup xuất hiện, một danh sách cuộn thêm vài dòng là tọa độ cũ không còn đúng nữa.

agent-desktop đi theo hướng khác. Thay vì đoán pixel, nó đọc cây accessibility mà hệ điều hành đã cung cấp sẵn cho các công cụ hỗ trợ tiếp cận, rồi thao tác trực tiếp lên các phần tử trong cây đó. Mỗi phần tử có một ref gắn với một snapshot cụ thể. Agent quan sát, hành động, rồi quan sát lại để xác minh. Nếu giao diện đã đổi, hệ thống báo lỗi thay vì đoán tiếp.

Vì sao agent vẫn “mù” trước ứng dụng desktop?

Computer use là bài toán cho AI agent sử dụng máy tính như người dùng: mở ứng dụng, đọc nội dung, bấm nút, gõ văn bản, kiểm tra kết quả. Cách phổ biến nhất là chụp màn hình, đưa ảnh cho model, model ước lượng tọa độ rồi bấm. Ưu điểm là nó làm việc với bất kỳ thứ gì hiển thị được. Nhược điểm là tọa độ chỉ là suy đoán: ảnh chụp có độ phân giải hữu hạn, giao diện thay đổi theo trạng thái, và model không có cách chắc chắn rằng điểm nó bấm chính là nút nó định bấm.

Screenshot càng yếu trong ba trường hợp: ứng dụng dày đặc với hàng trăm phần tử; cửa sổ nền, trong khi screenshot chỉ thấy lớp trên cùng; và thao tác cần xác minh, như sau khi bấm “Lưu”, agent cần biết chắc hành động đã có hiệu lực.

agent-desktop giải quyết đúng ba điểm trên, trong phạm vi ứng dụng có cây accessibility tốt: nó đọc cấu trúc có tên, vai trò và trạng thái thay vì đọc pixel; nó thao tác qua API hệ điều hành nên không cần đưa cửa sổ lên trước; và nó bắt agent xác minh bằng snapshot mới sau mỗi thao tác. Nó không giải quyết được ứng dụng không expose cây accessibility — ví dụ giao diện vẽ hoàn toàn bằng canvas.

agent-desktop là gì? Công cụ, không phải agent

agent-desktop là một CLI và thư viện C của Vercel Labs, mô tả ngắn gọn là “Computer use CLI for AI agents”. Dự án viết bằng Rust, phát hành dưới giấy phép Apache-2.0. Tại thời điểm kiểm tra ngày 3/11/2026, kho vercel-labs/agent-desktop có 10.852 star và 726 fork, bản phát hành mới nhất là v1.1.0 ra ngày 3/11/2026, sau v1.0.2 ngày 30/10/2026.

Cần nói rõ ngay: agent-desktop không phải là agent. Nó không chứa model ngôn ngữ, không có giao diện đồ họa, không tự quyết định làm gì. Nó là công cụ mà một agent gọi tới, giống như cách coding agent gọi tới terminal hay trình duyệt. LLM và harness của bạn là bộ não; agent-desktop chỉ là bàn tay.

Theo mình, nhóm hưởng lợi rõ nhất là sysadmin, DevOps/SRE, developer, người chơi homelab self-host, và người đã có sẵn một AI coding agent muốn mở rộng khả năng sang ứng dụng desktop. Ngược lại, bạn chưa nên dùng nếu đang tìm một agent hoàn chỉnh tự làm hết, nếu môi trường cấm cấp quyền accessibility, hoặc nếu ứng dụng cần điều khiển là canvas-only.

Kiến trúc và cơ chế hoạt động

Vòng lặp snapshot → act on ref → snapshot lại

Mọi thao tác xoay quanh ba bước: lấy snapshot — bản mô tả cấu trúc giao diện dưới dạng JSON, trong đó mỗi phần tử có thể thao tác được gán một ref; hành động trên ref đó, ví dụ bấm, gõ, chọn, cuộn; rồi lấy snapshot mới để xác minh. Không xác minh thì chưa coi là xong, đặc biệt sau những thao tác có tác dụng phụ như lưu, gửi, xóa hay xác nhận.

Bên dưới CLI là ba API accessibility của hệ điều hành: AX API trên macOS, UI Automation trên Windows, AT-SPI trên Linux.

Ref gắn với snapshot: thất bại an toàn thay vì thao tác sai

Ref chỉ có nghĩa trong đúng snapshot đã sinh ra nó. Một ref trần như @e8 sẽ bị từ chối với lỗi INVALID_ARGS. Nếu giao diện thay đổi sau khi snapshot được lấy, ref cũ có thể trả về STALE_REF hoặc AMBIGUOUS_TARGET.

Theo mình, đây là điểm sâu nhất của thiết kế này. Ref hoạt động giống như một capability token có thời hạn gắn với trạng thái đã quan sát: mỗi hành động chỉ hợp lệ trong đúng trạng thái đó. Khi trạng thái đổi, hệ thống không đoán lại mà báo lỗi và bắt agent lấy trạng thái mới — thất bại an toàn thay vì thao tác sai. Quy tắc xử lý vì thế rất đơn giản: gặp STALE_REF hay AMBIGUOUS_TARGET thì snapshot lại rồi mới act, không retry mù.

Lệnh, skeleton, headless và JSON envelope

agent-desktop có 60 tên lệnh, trong đó 56 lệnh vận hành được, còn 4 lệnh giữ phím/chuột sẽ từ chối chạy cho tới khi có daemon xử lý việc nhả phím/chuột bị giữ. Các nhóm chính gồm: observe (snapshot, find, screenshot); act trên ref (click, type, set-value, focus, select, scroll); apps/windows; clipboard; sessions; và system (status, permissions, version, skills).

Với ứng dụng dày đặc, đừng lấy toàn bộ cây một lúc: lấy skeleton trước bằng snapshot --skeleton, rồi drill-in bằng snapshot --root @<ref> -i --compact.

Mặc định, agent-desktop chạy headless: thao tác trên ref đi qua accessibility API mà không di chuyển con trỏ thật, không cướp focus. Cờ --headed cho phép input vật lý khi thực sự cần, nhưng mở lại đúng rủi ro mà headless đã loại bỏ. Theo mình, chỉ dùng nó khi thao tác đó không tồn tại ở tầng API, và luôn chạy trong phiên có giám sát.

Mỗi lệnh in ra một JSON envelope duy nhất với trường ok và hoặc data hoặc error, kèm code, disposition và suggestion khi lỗi. Skill docs khớp phiên bản lấy bằng agent-desktop skills get desktop và agent-desktop skills get platform. Giới hạn cần nhớ: agent-desktop chỉ thấy những gì accessibility tree cho thấy.

Hướng dẫn triển khai: cài đặt và kiểm chứng

Các lệnh dưới đây đối chiếu tài liệu cài đặt chính thức; phần này mình chưa chạy thử trong môi trường hiện tại.

Trên macOS, agent-desktop cần quyền Accessibility; chụp màn hình cần thêm Screen Recording, còn mở Notification Center cần quyền Automation cho System Events. Trên Windows, ứng dụng chạy as administrator chỉ nhận input từ agent đã elevated. Trên Linux, mục tiêu chính là Ubuntu 24.04 trở lên với GNOME 46, cần chạy trong graphical session của chính người dùng và cài at-spi2-core; một shell TTY hay SSH không gắn với session đó sẽ không thấy ứng dụng của bạn.

npm install -g agent-desktop
agent-desktop version

Bun, Yarn và pnpm cũng cài được cùng package npm này.

Hai nhầm lẫn cần tránh. Thứ nhất, gói Homebrew và Scoop chính thức vẫn đang được gửi lên, chưa có trong catalog mặc định — đừng dùng brew install agent-desktop với kỳ vọng nó sẽ chạy. Thứ hai, ví dụ JSON trong tài liệu hiển thị "version": "2.6" — đó là phiên bản của JSON envelope, không phải phiên bản package; bản phát hành mới nhất đã kiểm chứng là v1.1.0, chưa có bản 2.0.0..

Trên macOS, chạy agent-desktop permissions --guide để mở System Settings đúng tại quyền còn thiếu, và cấp tối thiểu theo nhu cầu thật. Trên Windows, binary chưa được ký, nên tải qua trình duyệt có thể bị SmartScreen cảnh báo, antivirus cách ly, hoặc Smart App Control chặn; cài qua npm không kích hoạt SmartScreen. Bẫy lớn hơn là mức integrity: đừng elevated toàn bộ harness chỉ vì một ứng dụng, vì agent elevated bị prompt injection hay thao tác sai sẽ có quyền administrator.

Trên Linux, kiểm tra ba thứ trước khi kết luận công cụ hỏng: bạn có đang ở trong graphical session của chính user đó không, at-spi2-core đã cài chưa, và bus/display/runtime có trỏ đúng session đó không.

agent-desktop permissions --guide
agent-desktop list-apps
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

list-apps cho danh sách ứng dụng mà agent-desktop thấy được — nếu ứng dụng cần thao tác không có trong danh sách, đừng cố bấm, hãy quay lại phần quyền và session. snapshot --app Finder -i trả về cây giao diện của Finder, trong đó mỗi phần tử có ref dạng gắn snapshot như @s8f3k2p9:e8. Lệnh click trả về envelope báo thành công hay lỗi, và snapshot thứ hai sau đó là bước xác minh.

agent-desktop không sở hữu dữ liệu của ứng dụng đích, nên rollback chủ yếu là thu dọn: gỡ package bằng npm uninstall -g agent-desktop, thu hồi quyền đã cấp, xóa session trace và debug artifact, ngắt harness khỏi CLI, và kiểm tra không còn daemon nào giữ phím hay chuột.

Đánh giá kỹ thuật

Ưu điểm lớn nhất là tính xác định: thao tác theo ref thay vì tọa độ, và mỗi thao tác đều có bước xác minh bằng snapshot sau đó. Tiếp theo là chế độ headless mặc định, không cướp focus, không di chuyển chuột thật. Thứ ba là đa nền tảng với cùng một envelope JSON, giúp harness viết một lần và dùng trên cả ba hệ điều hành.

Nhược điểm lớn nhất là phụ thuộc vào cây accessibility: ứng dụng không expose cây thì công cụ không làm được gì. Tiếp theo là quyền nhạy cảm: Accessibility, Screen Recording, UI Automation và AT-SPI đều là quyền mạnh, cấp sai phạm vi là mở rộng bề mặt tấn công. Hệ sinh thái còn mới — v1.1.0 ra ngày 3/11/2026 — nên API và skill docs có thể còn thay đổi theo release.

Về bảo mật và riêng tư, snapshot, clipboard, screenshot và session trace đều có thể chứa dữ liệu desktop nhạy cảm. Đừng đưa chúng vào log công khai hay artifact debug tải lên nơi khác, và hãy coi trace là dữ liệu nhạy cảm, xóa khi không còn cần. JEV là helper tùy chọn gửi mô tả màn hình tới model provider, tách khỏi CLI gốc và không bật mặc định; trong môi trường chứa dữ liệu nhạy cảm, đừng bật nó trước khi đánh giá đường đi dữ liệu tới provider đó.

Mình chưa đo hiệu năng công cụ này nên không công bố benchmark.

So sánh với các lựa chọn cùng phạm vi

Tiêu chí so sánh là độ tin cậy, chi phí token, khả năng headless, đa nền tảng, khả năng xác minh sau thao tác, an toàn và khả năng kiểm toán. Computer use bằng screenshot và pixel làm việc với mọi thứ hiển thị được, nhưng mong manh trước thay đổi giao diện, tốn token vì phải gửi ảnh, và khó xác minh chắc chắn. Script tọa độ — PyAutoGUI, SikuliX, AppleScript, xdotool — linh hoạt và không cần agent, nhưng bạn phải tự duy trì mọi logic chờ đợi, thử lại và xác minh; tọa độ cứng sẽ gãy khi giao diện đổi.

Tự động hóa trình duyệt là hướng bổ sung, không thay thế. Lightpanda là trình duyệt headless cho AI agent, rất hợp với tác vụ web, nhưng nó không chạm được tới ứng dụng desktop native. RPA và agent hoàn chỉnh là lựa chọn khi bạn cần giải pháp đóng gói, có phê duyệt và giám sát tích hợp.

Trường hợp sử dụng thực tế

Với IT admin và sysadmin, trường hợp rõ nhất là thao tác ứng dụng desktop nội bộ không có API: mở công cụ quản trị, kiểm tra một cấu hình, xuất một báo cáo, trong một phiên có giám sát và có log JSON để đối chiếu. Với DevOps/SRE, agent-desktop hợp với kiểm thử và vận hành công cụ desktop trong quy trình có giám sát, nơi mỗi bước đều được snapshot xác minh trước khi đi tiếp. Với homelab, agent hỗ trợ cấu hình ứng dụng desktop trên máy lab.

Với AI workflow, coding agent gọi agent-desktop như một tool, kèm vòng lặp snapshot-act-verify, thay vì tự đoán tọa độ qua screenshot. Trong doanh nghiệp, nguyên tắc là giới hạn phạm vi: chỉ cấp quyền trên máy đã kiểm soát, phê duyệt thao tác nhạy cảm trước khi chạy, và không chạy tự động không giám sát trên máy chứa dữ liệu nhạy cảm.

Kết luận

agent-desktop phù hợp nếu bạn cần điều khiển desktop bằng AI agent một cách xác định và kiểm chứng được: bạn đã có model và harness, bạn làm việc với ứng dụng có cây accessibility tốt, và bạn chấp nhận cấp quyền hệ thống trong một phạm vi đã kiểm soát. Nó không phù hợp nếu bạn tìm một agent hoàn chỉnh tự làm mọi thứ, nếu ứng dụng của bạn là canvas-only, hoặc nếu môi trường của bạn cấm cấp quyền accessibility.

Bước tiếp theo, theo mình, nên rất nhỏ: cài trên một máy thử, cấp quyền tối thiểu, chạy thử vòng snapshot-click-verify với một ứng dụng quen thuộc như Finder, rồi mới gắn vào harness thật. Đừng bắt đầu bằng ứng dụng chứa dữ liệu nhạy cảm, và đừng bỏ qua bước snapshot thứ hai sau mỗi thao tác quan trọng.

Tài liệu tham khảo

• Kho chính thức: https://github.com/vercel-labs/agent-desktop
• Hướng dẫn cài đặt: https://github.com/vercel-labs/agent-desktop/blob/main/docs/install.md
• Câu hỏi thường gặp: https://github.com/vercel-labs/agent-desktop/blob/main/docs/faq.md
• Các bản phát hành: https://github.com/vercel-labs/agent-desktop/releases
• Trang giới thiệu: https://agent-browser.dev/desktop