Visual Browser Agent

Локальный инструмент автоматизации браузера, который даёт ИИ-агентам «глаза и руки» для взаимодействия с веб-страницами. Visual Browser Agent — это Playwright плюс плоскость управления агентом: Playwright выполняет работу в браузере, а этот проект добавляет MCP-инструменты, визуальные доказательства, подтверждения, обработку идентичности Chrome, средства безопасности и рабочие процессы для агентов кодирования и повседневных задач в браузере.

Что происходит после установки

Вам не нужно разбираться в Chromium, CDP, удалённой отладке или внутренних именах профилей Chrome.

Технический установщик регистрирует Visual Browser Agent в используемом вами агенте кодирования и устанавливает среду выполнения браузера Playwright. После этого ваш обычный рабочий процесс происходит в чате агента кодирования. Вы можете сказать:

Use the browser to open this website and check the layout.

Агент сначала проверяет, доступна ли существующая сессия Chrome. Если она есть, он использует её; в противном случае запускает чистую сессию Chromium под управлением Playwright. Вы также можете явно указать это обычным языком:

Use my Work Chrome account and check the dashboard.

Агент обнаруживает понятные идентичности Chrome, такие как «Рабочая — work@example.com» и «Личная — personal@example.com». Если возможных идентичностей несколько, он спрашивает вас в разговоре. Вам не нужно выполнять команду профиля или выбирать Profile 3.

Visual Browser Agent также включает дополнительную локальную панель управления. Технический пользователь может запустить её с помощью npx visual-browser-agent dashboard, но панель управления не обязательна для обычного использования. Она показывает состояние подключения, активную вкладку, доступные идентичности Chrome и недавние доказательства по адресу http://127.0.0.1:8787/.

Прежде чем агент войдёт в систему, отправит сообщение, опубликует, купит, удалит, отправит или изменит внешние данные, он приостанавливается и запрашивает подтверждение. Проверка только для чтения, снимки экрана, визуальные аудиты и сбор доказательств могут выполняться автоматически.

Related MCP server: websight

Как это работает

Есть два браузера и два способа подключения:

Установка

Вариант 1: Попросите вашего агента кодирования установить его

В Claude Code, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity или другом агенте кодирования с поддержкой MCP спросите:

Install Visual Browser Agent, set it up for this coding agent, and check that the browser runtime is ready. Ask me before installing software or changing browser settings.

Агент должен проверить статус настройки, запросить подтверждение перед установкой Playwright Chromium, зарегистрировать MCP-сервер и сообщить о любых отсутствующих разрешениях или шагах с расширением. Затем вы можете просто сказать «используй браузер, чтобы …».

Вариант 2: Из GitHub (рекомендуется для тестирования)

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install dependencies
npm install

# Build
npm run build

# Initialize (installs Chromium + MCP + skills)
npx visual-browser-agent init

Или используйте напрямую с npx:

npx github:Akakaui/visual-browser-agent init

Вариант 3: Из npm (после публикации)

# Install globally
npm install -g visual-browser-agent

# Or use directly with npx
npx visual-browser-agent init

Вариант 4: Локальная разработка

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install in development mode
npm install

# Build
npm run build

# Link for global use
npm link

# Now you can use it anywhere
visual-browser-agent init

Быстрый старт

1. Инициализация

npx visual-browser-agent init

Это:

• Установит Chromium (браузер Playwright)

• Настроит конфигурацию MCP

• Установит навыки агента

• Автоматически определит вашего агента кодирования и установит обёртку

2. Начало использования

# Start MCP server with Chromium (default)
npx visual-browser-agent mcp

# Or start with Chrome extension
npx visual-browser-agent mcp --extension

3. Использование в вашем ИИ-агенте

Спросите своего агента: «Исследуй дизайн этого сайта»

Агент будет использовать Visual Browser Agent для управления браузером.

Использование вашего существующего Chrome (расширение)

