Vercel відкрила agent-desktop: агент керує десктопом без скриншотів
Vercel Labs виклала під Apache-2.0 agent-desktop: це CLI і C-бібліотека для macOS, Windows і Linux. `snapshot` віддає JSON із дерева accessibility ОС, і кожен елемент у ньому має ref. Агент робить `click` по ref і знімає снепшот знову, пікселі не розпізнаються. За замовчуванням працює headless: курсор і фокус не чіпає, фізичний ввід вмикається лише з `--headed`.
Агент отримує структуру інтерфейсу замість картинки. Ціна цього: після зміни UI старі ref повертають `STALE_REF`, і потрібен новий снепшот.
Встановлення і підключення до агента
Пакет ставиться через npm: npm install -g agent-desktop, перевірка — agent-desktop version. Bun, Yarn і pnpm ставлять той самий пакет із нативними бінарниками для x64 і ARM64. Якщо JS-лаунчер не потрібен, візьміть нативний архів із GitHub Releases і тримайте helper поруч із виконуваним файлом. Офіційні пакети для Homebrew і Scoop ще на подачі, у стандартних каталогах їх поки немає.
- macOS: потрібен дозвіл Accessibility, підказку дає
agent-desktop permissions --guide. - Windows: для застосунків на рівні цілісності вашого терміналу дозволи не потрібні.
- Linux: потрібна графічна сесія користувача з
at-spi2-core.
Щоб агент знав правила роботи, поставте skill: npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop. Інший варіант — додати в AGENTS.md: 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. Документація вшита в бінарник і відповідає його версії.
Цикл і помилки, на які агент натрапить першими
Схема така: снепшот, дія по ref, повторний снепшот для перевірки. Назву застосунку беріть із agent-desktop list-apps. Прапорець -i лишає в снепшоті тільки інтерактивні елементи. Кожна команда друкує один JSON-конверт з ok і полем data або error. Помилка містить код, disposition і зазвичай підказку. Повторювати команду варто лише тоді, коли error.disposition.retry дозволяє це як безпечне.
- Ref прив'язаний до свого снепшоту. Голий
@e8даєINVALID_ARGS, потрібна повна форма@s8f3k2p9:e8. - Після зміни UI дія повертає
STALE_REFабоAMBIGUOUS_TARGET. Робіть новий снепшот і беріть ref із нього. - Якщо відкрито кілька вікон, буде
AMBIGUOUS_TARGET, а id кандидатів лежать вerror.details. Передайте потрібне через--window-id. - У PowerShell беріть кожен ref у лапки (
'@s8f3k2p9:e8'), бо голий@там означає оператор splatting.
Важкі інтерфейси і виклик із власного коду
Для застосунків із великим деревом спершу зніміть карту snapshot --skeleton --app Slack -i --compact, потім заходьте в один регіон через snapshot --root @s8f3k2p9:e3 -i --compact. Так агент не тягне в контекст усе дерево.
Кожен виклик CLI запускає окремий процес. Якщо це гальмує, у кожному релізі є libagent_desktop_ffi для всіх трьох ОС, тож бібліотеку можна викликати in-process, наприклад через ctypes. ad_init повертає OK лише тоді, коли major-версія ABI у заголовку збігається з бібліотекою. Точки входу, володіння пам'яттю і правила потоків описує agent-desktop skills get ffi.
Межі і що перевірити
- Headless — режим за замовчуванням: дії йдуть через accessibility API, курсор не рухається, фокус не перехоплюється. Фізичний ввід дозволяє лише глобальний
--headed. - Із 60 команд працюють 56.
key-down,key-up,mouse-downіmouse-upвідмовляються виконуватись, доки не з'явиться демон, який зможе відпустити затиснуту клавішу чи кнопку. - Можливості відрізняються між ОС, зокрема між X11 і Wayland на Linux. Повну таблицю для вашої системи показує
agent-desktop skills get platform. - Снепшоти, буфер обміну, скриншоти, вивід команд і debug-артефакти можуть містити приватний вміст десктопа. Не пускайте їх у публічні логи, CI-артефакти чи завантаження.
- Опційний helper JEV надсилає описи екрана налаштованому провайдеру моделі. Він окремий від нативного CLI, тому перевірте, чи ви його не ввімкнули.