Autonomous Browser Agent — без скриншотов

Агент управляет реальным Chromium через Playwright, а решения принимает LLM на основе структурного текстового снимка страницы (ref | role | name | состояния), а не картинок. Vision-модель не нужна, скриншоты не делаются ни на одном шаге.

Три режима работы из одной кодовой базы:

Архитектура

Related MCP server: project-tendril

1. Установка на локальный комп

git clone https://github.com/maxmkab/autonomous-browser-agent.git
cd autonomous-browser-agent

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
playwright install chromium

cp .env.example .env             # вписать ANTHROPIC_API_KEY

Проверка без трат на LLM — посмотреть, что именно видит модель:

python main.py snapshot --url https://example.com

Запуск задачи с видимым браузером:

HEADLESS=false python main.py run \
  --task "Найди раздел с ценами и извлеки все тарифы через extract" \
  --url https://example.com \
  --json state/report.json

2. Встраивание в твой реальный браузер (CDP)

Агент может работать не в своём чистом Chromium, а в твоём Chrome — с живыми сессиями, расширениями и настоящим фингерпринтом. Никакие расширения ставить не нужно — управление идёт по Chrome DevTools Protocol.

# 1) запустить Chrome с открытым портом (отдельный профиль для агента)
chmod +x scripts/chrome-cdp.sh
./scripts/chrome-cdp.sh 9222          # Windows: scripts\\chrome-cdp.bat 9222

# 2) в другом терминале отдать задачу агенту в этом же браузере
CDP_URL=http://127.0.0.1:9222 python main.py run --task "..."

В этом режиме агент не трогает storage_state.json: сессии берутся из профиля Chrome. Первый запуск — залогинься в нужных сервисах руками, дальше профиль их помнит.

3. Встраивание в Claude Code / Cursor через MCP

mcp_server.py поднимает MCP-сервер со stdio-транспортом. Инструменты: browser_open, browser_snapshot, browser_click, browser_type, browser_select, browser_check, browser_scroll, browser_press, browser_back, browser_tabs, browser_save_session, browser_run_task, browser_close.

Конфиг для Claude Code (~/.claude.json или .mcp.json в корне проекта):

{
  "mcpServers": {
    "browser-agent": {
      "command": "/absolute/path/autonomous-browser-agent/.venv/bin/python",
      "args": ["/absolute/path/autonomous-browser-agent/mcp_server.py"],
      "env": {
        "HEADLESS": "false",
        "CDP_URL": "http://127.0.0.1:9222",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "REQUIRE_APPROVAL": "true"
      }
    }
  }
}

Или одной командой:

claude mcp add browser-agent -- /absolute/path/.venv/bin/python /absolute/path/mcp_server.py

После этого модель в Claude Code ведёт браузер циклом browser_snapshot → browser_click → browser_snapshot, получая только текстовые снимки. Сессия браузера живёт между вызовами, поэтому сценарий можно вести шаг за шагом. Для полной автономии есть browser_run_task — агент сам крутит цикл и возвращает JSON-отчёт.

4. Перенос авторизации на сервер

# локально, в видимом окне: залогинился → Enter в консоли
HEADLESS=false python main.py login --url https://site.ru/login

# переносим cookies + localStorage на сервер
scp state/storage_state.json root@YOUR_VPS_IP:/opt/browser-agent/state/

5. Деплой на VPS (Ubuntu 24.04 + Docker)

mkdir -p /opt/browser-agent/state && cd /opt/browser-agent
git clone https://github.com/maxmkab/autonomous-browser-agent.git .
cp .env.example .env && nano .env

docker build -t browser-agent .
docker run -d --name browser-agent --restart unless-stopped \
  --shm-size=1g \
  --env-file .env \
  -v /opt/browser-agent/state:/app/state \
  browser-agent

--shm-size=1g обязателен: Chromium в контейнере с дефолтными 64 МБ /dev/shm падает на тяжёлых страницах.

Разовая задача на сервере:

docker exec -it browser-agent python main.py run --task "..." --url https://...

Без Docker (systemd)

apt update && apt install -y python3-venv
cd /opt/browser-agent && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium

/etc/systemd/system/browser-agent.service:

[Unit]
Description=Autonomous browser agent
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/browser-agent
EnvironmentFile=/opt/browser-agent/.env
ExecStart=/opt/browser-agent/.venv/bin/python main.py daemon --interval 300
Restart=always
RestartSec=10
StandardOutput=append:/var/log/browser-agent.log
StandardError=append:/var/log/browser-agent.log

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now browser-agent
journalctl -u browser-agent -f

6. Постановка задач и n8n

Демон читает state/tasks.jsonl — одна строка = одна задача:

{"id":"price-check-1","task":"Открой карточку товара, извлеки цену и наличие через extract","url":"https://site.ru/item/123"}
{"id":"lead-form","task":"Заполни форму заявки: имя Иван, телефон +79990000000. Отправку подтвердит человек."}

Результаты пишутся в state/results.jsonl с полями success, result, extracted, steps, tokens_in/out и полной трассой history. n8n может писать задачи в этот файл (нода Execute Command / SSH) и читать результаты.

7. Экономия токенов

• Никаких скриншотов: только текст, без vision-модели.

• Фильтрация DOM: в контекст идут лишь видимые интерактивные элементы с непустым именем, максимум 250 на фрейм.

• Блокировка картинок/шрифтов/медиа на уровне сети (BLOCK_MEDIA=true).

• Сжатие истории (HISTORY_WINDOW): полные снимки только для последних шагов, старые сворачиваются в action → result.

• Детект зацикливания: если fingerprint снимка не меняется, модели даётся указание сменить стратегию.

8. Безопасность

Действия, попадающие под RISKY_PATTERNS (оплата, купить, заказать, удалить, отправить, checkout, pay, delete), требуют подтверждения: в консоли локально или ответом «да» в Telegram на сервере (APPROVAL_MODE=telegram). ALLOW_EVAL=false по умолчанию запрещает выполнение произвольного JS. Все ошибки действий возвращаются модели как observation и не роняют процесс. Секреты хранятся только в .env, который исключён из git.

9. Проверка перед продакшеном

1. python main.py snapshot --url <целевой сайт> — нужные элементы попадают в снимок?

2. Прогон задачи локально в headful с REQUIRE_APPROVAL=true.

3. Та же задача локально в headless — ловит различия рендеринга до деплоя.

4. Только потом деплой на VPS и запуск демона.

Лицензия

MIT