Для полного пошагового руководства для обычного пользователя с переключением профилей, проверкой и устранением неполадок см. EXTENSION_INSTALLATION.md.

Если вам нужно, чтобы ваш агент использовал ваш существующий Chrome (с вашими логинами, куками, сессиями):

1. Установите расширение

1. Откройте Chrome → chrome://extensions/

2. Включите Режим разработчика

3. Нажмите Загрузить распакованное

4. Выберите: node_modules/visual-browser-agent/browser-extension

2. Запустите агента

npx visual-browser-agent mcp --extension

3. Использование в вашем ИИ-агенте

Спросите своего агента: «Войди в мою Gmail и обобщи мои письма»

Агент подключается к вашему Chrome со всеми вашими логинами.

Интеграция с ИИ-агентами

Автоматическое обнаружение (рекомендуется)

Когда вы запускаете npx visual-browser-agent init, он автоматически:

• Определяет, какого агента кодирования вы используете

• Устанавливает соответствующую обёртку

• Настраивает конфигурацию MCP

Ручная установка

Если автоматическое обнаружение не работает, вы можете установить вручную:

# Install for specific agent
npx visual-browser-agent host <agent-name>

Поддерживаемые агенты:

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

Добавьте в .claude/settings.json:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Для режима расширения Chrome

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp", "--extension"]
    }
  }
}

Как ИИ-агенты используют это

Сценарий 1: Исследование публичного сайта

Агент думает: «Это публичный сайт, вход не нужен».

Агент делает: Использует Chromium (по умолчанию)

npx visual-browser-agent mcp

Сценарий 2: Доступ к личным данным пользователя

Агент думает: «Для этого нужен вход пользователя».

Агент делает: Использует Chrome через расширение

npx visual-browser-agent mcp --extension

Сценарий 3: Пользователь указывает браузер

Пользователь говорит: «Используй мой рабочий аккаунт Chrome, в который я вошёл»

Агент делает:

npx visual-browser-agent mcp --choose-profile

Справочник команд

Панель управления для обычного пользователя

Для нетехнического пользователя браузерный агент должен быть установлен и зарегистрирован один раз администратором или при настройке агента кодирования. Затем пользователь работает через агента кодирования, говоря «используй браузер, чтобы открыть этот сайт», «используй мой рабочий аккаунт» или «проверь страницу и покажи мне снимки экрана». Агент обрабатывает подключение, обнаружение идентичности, доказательства и подтверждения через MCP.

Дополнительная локальная панель управления доступна для видимости подключения и восстановления. Технический пользователь может запустить её с помощью npx visual-browser-agent dashboard; она открывается по адресу http://127.0.0.1:8787/ и показывает состояние подключения, понятные идентичности Chrome, активную вкладку и недавние доказательства. Панель работает только локально и не заменяет разговор с агентом кодирования.

Поверхность совместимости Playwright 2.0

Visual Browser Agent предоставляет поверхность MCP на основе Playwright для рабочих процессов агентов. Помимо навигации, форм, загрузок, скачиваний, снимков экрана, записи, адаптивных аудитов и визуальных исследований, агенты могут использовать вкладки/страницы, историю, перетаскивание, ссылки на локаторы, веб-ориентированные утверждения, проверку фреймов, политику диалогов, куки, экспорт одобренного состояния хранилища, недавние сообщения консоли, недавние сетевые запросы, моки маршрутов URL, трассировку, эмуляцию мультимедиа, PDF-доказательства и оценку страницы с подтверждением.

Слой совместимости намеренно делает чувствительные операции явными. Очистка куки требует confirm=true; оценка страницы требует confirmDangerous=true; публичные отправки и удаление артефактов остаются под управлением службы подтверждения. Сетевые моки и артефакты хранилища ограничены активной сессией агента и одобренными каталогами.

Профили

Если у вас несколько профилей Chrome, выберите аккаунт, в который вы вошли, для использования с расширением:

# Choose an account interactively
npx visual-browser-agent mcp --choose-profile

