agent-desktop：讓 AI agent 用無障礙樹操作桌面程式，不用靠截圖猜按鈕

AI agent 要「用電腦」，常見做法是截圖，再請模型從圖上猜按鈕在哪。Vercel Labs 開源的 agent-desktop 走另一條路：直接讀作業系統提供的無障礙樹（accessibility tree），讓 agent 用結構化的資料看畫面、再下指令操作。

本文依據該專案 README 整理，我們沒有在自己的環境完整實測，安裝與權限細節請以官方說明為準。

它怎麼運作

專案的一句話介紹是：讓 AI agent 透過作業系統的無障礙樹，讀取並操作桌面應用程式。流程大致是：

1. snapshot：取得目前應用程式的 UI 結構，輸出成 JSON，每個可以操作的元素都有一個 ref。
2. 操作：agent 用 ref 執行點擊、輸入等動作。
3. 再 snapshot 驗證：重新讀一次畫面，確認動作的結果。

整個過程不做像素比對，所以不太受解析度、主題色或縮放影響。

主要特色

• 約 56 個指令，涵蓋觀察、點擊與輸入、鍵盤滑鼠、應用程式與視窗管理、通知、剪貼簿、截圖等。
• 支援 macOS、Windows、Linux（Linux 使用 AT-SPI）。
• 預設 headless，不會移動游標或搶走焦點；需要時可加 --headed。
• 提供 C 函式庫（FFI），可以在程式裡直接呼叫，專案頁面有 Python ctypes 範例。
• 內建給 AI agent 閱讀的說明文件。
• 授權 Apache-2.0。

安裝與權限

npm install -g agent-desktop
agent-desktop version

各平台的權限需求不同：macOS 需要在系統設定裡給「輔助使用」權限；Windows 對與終端機同一完整性等級的應用程式不需額外授權；Linux 需要圖形化工作階段與 at-spi2-core。

快速範例是先對某個應用程式做 snapshot 取得 ref，點擊後再 snapshot 確認結果。

為什麼值得 agent 開發者注意

• 結構化資料比截圖便宜也更穩：JSON 的 UI 結構通常比整張圖更短，也不依賴模型的視覺辨識。
• 每一步都能驗證：「操作、再讀取」的循環讓 agent 能自己發現動作沒生效。
• 跨平台：同一套指令可以跑在三大桌面系統。

它也有限制：只能操作有正確提供無障礙資訊的應用程式，畫面上完全自繪、沒有無障礙節點的內容，就需要搭配截圖等其他方式。

呼叫模型的部分：接 BazaarLink

agent-desktop 負責「看與做」，推理由你的 agent 背後的模型負責。README 並沒有說明核心 CLI 會呼叫哪些模型 API，所以模型怎麼選，取決於你用的 agent 或框架。

這類 agent 常常是一個迴圈：讀畫面、請模型決定下一步、操作、再讀畫面。一個任務會呼叫模型很多次，成本與延遲都會累積，因此能自由換模型、集中用一組金鑰和一張帳單很實用。

如果你的 agent 或程式支援 OpenAI 相容介面，只要換三個設定就能改走 BazaarLink：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_BAZAARLINK_MODEL_PAGE",
    messages=[{"role": "user", "content": "請根據這份 UI 結構，說明下一步該點哪個 ref。"}],
)
print(resp.choices[0].message.content)

• base_url 換成 https://api.bazaarlink.ai/v1（https://bazaarlink.ai/api/v1 也可以用）。
• api_key 換成你在 BazaarLink 建立的金鑰。
• model 填 模型頁 上的模型 ID。

要注意：agent 通常會用到工具呼叫與長對話，換模型前請先用你自己的 agent 流程實際跑過，確認它支援你需要的功能。

小結

agent-desktop 把桌面操作變成「讀結構、下指令、再驗證」的流程，適合想讓 agent 操作原生應用程式的開發者。模型那一端，只要你的 agent 支援 OpenAI 相容介面，就能用 BazaarLink 的一組金鑰與單一帳單去呼叫不同模型。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API