Примечание автора: от установки до работы со snapshot и ref и проверки результата — за 5 шагов разберём цикл agent-browser «прочитать страницу, нажать на элемент, снова прочитать страницу», который помогает AI-агенту надёжно управлять настоящим браузером.
Когда AI-агенту нужно работать с веб-страницей, возникают две типичные сложности: он не видит страницу и с трудом попадает по нужным элементам. Скриншоты и клики по координатам расходуют много токенов и не всегда точны; если же передать модели весь HTML, контекстное окно быстро заполнится. В этой статье мы разберём цикл snapshot-ref в agent-browser и покажем, как агент может управлять браузером, выполняя команды по одной.
Это не очередная статья с общим обзором автоматизации браузера. Мы пройдём всё в том порядке, в котором вы будете работать с инструментом: установим agent-browser, разберём связку snapshot и ref, стратегию повторных попыток при ошибках и подключение к рабочему процессу агента.
Главное: прочитав статью, вы поймёте, почему цикл snapshot-ref в agent-browser хорошо подходит для больших языковых моделей, и сможете выполнить свою первую задачу в браузере с помощью агента всего за 5 команд.
Главное о цикле snapshot-ref в agent-browser
agent-browser — инструмент автоматизации браузера с открытым исходным кодом от Vercel Labs, распространяемый по лицензии Apache-2.0. Это нативный CLI на Rust с понятной целью: дать ИИ-агенту браузер, которым можно управлять отдельными командами. Открыв страницу, агент считывает её в виде компактного текста на основе дерева доступности (accessibility tree), а затем взаимодействует с элементами с помощью shell-команд.
| Особенность | Описание | Польза для агента |
|---|---|---|
| Компактный текст snapshot | Страница выводится в виде дерева доступности, у каждого элемента есть ссылка ref, например @e1 |
Экономит контекст по сравнению со скриншотами и исходным HTML |
| Точное определение элементов через ref | Команды действий напрямую используют ref, например click @e1 |
Модели не нужно самостоятельно составлять CSS-селекторы |
| Браузер остаётся запущенным | Фоновый процесс поддерживает браузер открытым | Каждый шаг — это короткий вызов shell-команды |
| Явные сообщения об ошибках | Если элемент перекрыт, скрыт или отключён, клик завершается ошибкой, а не ложным успехом | Агент может решить, что делать дальше, опираясь на реальный результат |
| Встроенные навыки (skills) | CLI содержит инструкции по использованию, соответствующие его версии | Агент получает инструкции, актуальные для установленной версии |
Как работает цикл snapshot-ref
Этот цикл состоит из трёх действий: сначала snapshot считывает страницу, затем выполняется действие с выбранным ref, после чего страница считывается снова для проверки результата. И так по кругу. В официальном примере снимок example.com содержит всего одну строку: - link "Learn more" [ref=e1]. Увидев её, модель понимает, что на странице есть ссылка Learn more, и может нажать на неё с помощью @e1.
Такой подход разделяет понимание страницы и выполнение действия на два проверяемых шага и хорошо подходит для работы большой языковой модели с инструментами. Модели не нужно разбираться в сложной структуре DOM: достаточно найти в тексте нужный элемент и обратиться к его ref. Повторный снимок после каждого действия позволяет агенту принимать решения на основе актуального состояния страницы, а не полагаться на память и догадки.
Архитектура agent-browser
Сам CLI не управляет браузером напрямую. При выполнении первой команды запускается фоновый процесс — daemon, который управляет браузером через Chrome DevTools Protocol. Все последующие команды CLI отправляются этому процессу. Поэтому браузер остаётся открытым между командами, а состояние авторизации и положение на странице сохраняются.
У каждой --session есть собственный daemon и браузер, поэтому несколько задач могут выполняться параллельно, не мешая друг другу. По умолчанию, если в течение часа команды не поступают, браузер в headless-режиме закрывается, а daemon завершает работу. Если настроено сохранение сессии (session persistence), перед выходом состояние сохраняется.
«Мозг» этого цикла — большая языковая модель. На каждом шаге текст снимка попадает в контекст модели, и она выбирает следующую команду. Поэтому способность модели следовать инструкциям и стоимость её использования напрямую влияют на успешность и стоимость задачи. APIYI предоставляет API-доступ к упомянутым в статье моделям Claude, DeepSeek, Kimi и другим. Сервис поддерживает оба формата интерфейса — OpenAI и Anthropic; документация по подключению доступна на docs.apiyi.com.
Быстрый старт с agent-browser: цикл snapshot-ref за 5 шагов
Шаг 1. Установите agent-browser и браузер
Обычно agent-browser устанавливают глобально через npm, а затем скачивают Chrome for Testing. Пакет npm автоматически выбирает нативный бинарный файл для вашей платформы. Сейчас поддерживаются macOS (ARM64, x64), Linux (ARM64, x64, glibc и musl) и Windows (x64).
| Способ установки | Команда | Когда использовать |
|---|---|---|
| Глобальная установка через npm | Сначала npm install -g agent-browser, затем agent-browser install |
Большинство сред разработки; при первой установке нужно скачать браузер |
| Homebrew | Сначала brew install agent-browser, затем agent-browser install |
Для пользователей macOS |
| Linux с зависимостями | agent-browser install --with-deps |
Для серверов и контейнеров, где также нужно установить системные библиотеки браузера |
| Без установки | npx agent-browser open example.com |
Чтобы быстро попробовать инструмент или выполнить разовую задачу в CI |
| Команды обслуживания | agent-browser upgrade, agent-browser doctor |
Для обновления и диагностики проблем с окружением |
Для сборки из исходного кода официально требуются Node.js 24 или новее, pnpm 11 или новее и инструменты Rust. Последовательно выполните pnpm install, pnpm build:source, pnpm link --global, а затем запустите agent-browser install. Для повседневного использования достаточно установки через npm.
Шаги 2–5: полный минимальный цикл
После установки эта последовательность команд позволит пройти полный цикл snapshot-ref. Сначала попробуйте выполнить его вручную в терминале и проверить результат каждого шага, а затем поручите выполнение агенту.
| Шаг | Команда | Действие | Ожидаемый результат |
|---|---|---|---|
| 2. Открыть страницу | agent-browser open example.com |
Запускает демон и открывает сайт | Браузер остаётся работать в фоне |
| 3. Прочитать снимок | agent-browser snapshot -i |
Выводит только интерактивные элементы, каждый со своим ref | Вывод вида link "Learn more" [ref=e1] |
| 4. Выполнить действие по ref | agent-browser click @e1 |
Нажимает на элемент из снимка | Переход на другую страницу или изменение состояния |
| 5. Проверить результат | agent-browser get url |
Считывает текущий URL, чтобы убедиться, что действие сработало | Возвращает адрес после перехода |
| Завершение | agent-browser close |
Закрывает браузер | Освобождает ресурсы |
Параметр -i на шаге 3 особенно важен: он оставляет в выводе только интерактивные элементы и значительно сокращает текст снимка. Это удобно, когда бюджет токенов ограничен. Проверку на шаге 5 тоже нельзя пропускать: агент должен оценивать успех действия по фактическому результату, а не считать, что нажатие автоматически означает успех.
🚀 Быстрый старт: когда ручной цикл заработает, можно передать эти команды агенту. Рекомендуем сначала получить тестовый лимит через APIYI apiyi.com и попробовать несколько моделей на одной и той же задаче. Так вы увидите, какая из них лучше выбирает нужный ref из текста снимка. Интерфейс совместим с форматами OpenAI и Anthropic: в большинстве существующих фреймворков для агентов достаточно заменить ключ и адрес. Подробности — в документации на docs.apiyi.com.
Срок действия ref в agent-browser и повторное создание снимка
ref описывает страницу на момент создания снимка. При переходе на другую страницу или изменении DOM старый ref может устареть или даже указывать на неправильный элемент. Поэтому главное правило: после каждого перехода или заметного изменения страницы сначала снова выполните snapshot, а затем используйте новые ref.
Это правило лучше сразу включить в системный промпт агента. Надёжный цикл выглядит так: «снимок, действие, снимок», а не «один снимок, десять действий подряд». Стоимость дополнительного снимка гораздо ниже затрат на поиск ошибки и откат после клика не по тому элементу.
Что делать, если клик в agent-browser не удался
agent-browser не делает вид, что клик прошёл успешно. Если целевой элемент скрыт, отключён, находится за пределами видимой области или перекрыт другим элементом, например окном согласия на Cookie, click сразу вернёт ошибку. Это удобно для агента: само сообщение об ошибке помогает решить, что делать дальше.
| Причина ошибки | Типичный случай | Что делать |
|---|---|---|
| Элемент перекрыт | Окно согласия или другое всплывающее окно закрывает кнопку | Сначала закройте перекрывающий элемент, затем создайте новый снимок и повторите попытку |
| Элемент вне видимой области | Элемент находится ниже на странице | Прокрутите страницу с помощью scroll, затем создайте новый снимок |
| Элемент отключён | Кнопка недоступна, потому что форма заполнена не полностью | Заполните обязательные поля с помощью fill, затем проверьте снимок |
| Элемент скрыт | Элемент появляется только после раскрытия меню | Сначала раскройте меню, дождитесь его появления с помощью wait, затем создайте снимок |
| ref устарел | Страница перешла по ссылке или обновилась | Снова выполните snapshot, чтобы получить новые ref |
Помимо ref, agent-browser поддерживает CSS-селекторы, поиск по тексту, XPath и семантические локаторы. Например, команда agent-browser find role button click --name "Submit" находит кнопку отправки по роли и имени и нажимает её. Если структура страницы стабильна, а семантика элементов понятна, семантические локаторы могут дополнить ref.
Основные группы команд agent-browser
agent-browser поддерживает множество команд. Полный список доступен через agent-browser --help, а справка по отдельной команде — через agent-browser <command> --help. Ниже мы сгруппировали самые полезные команды по назначению, чтобы вам было проще решить, какие возможности предоставить агенту.
| Группа | Основные команды | Типичные задачи |
|---|---|---|
| Навигация и чтение | open, back, reload, read, snapshot, get, is |
Открытие страниц, чтение снимков, проверка состояния |
| Взаимодействие | click, fill, type, press, select, check, scroll, upload, find |
Клики, заполнение форм, загрузка файлов |
| Ожидание | wait |
Ожидание появления элемента или загрузки страницы |
| Сбор данных | screenshot, pdf, record, download, diff |
Снимки экрана, экспорт в PDF, запись экрана, сравнение страниц |
| Состояние страницы и сети | cookies, storage, network, eval |
Управление cookie, перехват сетевых запросов, выполнение скриптов |
| Вкладки и всплывающие окна | tab, frame, dialog |
Работа с несколькими вкладками, iframe и диалоговыми окнами |
| Отладка и производительность | console, errors, trace, vitals, a11y |
Сбор ошибок консоли и показателей производительности |
| Сессии и аутентификация | session, state, auth, confirm, deny |
Изоляция сессий, сохранение состояния входа, подтверждение чувствительных операций |
| Интеграция с агентами | skills, mcp, flow, batch, plugin |
Загрузка навыков, запуск MCP-сервера |
По умолчанию используется браузер Chrome for Testing. Вы также можете подключиться к уже запущенному Chrome с помощью --cdp или --auto-connect, переключиться на движок Lightpanda или Obscura с помощью --engine, управлять Mobile Safari в симуляторе iOS или подключить облачный браузерный сервис, например Browserbase, Browserless, Browser Use, Kernel или AgentCore.
Подключаем agent-browser к AI-агенту
Обучаем агента с помощью встроенных навыков
Одна из удачных идей agent-browser — поставлять инструкции вместе с CLI. Команда agent-browser skills get core выводит описание основного цикла работы, использования ref, стратегий ожидания и типичных рабочих сценариев. Флаг --ref commands позволяет посмотреть отдельный справочный раздел, например полный список команд, а --full добавляет полную справку по командам и шаблоны. Команда agent-browser skills list также выводит список специализированных навыков, таких как electron, slack и dogfood.
В фреймворке для агентов навык обнаружения можно установить командой npx skills add vercel-labs/agent-browser. Это лишь небольшая инструкция, которая направляет агента к agent-browser skills get core. Поэтому указания всегда соответствуют установленной версии CLI. Если устанавливать навык не хочется, можно добавить в AGENTS.md одну строку: используйте agent-browser для автоматизации браузера, перед первым использованием выполните agent-browser skills get core и следуйте полученным инструкциям.
Подключение через MCP
Если ваш клиент поддерживает MCP, команда agent-browser mcp запустит MCP-сервер через stdio. После этого десктопные клиенты вроде Claude или собственные агенты смогут вызывать операции браузера как стандартные инструменты — без отдельной обёртки для выполнения команд в shell.
Выбор управляющей модели для цикла snapshot-ref
Задачи в браузере обычно требуют много шагов, и на каждом из них модель получает текстовый снимок страницы. Поэтому входящих токенов, как правило, значительно больше, чем исходящих. При выборе модели стоит учитывать не только способность следовать инструкциям, но и стоимость входящих и кэшированных токенов. Цены в таблице приведены по данным страницы цен APIYI docs.apiyi.com/models; единицы измерения и условия тарификации уточняйте на странице цен.
| Модель | Цена входящих токенов | Цена исходящих токенов | Цена кэша | Подходящие задачи | Доступная платформа |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | Сложные многошаговые задачи, проблемные страницы | APIYI apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | Основная модель для повседневных задач | APIYI apiyi.com |
| kimi-k3.1-pro | $2 | $10 | $0.2 | Работа с китайскоязычными веб-страницами | APIYI apiyi.com |
| deepseek-v4.1-flash | $0.3 | $1.2 | $0.006 | Простые формы, массовые проверки | APIYI apiyi.com |
Практичный вариант: использовать deepseek-v4.1-flash для массовых задач с простой структурой и фиксированными шагами, claude-sonnet-5-5 — как основную универсальную модель, а для страниц со сложными взаимодействиями или частыми ошибками переключаться на claude-opus-5-5. Поскольку текст skills и системный промпт повторяются на каждом шаге, модели с более дешёвым кэшем позволяют сократить расходы в длинных циклах.
Стоит отметить, что моделей семейства ERNIE от Baidu пока нет в таблице цен APIYI: APIYI ещё не подключила эти модели, но мы постараемся сделать это как можно скорее. Если ваш агент изначально зависит от ERNIE, для тестирования пока можно использовать модели из таблицы выше.
💡 Совет по выбору: нет модели, которая лучше всех работает на любых сайтах. Выберите от 3 до 5 реальных страниц для небольшого теста, переключайте модели через единый интерфейс APIYI apiyi.com и сравните долю успешных выполнений и стоимость одной задачи, прежде чем выбрать основную модель.
Рекомендации по безопасному использованию agent-browser
Если Agent работает с настоящим браузером, границы безопасности нужно продумать заранее. В разделе безопасности официальной документации agent-browser описаны такие механизмы, как хранилище учётных данных (auth vault), белый список доменов, политики действий и границы содержимого. Команда auth управляет учётными данными, а confirm и deny позволяют подтверждать или отклонять чувствительные действия.
В продакшене стоит как минимум соблюдать три правила:
- Ограничьте доступные домены: с помощью белого списка разрешите Agent работать только с сайтами, связанными с вашими задачами. Так вредоносная страница не сможет направить его на незнакомый сайт.
- Не помещайте учётные данные в контекст: храните логины и пароли в auth vault, а не в промпте, чтобы они не попали в логи модели.
- Требуйте подтверждения чувствительных действий: настройте подтверждение для платежей, удаления данных и оформления заказов, чтобы последнее слово оставалось за человеком.
Сами веб-страницы тоже могут содержать вредоносные инструкции для Agent, поэтому механизм границ содержимого также стоит включить. Он помогает модели отличать текст на странице от инструкций пользователя и снижает риск инъекции промпта.
Часто задаваемые вопросы FAQ
Q1: Что такое цикл snapshot-ref в agent-browser?
Это основной принцип работы agent-browser: сначала команда `snapshot` считывает страницу в виде компактного текста с ref, затем выполняется действие с выбранным ref, после чего создаётся новый снимок для проверки результата. Цикл повторяется по мере необходимости. Такой подход разбивает понимание страницы и выполнение действий на небольшие проверяемые шаги и хорошо подходит для пошаговых рассуждений больших языковых моделей.
Q2: Чем agent-browser отличается от браузерного агента, работающего со скриншотами?
Скриншоты дают больше возможностей для визуального анализа, но требуют много токенов, а клики по координатам могут промахиваться. agent-browser, напротив, использует текст дерева доступности и ref для поиска элементов. Контекст получается компактнее, действия точнее, а при сбоях выдаётся явная ошибка. Поэтому он лучше подходит для задач автоматизации, где важна стабильность.
Q3: Почему после перехода на другую страницу нельзя использовать старые ref?
ref описывает страницу только на момент создания снимка. После навигации или изменения DOM элементы могли исчезнуть или быть заменены, поэтому старый ref может перестать работать или указывать не на тот элемент. После каждого изменения страницы нужно заново выполнить `snapshot` и использовать новые ref.
Q4: Для каких задач подходит agent-browser?
В первую очередь для следующих:
— **Автоматическое заполнение форм**: регистрация, подача заявок, ввод данных в панели управления и другие процессы с фиксированными шагами.
— **Проверка сайтов и регрессионное тестирование**: поиск ошибок и оценка производительности страниц с помощью `errors`, `console` и `vitals`.
— **Сбор информации**: постраничное чтение данных после входа в панель управления.
— **Специализированные задачи с Electron, Slack и другими инструментами**: расширение возможностей с помощью навыков из `skills list`.
Q5: Как подключить модель для управления agent-browser?
Можно действовать так:
1. Зарегистрируйтесь на сайте APIYI apiyi.com и получите API-ключ.
2. В фреймворке агента выберите формат, совместимый с OpenAI или Anthropic, и укажите параметры подключения согласно документации на docs.apiyi.com.
3. Используйте описанный в статье цикл из 5 шагов как тестовую задачу и сравните работу разных моделей.
APIYI поддерживает единый способ подключения к Claude, DeepSeek, Kimi и другим моделям. Для переключения достаточно изменить имя модели.
Q6: Как оценить стоимость работы модели в цикле snapshot-ref?
В браузерных задачах основная часть расходов приходится на входные токены: на каждом шаге модели передаются текст снимка и системный промпт. При оценке обращайте внимание на стоимость входных токенов и кэширования, а для сокращения снимков по возможности используйте `snapshot -i`. Актуальные цены моделей смотрите на странице APIYI docs.apiyi.com/models, а не в устаревших сторонних источниках.
Q7: Какие ограничения есть у agent-browser?
Из-за ограниченного срока действия ref агенту приходится часто создавать новые снимки, что увеличивает число шагов. Если на странице сильно не хватает информации для средств доступности, снимок может оказаться неполным. В таком случае на помощь придут CSS-селекторы, XPath или скриншоты. Кроме того, headless-браузер автоматически закрывается после часа простоя, поэтому для длительных задач нужно настроить сохранение сессии.
Ключевые выводы об agent-browser и цикле snapshot-ref
- Что это: agent-browser — CLI на Rust с открытым исходным кодом от Vercel Labs, который позволяет агенту управлять браузером с помощью отдельных команд.
- Основной цикл: получить снимок страницы, выполнить действие с ref и снова получить снимок для проверки. Эти три шага повторяются.
- Главное правило ref: после перехода на другую страницу или изменения DOM необходимо заново получить снимок, прежде чем использовать ref.
- Ошибка — это сигнал: если элемент перекрыт или недоступен, клик завершится ошибкой. Агенту следует сначала устранить препятствие, а затем повторить попытку.
- Подключение: используйте
skills get core, чтобы загрузить инструкции для установленной версии, илиagent-browser mcpдля подключения к MCP-клиенту. - Безопасность прежде всего: в продакшене включите белый список доменов, auth vault и подтверждение чувствительных операций.
- Выбор модели: сравните модели, управляющие браузером, через единый интерфейс APIYI apiyi.com. Актуальные цены указаны на docs.apiyi.com/models.
Итоги
Главное о цикле snapshot-ref в agent-browser:
- Текст вместо скриншотов: снимок дерева доступности и ref помогают модели понять содержимое страницы с минимальными затратами контекста.
- Проверка на каждом шаге: после каждого действия считывайте состояние страницы или URL, чтобы агент не продолжал работу в неверном состоянии.
- Обработка ошибок: для перекрытых или недоступных элементов, проблем с областью просмотра и устаревших ref предусмотрены понятные способы решения.
- Простое подключение: установка через npm, встроенные skills и MCP-сервер позволяют быстро встроить инструмент в существующего агента.
Сначала вручную выполните в терминале пять команд: open, snapshot, click, get и close. Затем добавьте правила цикла в системный промпт агента и подберите модель для управления браузером на реальных рабочих страницах.
Для быстрой проверки разных моделей с agent-browser можно использовать APIYI apiyi.com. Платформа совместима с форматами интерфейсов OpenAI и Anthropic. Инструкции по подключению доступны на docs.apiyi.com, а цены на модели — на docs.apiyi.com/models.
📚 Источники
- GitHub — agent-browser: официальный репозиторий с открытым исходным кодом
- Ссылка:
github.com/vercel-labs/agent-browser -
Описание: установка, быстрый старт, группы команд и инструкции для разработчиков
-
Официальная документация agent-browser: полное руководство и справочник команд
- Ссылка:
agent-browser.dev -
Описание: снимки, селекторы, сессии, режим CDP и механизмы безопасности
-
Документация по безопасности agent-browser: аутентификация и контроль доступа
- Ссылка:
agent-browser.dev/security -
Описание: хранилище учётных данных, белый список доменов, политики операций и границы содержимого
-
Центр документации APIYI: подключение моделей
- Ссылка:
docs.apiyi.com -
Описание: способы подключения через форматы, совместимые с OpenAI и Anthropic
-
Страница цен на модели APIYI: актуальная стоимость моделей
- Ссылка:
docs.apiyi.com/models - Описание: актуальные цены на все модели из этой статьи указаны на данной странице
Автор: техническая команда APIYI
Технические вопросы: свяжитесь с нами на главной странице сайта APIYI apiyi.com. Дополнительные материалы по подключению доступны в центре документации docs.apiyi.com.