# Advanced: use a known technical profile name
npx visual-browser-agent mcp --profile "Profile 3"

Устранение неполадок

Chromium не работает

npx playwright install chromium

Расширение Chrome не подключается

1. Убедитесь, что Chrome открыт

2. Проверьте, что значок расширения показывает «ON»

3. Попробуйте: npx visual-browser-agent doctor

MCP-сервер не запускается

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

Архитектура

User's AI Agent (Claude Code, Cursor, etc.)
                    |
                    | MCP Protocol
                    |
        Visual Browser Agent MCP Server
                    |
        +-----------+-----------+
        |                       |
    Chromium                  Chrome
    (Playwright)            (Extension)
        |                       |
        v                       v
  Agent controls           Agent connects
  fresh browser            to existing browser

Лицензия

MIT

Повседневное использование для нетехнических пользователей

Visual Browser Agent можно использовать в двух простых режимах:

Нетехническому пользователю не нужно понимать MCP. После одной настройки он может говорить своему агенту кодирования, что хочет, обычным языком, например: «Открой рабочий профиль Chrome, проверь страницу оформления заказа по этому URL и сохрани снимки экрана» или «Используй чистую сессию Chromium, чтобы сравнить этот сайт на десктопе и мобильном». Обёртка инструктирует агента кодирования проверить подключение к браузеру, выбрать подходящий режим, спрашивать перед аутентификацией или важными действиями и возвращать краткие выводы с доказательствами.

Профили Chrome: расширение против удалённой отладки

Расширения Chrome устанавливаются для каждого профиля Chrome, а не один раз для всех окон браузера. Если человек хочет использовать три отдельных профиля Chrome через режим расширения, он должен открыть каждый профиль, перейти на chrome://extensions/, включить режим разработчика и загрузить распакованный каталог browser-extension/ один раз в каждом профиле. Один и тот же исходный код расширения можно загрузить в каждый профиль, но каждый профиль должен предоставить свои собственные разрешения и оставаться открытым, когда этот профиль выбран.

Удалённая отладка отличается. Она подключается к экземпляру Chrome, запущенному с определённым --profile-directory и портом отладки. Большинству людей следует запускать visual-browser-agent mcp --choose-profile; инструмент считывает понятные метки аккаунтов из Chrome и позволяет пользователю выбрать один по номеру. Техническая опция --profile остаётся доступной для скриптов и продвинутых настроек. Профиль, уже используемый другим процессом Chrome, может отказать во втором запуске; закройте этот профиль сначала или используйте отдельный профиль отладки и порт.

Для пользователя, которому нужны существующие куки входа, маршрут расширения обычно самый простой. Для пользователя, который хочет повторяемый чистый браузер, Chromium безопаснее. Удалённую отладку следует рассматривать как продвинутую опцию, поскольку она открывает выбранную сессию браузера локальному процессу агента.

Выбор браузерного агента с помощью подсказки

Пользователь обычно выбирает задачу, а не режим браузера или специализированную модель. Скажите «используй браузер, чтобы …» в Claude, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity или другом MCP-совместимом кодинг-агенте. Обёртка сообщает агенту использовать автоматический выбор браузера, обнаруживать видимые Chrome-профили при необходимости и переключаться на управляемый Chromium, когда нет активной сессии. Кодинг-агент выбирает инструменты Visual Browser Agent MCP после установки интеграции. В промптах следует указывать требование к сессии, когда это важно:

Use a clean Chromium browser. Audit this public website at desktop and mobile widths and save visual evidence.

Use the Work account I choose from Chrome. Open the internal dashboard, inspect the layout, and ask me before making any changes.

Use the current browser session. Do not submit forms, publish, purchase, delete, or send messages without asking for approval first.

