Настольное приложение тоже может управлять Agent: подключение модели к agent-desktop за 5 шагов

ОтShark 2026年 11月 14日

Примечание автора: в этой статье — установка agent-desktop, выдача разрешений, минимальный цикл snapshot/click и подключение через MCP, а также о том, как настроить модель и Base URL для «мозга» в этом цикле.

Заставить программирующего Agent или самодельного Agent кликать в Finder, заполнять системные настройки и работать с нативным клиентом раньше можно было в основном через скриншоты, визуальные модели и пиксельные координаты: цепочка длинная, да и промахнуться легко. Открытый проект agent-desktop от Vercel Labs пошёл другим путём: он читает дерево доступности ОС (Accessibility Tree) и превращает интерфейс рабочего стола в JSON с ref, а Agent выполняет клики и ввод по ref. Это и есть его «computer use без скриншотов».

Это не ещё один настольный робот со встроенным ИИ. Перед началом проясним три вещи:

В agent-desktop нет модели: в бинарник не встроена LLM, нет GUI и интерактивных подсказок. Каждая команда печатает JSON-envelope и завершается.
Цикл живёт у вызывающей стороны: за цикл observe-act-verify (наблюдение — действие — проверка) отвечает Agent, который вызывает инструмент, например Claude Code, OpenCode или ваш собственный скрипт.
Не для веба: автоматизацию веба передайте родственному проекту agent-browser, agent-desktop занимается только нативными десктопными приложениями.

Раз в самом инструменте нет модели, «мозг» должен предоставить вызывающий Agent — для этого нужны API-ключ и токен. Можно направить Base URL вызывающего Agent на APIYI apiyi.com и одним ключом вызывать модели claude-opus-5-5, claude-sonnet-5-5 и другие.

Что в итоге: после этой статьи вы сможете установить agent-desktop, выдать разрешения, пройти минимальный цикл snapshot → click → snapshot, подключить инструмент к своему Agent через MCP и настроить Base URL и указать модель на стороне LLM.

Table of Contents

Ключевые моменты agent-desktop

Сначала — таблица, которая показывает, как позиционируется agent-desktop. Данные ниже взяты из официального README, FAQ и сайта документации; дата наблюдения — 2026-11-13.

Пункт	Описание	Ценность для разработчика
Источник данных	Читает дерево доступности ОС: в macOS используется AX API, в Windows — UI Automation, в Linux — AT-SPI	Не зависит от скриншотов и попиксельного сопоставления, высокая структурированность
Формат вывода	Каждая команда выводит JSON envelope и завершает работу; у элементов есть ref	Удобно для разбора LLM и для проверок в скриптах
Режим по умолчанию	headless, работает через API доступности, не двигает указатель и не перехватывает фокус	Можно работать в фоне, не прерывая пользователя
Есть ли модель	Нет, цикл отвечает вызывающая сторона	Модель выбираете сами, затраты и результат контролирует вызывающая сторона
Способы подключения	CLI, MCP (stdio), skills, FFI к C-библиотеке	Можно подключить к Claude Code, OpenCode, собственному агенту

По состоянию на 2026-11-13 в GitHub-репозитории vercel-labs/agent-desktop около 22 900 звёзд, лицензия Apache-2.0, имя npm-пакета — agent-desktop; в тот день там всё ещё появлялись новые коммиты. Всего около 61 названия команд, 57 из них исполняемые; они делятся на группы Observe, Act on ref, Keyboard mouse, Apps windows, Notifications, Clipboard, Wait, Sessions, Sandboxes, System.

Как работает agent-desktop: дерево доступности и ref

Ключевые понятия agent-desktop — это snapshot и ref. Когда выполняется snapshot, инструмент обходит дерево доступности целевого приложения и выдаёт кнопки, текстовые поля, пункты меню и прочие элементы в виде JSON, причём каждому элементу присваивается ref. Полный ref выглядит примерно так: @s8f3k2p9:e8 — первая часть это идентификатор текущего snapshot, вторая — номер элемента.

ref принадлежит только тому snapshot, который его создал. Если передать голый @e8, получите INVALID_ARGS. После изменения интерфейса старый ref может устареть — вернётся STALE_REF или AMBIGUOUS_TARGET, и тогда нужен новый snapshot. Такая схема заставляет вызывающую сторону заново смотреть на экран после каждого действия, то есть выполнять шаг «проверка» в цикле observe-act-verify.

