agent-desktop: локальный ИИ-агент жмёт элемент по ref, а не угадывает пиксель

Скриншот рабочего стола долго казался коротким путём: локальный ИИ-агент видит то же, что человек, и нажимает кнопку. На практике картинка тяжёлая, координата плывёт из-за масштаба и сдвига окна, а в кадр попадает соседняя переписка. 3 ноября в репозиторий agent-desktop от Vercel Labs вошёл MCP, и самодельный разбор вывода командной строки перестал быть обязательным шагом. Утилита читает дерево доступности приложения на macOS, Windows и Linux и отдаёт JSON, где у элемента есть ref. Модели внутри нет: клик и ввод делает ваш агент по этой ссылке, и шаг "сначала сфотографируй весь экран" из цикла выпадает.

Что agent-desktop отдаёт вместо скриншота

Это не чат и не очередная модель. Командная утилита смотрит дерево доступности уже открытой программы и описывает кнопки, поля и пункты меню так, чтобы по ним можно было действовать. В описании 60 имён команд, рабочие из них 56. Не выполняются key-down, key-up, mouse-down и mouse-up, пока нет фонового процесса, который отпустит зажатую клавишу. Без него агент легко нажмёт модификатор и не отпустит.

По умолчанию действие не показывают на столе: курсор не едет, фокус окна не меняется. Живой ввод включается флагом --headed. Платформы из первоисточника: macOS 13 и новее, Windows 10 1809 и новее, Ubuntu 24.04 и новее, X11 или Wayland. Лицензия Apache-2.0. Вместе с MCP подготовили версию 1.1.0. Агент вызывает agent-desktop mcp и получает дерево, а не сырой текст.

Свой разбор строк мы уже ловили на других обвязках. Пока формат стабилен, парсер живёт. Стоит полю переехать на другую строку, агент теряет кнопку и начинает "чинить" промпт. Готовый MCP этот класс поломок забирает себе. Остаются поломки окна, не поломки разбора.

Как сделать ИИ-агента на ref, а не на координате

Проверка короткая. Это ещё не контур заказчика.

Ставите утилиту: npm install -g agent-desktop. Смотрите agent-desktop status. На Mac отдельно agent-desktop permissions --guide. Без разрешения системы на доступность дерево пустое, и модель это не компенсирует.

Дальше снимок одного приложения, не всего стола: agent-desktop snapshot --app Finder -i. В JSON берёте ref нужного элемента вместе с id снимка. Клик по этому ref, затем новый снимок. Голый @e8 без id снимка утилита считает ошибкой. Так и должно быть: ссылка без снимка не привязана к окну, которое агент только что видел.

В конфиг MCP кладётся команда agent-desktop и аргумент mcp. Дальше петля короткая. Модель читает JSON, выбирает один ref, инструмент делает действие, свежий снимок говорит, изменилось ли окно. Так и собирается агент: не просьба "покликай в программу", а один шаг и проверка.

Модель подставляете вы. Утилита одинаково отдаст дерево и локальной модели, и облачной. Локальный ИИ-агент здесь значит локальные руки. Где думает модель, командная строка не решает. Путать эти два слоя в работе с ИИ-агентами обычно дороже, чем спорить, как назвать связку. Для сотрудника это всё тот же ИИ-агент. AI-агентом его делает не вывеска, а инструмент на машине: видит элементы окна и трогает один из них.

Где дерево врёт и клик не доходит

Устаревший ref приходит как STALE_REF или AMBIGUOUS_TARGET. Список прокрутили, диалог закрылся, кнопка перерисовалась. Старая ссылка больше не тот элемент. Нормальный темп: снимок, одно действие, новый снимок. Серия кликов по одному JSON - это тыкать в меню, которое уже убрали.

Часть программ дерева не отдаёт. Самописное окно на голых пикселях, некоторые терминалы, старые оболочки. Агент их не видит, и подкрутка промпта не создаст ref из ничего. Скриншот выглядит запасным глазом, но это другой канал: другие права, другая утечка, другая ошибка координаты. Не "тот же режим, только с картинкой".

Снимки, буфер обмена и скриншоты могут содержать личные данные рабочего стола. JSON суше картинки, но в нём имена файлов, темы писем, цифры в полях. Если этот текст уходит в чужой контур, локальный ИИ-агент кликом ничего не прячет: наружу ушло содержимое окна.

Четыре команды удержания клавиши без фонового процесса в сценарий лучше не закладывать. Для ввода в форму зависший Shift хуже честного отказа.

Что заложить в работу с ИИ-агентами до первого боевого окна

Снимок ограничивайте одним приложением, как в примере с Finder. Весь рабочий стол для первого боевого сценария слишком широк: агент видит то, что человеку показывать не собирались.

Id снимка храните рядом с ref и считайте ссылку одноразовой. После любого действия старый набор не переиспользуйте.

Сначала право смотреть, потом право менять. Первые прогоны - только снимки и журнал: какой ref модель выбрала. Запись в форму, отправка и удаление подключайте, когда человек узнал свои кнопки в JSON и согласен, что агент попадёт именно в них.

Отдельно решите, куда уезжает дерево. Для персональных данных это раньше спора о модели. Локальная модель или российский контур уместны не потому, что утилита безопасна сама по себе, а потому что содержимое окна не должно гулять вместе с запросом. В "Интеллект Технологии" на таких задачах мы начинаем с вопроса, что инструмент видит, и только потом выбираем, кто этот JSON читает.

Флаг без показа курсора оставляйте там, где за машиной никто не сидит. --headed включайте, когда сотруднику нужно увидеть, что действие пошло в его окно, и успеть остановить процесс. Разрешения операционной системы - часть настройки. Пока их нет, фраза "агент установлен" пустая: дерева нет, клика нет.

Что из этого следует

agent-desktop не делает модель внимательнее. Он убирает гадание по пикселям там, где у программы есть дерево доступности, и оставляет короткую петлю: снимок, один ref, действие, новый снимок. Проверьте это на одном живом приложении и сразу договоритесь, куда девается JSON. Если дерева нет или в нём чужие данные, включать агента "посмотрим" дороже, чем отложить.

У окна, которое агент должен нажимать, дерево доступности вообще есть, или модель до сих пор кормят скриншотом?