Если команда хочет выделенного браузерного специалиста, запустите visual-browser-agent host <agent-name> для кодинг-клиента и сохраните сгенерированную MCP-конфигурацию вместе с обёрткой в этом проекте. Пакет включает адаптеры для Claude Code, Cursor, Gemini, Windsurf, Cline, Roo, Kiro, Copilot, Codex, Goose, OpenCode и Antigravity, а для хостов без выделенной обёртки используется универсальная обёртка. Новые хосты могут использовать ту же стандартную MCP-конфигурацию: запустите команду visual-browser-agent mcp --managed и зарегистрируйте её как MCP-сервер с именем visual-browser.

Рекомендуемая первоначальная настройка

npm install
npm run build
npx visual-browser-agent init --mode chromium
npx visual-browser-agent host <your-coding-agent>

Затем перезапустите кодинг-агента и попросите его использовать инструменты визуального браузера. Для чистого ежедневного рабочего процесса с Chromium используйте visual-browser-agent mcp --managed. Для существующего Chrome-профиля используйте visual-browser-agent mcp --choose-profile после загрузки расширения в нужный профиль. Флаг --profile используйте только в продвинутых скриптах.

Агент всегда должен автоматически использовать инспекцию только для чтения и скриншоты при просмотре веб-сайта. Он должен запрашивать явное одобрение перед публикацией, размещением, покупкой, удалением, отправкой или изменением внешних данных. Аутентификация и личная конфиденциальная информация должны вводиться пользователем напрямую в браузере, а не помещаться в промпты или конфигурационные файлы.

Артефакты агента, панели артефактов, вопросы и одобрения

Полный рабочий процесс для обычного пользователя и технического специалиста описан в Руководстве пользователя Visual Browser Agent 1.0. Если кратко: кодинг-агент взаимодействует с Visual Browser Agent через MCP: он обнаруживает доступные браузерные инструменты, выбирает инструменты, соответствующие запросу пользователя, и получает текст, структурированный JSON, скриншоты и метаданные доказательств.

Visual Browser Agent разработан как для UI-ориентированных кодинг-агентов, так и для CLI-ориентированных. UI-хост, такой как Claude Code или Antigravity, может разместить скриншоты/изображения и сгенерированный HTML- или Markdown-отчёт с доказательствами на своей панели артефактов. CLI-хост или универсальный MCP-клиент может использовать тот же результат через встроенный блок изображения, структурированные метаданные, локальный путь к доказательствам или локальную панель по адресу http://127.0.0.1:8787/. Агент не должен предполагать, что хост может открыть произвольный путь в песочнице; он должен возвращать переносимый результат и запасной вариант.

Хороший результат браузерного агента содержит цель задачи, URL и источник, выбранную браузерную идентичность, выполненные действия, утверждения, скриншоты, данные консоли/сети, ID запуска, временную метку и следующий шаг. Это позволяет человеку проверить работу визуально, а не читать сырые журналы инструментов. При необходимости запрашивайте это у агента явно:

Create a host-renderable visual report with screenshots, assertions, console errors, and a concise conclusion. Also provide a local fallback.

Существует три вида взаимодействия с человеком. Вопрос устраняет недостающую информацию, например, какой Chrome-профиль или вкладку использовать. Передача управления человеку просит пользователя управлять браузером напрямую, когда появляется пароль, запрос MFA, CAPTCHA или одноразовый код. Одобрение авторизует значимое действие, такое как отправка, публикация, покупка, удаление или подача. Они намеренно разделены: вопрос — это не разрешение на действие, а скриншот — не доказательство того, что транзакция прошла успешно.

Запасной инструмент ask_human поддерживает вопросы и простые структурированные варианты выбора. Инструменты request_approval и submit_public_action зарезервированы для явной авторизации. Агент должен показать точный сайт, цель, действие и соответствующие данные перед запросом одобрения и должен рассматривать отказ как окончательное решение пользователя, а не молча повторять попытку. Никогда не вставляйте пароли, API-ключи, токены доступа, платёжные данные или одноразовые коды в разговор с агентом. Полную модель безопасности см. в docs/user-guide-1.0.md, а настройку расширения Chrome для каждого профиля — в EXTENSION_INSTALLATION.md.