Шаг «Agent выбирает ref» на схеме выше — это уже решение модели. agent-desktop лишь структурированно передаёт интерфейс наружу, а читать JSON и решать, по какому элементу кликнуть, — работа вызывающей модели.

Как разделить обязанности между agent-desktop и agent-browser

Оба проекта относятся к Vercel Labs, и документация у них тоже на одном сайте, но границы ответственности очень чёткие:

Критерий сравнения	agent-desktop	agent-browser
Цель	Нативные десктоп-приложения (Finder, системные настройки, нативные клиенты)	Веб-страницы и содержимое браузера
Способ наблюдения	Дерево доступности ОС	Структура страницы на стороне браузера
Приложения Chromium / Electron	Можно передать agent-browser через порт DevTools	Подходит для работы с веб-содержимым таких приложений
Есть ли модель	Нет	Тоже работает как инструмент, который вызывает Agent
Типичные команды	`snapshot`, `click`, `clipboard-set`	Навигация и взаимодействие со страницей

Практичное разделение выглядит так: нативные окна, строка меню, Dock, уведомления — на agent-desktop; если же дело касается веб-содержимого на веб-странице или в Electron-приложении, переключаемся на agent-browser через порт DevTools.

Версии agent-desktop и источники фактов

agent-desktop развивается очень быстро, несколько ключевых версий принесли изменения в поведении, часть из них — разрушающие (breaking changes). В таблице ниже источник факта указан явно, «неизвестно» означает, что официальные материалы пока не уточняют.

Версия / дата	Основные изменения	Источник
1.0.0 (2026-10-27)	Поддержка Linux официально входит в 1.0	Официальный Changelog
1.1.0 (2026-11-02)	envelope обновлён до 2.6; поддержка macOS Dock и menu-bar-extras; разрушающие изменения, связанные с идентификацией	Официальный Changelog
1.2.0 (2026-11-05)	Добавлен MCP (`agent-desktop mcp`); type / set-value / clipboard-set поддерживают `--stdin`	Официальный Changelog
1.3.0 (2026-11-11)	Добавлены `agent-desktop sandbox` и macOS sandbox provider; snapshot для menu/menubar больше не содержит data.window (разрушающее изменение)	Официальный Changelog
Песочница Windows / Linux	Будет ли предоставлен соответствующий provider	Неизвестно

Быстрый старт с agent-desktop

Дальше идём по порядку: установка → авторизация → минимальный рабочий цикл → подключение MCP.

Шаг 1: установка agent-desktop

Требования к платформе: macOS 13+; Windows 10 1809+ (x64 / ARM64); Linux — Ubuntu 24.04+ (x86_64 / aarch64), X11 или Wayland — без разницы. Установить можно одним из способов:

npm (нужен Node 18+, в пакет входят нативные бинарники для каждой платформы): npm install -g agent-desktop
Homebrew (macOS / Linux, уже есть в homebrew-core): brew install agent-desktop
Нативная сборка: скачайте из GitHub Releases; helper нужно положить рядом с исполняемым файлом.

После установки первым делом запустите agent-desktop status, чтобы убедиться, что бинарник и окружение текущей платформы в порядке.

Шаг 2: Авторизация разрешений agent-desktop

На macOS нужно выдать терминалу или хост-процессу разрешение «Универсальный доступ» (Accessibility), иначе дерево доступности не прочитать. Официально есть направляющая команда:

agent-desktop permissions --guide: следуйте подсказкам и завершите авторизацию универсального доступа в системных настройках
После авторизации запустите ещё раз agent-desktop status для повторной проверки

Важный момент: разрешение выдаётся «тому процессу, который запускает agent-desktop». Если вы вызываете его косвенно — через Claude Code, какую-нибудь IDE или MCP-клиент, — возможно, придётся дать разрешение соответствующему хост-приложению.

Шаг 3: Пройти минимальный цикл snapshot → click → snapshot

На примере Finder три команды образуют полный цикл «наблюдение — действие — проверка»:

agent-desktop snapshot --app Finder -i: получить дерево доступности Finder, -i используется для фокусировки на интерактивных элементах, в выводе JSON есть ref вида @s8f3k2p9:e8
agent-desktop click @s8f3k2p9:e8: кликнуть по целевому элементу из предыдущего snapshot, обязательно указывать полный ref
agent-desktop snapshot --app Finder -i: снова наблюдать и проверить, изменился ли интерфейс так, как ожидалось

Если на шаге 2 появилась ошибка STALE_REF или AMBIGUOUS_TARGET, значит интерфейс уже изменился — просто вернитесь к шагу 1 и сделайте snapshot заново. Для приложений, которым нужны настоящие события указателя или клавиатуры, можно добавить глобальный параметр --headed, чтобы переключиться в режим физического ввода.

Для интерфейсов с большим количеством элементов полный snapshot за один раз получится очень длинным и впустую потратит токены модели. Можно получать его в два уровня:

agent-desktop snapshot --skeleton --app Finder: сначала взять скелет и увидеть примерные области
agent-desktop snapshot --app Finder --root @<ref из скелета>: затем спуститься в конкретное поддерево

Этот приём заметно сокращает контекст, который отправляется в модель. Для вызывающей стороны чем короче контекст, тем ниже стоимость по токенам.

Шаг 4: подключение Agent через MCP и skills

Начиная с версии 1.2.0, в agent-desktop встроен MCP-сервер, который работает через stdio и предоставляет такие инструменты, как desktop_snapshot, desktop_click и другие. Форматы конфигурации у разных клиентов немного отличаются; ниже — примеры:

Команда запуска: agent-desktop mcp
Общий пример JSON-конфигурации: {"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}}
Пример для Claude Code: claude mcp add agent-desktop -- agent-desktop mcp

Если ваш Agent поддерживает skills, можно также напрямую загрузить официальную инструкцию, чтобы модель знала, как вызывать инструменты:

agent-desktop skills get desktop, agent-desktop skills get platform: выводят описание навыков
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop: установка через skills.sh

Если нужен вызов в том же процессе, можно использовать C-библиотеку libagent_desktop_ffi.

Опционально: agent-desktop sandbox в версии 1.3.0

В версии 1.3.0 добавлены подкоманда agent-desktop sandbox и провайдер sandbox для macOS. Они позволяют запускать автоматизацию в локально подписанной виртуальной машине macOS и изолировать действия Agent от вашего реального рабочего стола. Это необязательный шаг, минимальный рабочий сценарий от него не зависит. Если вы опасаетесь, что Agent случайно изменит реальные файлы, или хотите запускать много исследовательских задач, этот вариант стоит рассмотреть в первую очередь.

🚀 Быстрый старт: после настройки MCP вызывающему Agent всё ещё нужна рабочая модель. Официальный рекомендуемый способ — создать токен в консоли APIYI apiyi.com, а затем указать Base URL Agent на этот сервис: с одним ключом можно переключаться между Claude, GPT, Gemini и другими моделями и сравнивать их.

Подключаем «мозг» модели к циклу agent-desktop

agent-desktop отвечает только за «глаза и руки» — решение о том, какой ref нажать и выполнена ли задача, принимает вызывающая сторона, то есть «мозг». В этом месте есть две ключевые настройки: Base URL и модель.

Base URL: важно различать, с /v1 или без

Вызывающий Agent обычно работает по одному из двух протоколов, и Base URL записывается по-разному — неправильная запись чаще всего и приводит к 404:

Протокол, совместимый с OpenAI (большинство самодельных скриптов, OpenAI-совместимый провайдер в OpenCode): https://api.apiyi.com/v1 — с /v1
Нативный протокол Anthropic (Claude Code и другие клиенты, которые напрямую работают с интерфейсом messages): https://api.apiyi.com — без /v1

На примере Claude Code конфигурацию можно показать через переменные окружения:

export ANTHROPIC_BASE_URL=https://api.apiyi.com
export ANTHROPIC_AUTH_TOKEN=你的令牌

Если самодельный Python- или Node-скрипт использует OpenAI SDK, укажите base_url как https://api.apiyi.com/v1, а в model впишите claude-opus-5-5. Токен создаётся на api.apiyi.com/token, подробности настройки — в docs.apiyi.com/faq/base-url-config.md.

Как написать цикл собственного агента

Если не хочется зависеть от готового агента, свой цикл написать не так уж сложно. Основные шаги такие:

Запустите agent-desktop snapshot --app 目标应用 -i и прочитайте JSON envelope из stdout.
Передайте модели цель задачи вместе с snapshot JSON и попросите вернуть только следующее действие и полный ref.
Выполните команду, которую вернула модель. Например: agent-desktop click @sxxxx:eN.
Снова сделайте snapshot и передайте новый результат модели, чтобы она решила, всё ли готово. Если пришёл STALE_REF, сразу заново считайте состояние экрана.
Задайте максимальное число шагов и точки ручного подтверждения, чтобы не уйти в бесконечный цикл и не допустить действий сверх полномочий.

Шаги 2 и 4 расходуют токены. Упомянутый выше способ детализации через --skeleton и --root здесь напрямую влияет на стоимость.

Выбор модели: claude-opus-5-5 и claude-sonnet-5-5

Обе модели Claude уже есть в общем каталоге моделей APIYI и поддерживают эндпоинты chat и messages. Цены в таблице указаны на 2026-11-13, за 1 млн токенов. Модели и цены смотрите в актуальном списке моделей на платформе.

Модель	Вход	Выход	Чтение из кэша	Подходящие сценарии agent-desktop	Доступная платформа
`claude-opus-5-5`	$4	$20	$0.2	Многошаговые задачи со сложным интерфейсом, где нужна сильная способность планирования	APIYI apiyi.com
`claude-sonnet-5-5`	$2	$10	$0.1	Понятные пошаговые и более повторяющиеся повседневные операции	APIYI apiyi.com

Рабочий подход такой: сначала прогнать процесс на claude-opus-5-5, а когда промпты и шаги станут понятны, оценить, можно ли перевести стабильные участки на claude-sonnet-5-5. В snapshot JSON много повторяющихся системных подсказок и описаний инструментов, а чтение из кэша заметно дешевле обычного входа — поэтому включать кэширование промптов в длинных циклах довольно выгодно. Актуальные цены смотрите на docs.apiyi.com/models.

Устранение неполадок agent-desktop: проблема с правами доступа или с моделью

agent-desktop и модель — это две независимые цепочки. Когда что-то падает с ошибкой, полезно сначала понять, на чьей стороне проблема: так вы сэкономите кучу времени.

Симптом	Где искать	Возможная причина	Что делать
snapshot пустой или приложение не читается	Сторона инструмента	Не выдано разрешение Accessibility (Универсальный доступ), либо приложение вообще не предоставляет дерево доступности	Запустите `agent-desktop permissions --guide` и проверьте разрешения для хост-процесса
`INVALID_ARGS`	Сторона инструмента	Указан «голый» ref, например `@e8`	Используйте полный ref, например `@s8f3k2p9:e8`
`STALE_REF` / `AMBIGUOUS_TARGET`	Сторона инструмента	Интерфейс изменился, ref устарел	Сделайте snapshot заново
Запрос к модели 401	Сторона модели	Токен неверный или истёк, либо переменная окружения не подхватилась	Сверьте токен на `api.apiyi.com/token` и экспортируйте его заново
Запрос к модели 404	Сторона модели	Неправильно указан `/v1` в Base URL или опечатка в названии модели	В OpenAI-совместимом варианте нужен `/v1`, в нативном Anthropic — без него; сверьтесь со сводной таблицей моделей

Простой способ определить сторону: если команда agent-desktop в одиночку выдаёт в терминале JSON, значит со стороной инструмента всё в порядке, и остальные ошибки почти наверняка относятся к модели. Ошибки 401/404 на стороне модели удобно проверять по пунктам, сверяясь с описанием настройки Base URL в центре документации APIYI apiyi.com.

Риски разрешений и конфиденциальности в agent-desktop

В этом разделе речь идёт о рисках самого процесса автоматизации рабочего стола — они не связаны с аккаунтом, но перед началом работы их стоит внимательно прочитать.

Насколько серьёзно разрешение на спецвозможности. В macOS включение спецвозможностей (Accessibility) означает, что авторизованный процесс может читать и управлять интерфейсом других приложений. Если вы дали разрешение терминалу или какому-то хосту Agent, то любая программа, запущенная в этом процессе, может получить те же возможности. Рекомендуется давать разрешение только необходимым хостам, а после использования отключать его в системных настройках.

snapshot, буфер обмена и скриншоты могут содержать приватные данные. Официально указано, что snapshot, содержимое буфера обмена, скриншоты, уведомления и debug HTML могут содержать конфиденциальную информацию с рабочего стола — например, содержимое переписок, темы писем, имена файлов и интерфейс менеджера паролей. Эти данные вызывающая сторона отправляет в модель, поэтому не выкладывайте отладочные логи в открытый доступ и не вставляйте полные snapshot прямо в issue.

Опциональный helper выходит в сеть. Сам по себе нативный CLI не требует удалённого сервиса модели, но если включён опциональный JEV helper, он отправляет описание цели и экрана настроенному вами провайдеру модели. Включать ли его и кому отправлять — вы должны понимать сами.

Ответственность за последствия операций лежит на пользователе. Agent может нажать не ту кнопку, удалить не тот файл, отправить сообщение, которое отправлять не стоило. Снизить риски можно так: пробный запуск в sandbox версии 1.3.0, ограничение области --app, ручное подтверждение для рискованных операций вроде удаления, отправки, оплаты. Кроме того, приложения, чьё дерево доступности не читается, для agent-desktop невидимы — это граница возможностей, не стоит рассчитывать, что он сможет управлять любым софтом.

Подключение сторонних Agent к шлюзу — это другой тип риска. Когда вы подключаете Claude Code, OpenCode и других сторонних Agent к любому API-шлюзу, обращайте внимание на хранение токена, лимиты квоты и на то, не попадут ли конфиденциальные данные в логи. Это оценивается отдельно от рисков автоматизации рабочего стола. Рекомендуется создать для Agent отдельный токен и задать ему квоту, чтобы при проблемах можно было отдельно его аннулировать.

Частые вопросы (FAQ)

Вопрос 1: Что такое agent-desktop?

agent-desktop — это открытый computer use CLI от Vercel Labs. Через дерево доступности ОС он позволяет AI-агенту видеть десктопные приложения на macOS, Windows и Linux и управлять ими, не опираясь на скриншоты или попиксельное сопоставление. Это инструмент, а не Agent: собственной модели у него нет.

Вопрос 2: Чем agent-desktop отличается от computer use на основе скриншотов?

Подход на основе скриншотов опирается на визуальную модель: сначала она разбирает пиксели, а потом выдаёт координаты. Цепочка получается длинной и чувствительной к разрешению. agent-desktop сразу выдаёт структурированный JSON и ref, модель работает по ref, а по умолчанию он запускается в headless-режиме и не перехватывает указатель и фокус. Плата за это — видны только те приложения, которые предоставляют информацию о доступности.

Вопрос 3: Какая сейчас версия agent-desktop?

По состоянию на 2026-11-13 последняя видимая версия — 1.3.0 (2026-11-11), в ней появился sandbox. MCP доступен начиная с 1.2.0 (2026-11-05), а Linux официально вошёл в 1.0 в версии 1.0.0 (2026-10-27). Версии обновляются довольно быстро, сверяйтесь с GitHub Releases.

Вопрос 4: Для каких сценариев подходит agent-desktop?

— **Тестирование нативных приложений**: автоматически щёлкать по панели настроек, проверять состояние интерфейса
— **Расширение кодирующих агентов**: дать Claude Code после написания кода открыть десктопное приложение и проверить результат
— **Повторяющиеся операции на рабочем столе**: разбирать файлы в Finder, читать уведомления, читать и записывать буфер обмена

Задачи, связанные с веб-страницами, лучше передавать agent-browser.

Вопрос 5: Как агенту, который вызывает agent-desktop, быстро подключить модель?

1. Зарегистрируйтесь на APIYI apiyi.com и создайте API-ключ на странице токенов — новым пользователям доступна бесплатная тестовая квота.
2. В OpenAI-совместимом клиенте укажите Base URL `https://api.apiyi.com/v1`, в нативном клиенте Anthropic — `https://api.apiyi.com`.
3. Выберите модель `claude-opus-5-5` или `claude-sonnet-5-5`, а затем запустите цикл snapshot из этой статьи.

Вопрос 6: MCP настроен, но Agent выдаёт 401 или 404 — это проблема agent-desktop?

Обычно нет. agent-desktop не подключается к сервису моделей: 401 — это, как правило, проблема токена, а 404 — чаще всего ошибка в `/v1` или опечатка в названии модели. Сначала запустите в терминале отдельно `agent-desktop snapshot`, чтобы убедиться, что инструмент работает, а затем сверьтесь с документацией по настройке Base URL на APIYI apiyi.com и проверьте сторону модели.

Вопрос 7: Какие известные ограничения есть у agent-desktop?

— Приложения, чьё дерево доступности не читается, для него невидимы
— В некоторых версиях есть breaking changes (например, 1.1.0, 1.3.0) — перед обновлением читайте Changelog
— Провайдер sandbox сейчас ориентирован на macOS; будут ли его поддерживать другие платформы, пока неизвестно
— Веб-автоматизацию он не делает — для этого нужен agent-browser

agent-desktop: ключевые моменты

Инструмент без модели: agent-desktop выдает только JSON-envelope, а цикл и принятие решений остаются за вызывающей стороной.
computer use без скриншотов: работает через деревья доступности AX, UI Automation и AT-SPI и выполняет действия по ref.
ref должен быть полным: в формате @s8f3k2p9:e8; после изменения интерфейса нужно заново сделать snapshot.
Доступен на трех платформах: macOS 13+, Windows 10 1809+ и Ubuntu 24.04+.
Подключение через MCP одной строкой: начиная с версии 1.2.0 команда agent-desktop mcp работает через stdio.
Веб-страницы передаются agent-browser: приложения Electron можно передавать через порт DevTools.
Подключение «мозга»: в вызывающей стороне укажите Base URL APIYI (apiyi.com) и выберите claude-opus-5-5.

Итоги

Ключевые моменты agent-desktop:

Четкое позиционирование: это «глаза и руки» десктопных приложений. Модели внутри нет, веб-страницами он не занимается.
Простой цикл: установка → permissions --guide → snapshot → click → снова snapshot; --skeleton помогает управлять длиной контекста.
Гибкое подключение: доступны CLI, MCP, skills и FFI; sandbox в версии 1.3.0 подходит для изолированных пробных запусков.
Риски нужно контролировать: разрешения на доступность и приватные данные в snapshot требуют управления по стандартам автоматизации рабочего стола.

Когда инструмент настроен и работает, остается подобрать для цикла подходящий «мозг». Рекомендую создать токен в APIYI (apiyi.com) и указать Base URL в Claude Code, OpenCode или собственном скрипте. Сначала проверьте процесс на claude-opus-5-5, а затем в зависимости от сложности задачи решите, стоит ли переключаться на claude-sonnet-5-5.

📚 Справочные материалы

GitHub — agent-desktop: официальный открытый репозиторий, содержит README, FAQ и Changelog
Ссылка: github.com/vercel-labs/agent-desktop
Пояснение: изменения версий, список команд и уведомления о приватности — сверяйтесь здесь
Официальная документация agent-desktop: понятия и быстрый старт
Ссылка: agent-browser.dev/desktop, agent-browser.dev/desktop/quick-start
Пояснение: установка, авторизация и пример минимального замкнутого цикла
npm — agent-desktop: страница npm-пакета
Ссылка: npmjs.com/package/agent-desktop
Пояснение: просмотр текущей опубликованной версии
Vercel — What is computer use: введение в понятие computer use
Ссылка: vercel.com/i/what-is-computer-use
Пояснение: понимание различий между подходом на основе дерева доступности и подходом на основе скриншотов
Центр документации APIYI: сводная таблица моделей, настройка Base URL, описание возможностей Claude
Ссылка: docs.apiyi.com/models.md, docs.apiyi.com/faq/base-url-config.md, docs.apiyi.com/api-capabilities/claude.md
Пояснение: модели и цены — ориентируйтесь на список моделей платформы

Автор: Техническая команда APIYI
Обратная связь: будем рады, если вы свяжетесь с нами через главную страницу сайта APIYI apiyi.com; больше материалов — в центре документации docs.apiyi.com

Настольное приложение тоже может управлять Agent: подключение модели к agent-desktop за 5 шагов

Ключевые моменты agent-desktop

Как работает agent-desktop: дерево доступности и ref