Page Agent

Встроить в веб-приложения GUI-копилот на странице, понимающий естественный язык.

Метаданные навыка

Справочник: полный SKILL.md

page-agent

alibaba/page-agent (https://github.com/alibaba/page-agent, 17k+ звёзд, MIT) — GUI-агент на TypeScript, работающий прямо внутри веб-страницы. Он читает DOM как текст (без скриншотов, без мультимодальных моделей) и выполняет инструкции на естественном языке — например, «нажми кнопку входа, затем заполни имя пользователя как John» — применительно к текущей странице. Полностью клиентский: сайт просто подключает скрипт и передаёт совместимый с OpenAI эндпоинт языковой модели.

Когда использовать этот навык

Загружай этот навык, если пользователь хочет:

• Встроить AI-копилот в собственное веб-приложение (SaaS, admin-панель, B2B-инструмент, ERP, CRM) — «пользователи на моём дашборде должны иметь возможность написать “создай счёт для Acme Corp и отправь его по email” вместо того, чтобы кликать по пяти экранам»
• Модернизировать устаревшее веб-приложение без переписывания фронтенда — page-agent накладывается поверх существующего DOM
• Добавить доступность через естественный язык — пользователи голосовых / скринридерных интерфейсов управляют UI, описывая желаемое действие
• Демонстрировать или оценивать page-agent с локальной (Ollama) или облачной (Qwen, OpenAI, OpenRouter) моделью
• Создавать интерактивные обучающие материалы / product demo — AI проводит пользователя через «как подать отчёт о расходах» прямо в реальном интерфейсе

Когда НЕ использовать этот навык

• Пользователь хочет, чтобы Hermes сам управлял браузером → используй встроенный браузерный инструмент Hermes Agent (Browserbase / Camofox). page-agent решает обратную задачу.
• Пользователю нужна автоматизация нескольких вкладок без встраивания → используй Playwright, browser-use или расширение page-agent для Chrome
• Пользователю нужна визуальная привязка / скриншоты → page-agent работает только с текстовым DOM; используй мультимодальный браузерный агент

Требования

• Node 22.13+ или 24+, npm 10+ (документация указывает 11+, но 10.9 работает нормально)
• Совместимый с OpenAI эндпоинт языковой модели: Qwen (DashScope), OpenAI, Ollama, OpenRouter или любой сервис, поддерживающий /v1/chat/completions
• Браузер с инструментами разработчика (для отладки)

Вариант 1 — 30-секундное демо через CDN (без установки)

Самый быстрый способ убедиться, что всё работает. Использует бесплатный тестовый LLM-прокси Alibaba — только для оценки, подчиняется их условиям использования.

Добавь на любую HTML-страницу (или вставь в консоль devtools как букмарклет):

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

Появится панель. Введи инструкцию. Готово.

Форма букмарклета (перетащи в панель закладок, нажми на любой странице):

javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();

Вариант 2 — npm install в собственное веб-приложение (продакшн)

Внутри существующего веб-проекта (React / Vue / Svelte / plain):

npm install page-agent

Подключи с собственным LLM-эндпоинтом — не используй демо-CDN для реальных пользователей:

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: process.env.LLM_API_KEY,   // никогда не хардкоди
    language: 'en-US',
})

// Показать панель конечным пользователям:
agent.panel.show()

// Или управлять программно:
await agent.execute('Click submit button, then fill username as John')

Примеры провайдеров (подойдёт любой OpenAI-совместимый эндпоинт):

Ключевые поля конфигурации (передаются в new PageAgent({...})):

• model, baseURL, apiKey — подключение к языковой модели
• language — язык интерфейса (en-US, zh-CN и т. д.)
• Список разрешений и хуки маскировки данных позволяют ограничить, с чем агент может взаимодействовать — полный список опций см. на https://alibaba.github.io/page-agent/

Безопасность. Не помещай apiKey в клиентский код для реального деплоя — проксируй запросы к языковой модели через бэкенд и направляй baseURL на свой прокси. Демо-CDN работает потому, что Alibaba сам запускает этот прокси для целей оценки.

Вариант 3 — клонирование репозитория (для доработки или изучения)

Используй этот вариант, если пользователь хочет модифицировать сам page-agent, тестировать его на произвольных сайтах через локальный IIFE-bundle или разрабатывать браузерное расширение.

git clone https://github.com/alibaba/page-agent.git
cd page-agent
npm ci              # установка по точному lockfile (или `npm i` для разрешения обновлений)

Создай .env в корне репозитория с LLM-эндпоинтом. Пример:

LLM_MODEL_NAME=gpt-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Вариант для Ollama:

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=NA
LLM_MODEL_NAME=qwen3:14b

Основные команды:

npm start           # dev-сервер документации/сайта
npm run build       # сборка всех пакетов
npm run dev:demo    # IIFE-bundle на http://localhost:5174/page-agent.demo.js
npm run dev:ext     # разработка браузерного расширения (WXT + React)
npm run build:ext   # сборка расширения

Тест на любом сайте с локальным IIFE-bundle. Добавь этот букмарклет:

javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();

Затем: запусти npm run dev:demo, нажми букмарклет на любой странице — локальная сборка подключится. При сохранении файлов пересборка происходит автоматически.

Внимание: LLM_API_KEY из .env вшивается в IIFE-bundle при dev-сборках. Не делись бандлом. Не коммить его. Не вставляй URL в Slack. (Проверено: grep по публичному dev-bundle возвращает буквальные значения из .env.)

Структура репозитория (Вариант 3)

Монорепозиторий с npm workspaces. Ключевые пакеты:

Проверка работоспособности

После Варианта 1 или 2:

1. Открой страницу в браузере с открытыми инструментами разработчика
2. Должна появиться плавающая панель. Если нет — смотри консоль на ошибки (чаще всего: CORS на LLM-эндпоинте, неверный baseURL или неверный API-ключ)
3. Введи простую инструкцию, соответствующую чему-то видимому на странице («click the Login link»)
4. В Network-вкладке должен появиться запрос к твоему baseURL

После Варианта 3:

1. npm run dev:demo выводит Accepting connections at http://localhost:5174
2. curl -I http://localhost:5174/page-agent.demo.js возвращает HTTP/1.1 200 OK с Content-Type: application/javascript
3. Нажми букмарклет на любом сайте — появится панель

Типичные ошибки

• Демо-CDN в продакшне — не делай этого. Там стоит rate limit, используется бесплатный прокси Alibaba, а их условия запрещают продакшн-использование.
• Утечка API-ключа — любой ключ, переданный в new PageAgent({apiKey: ...}), попадает в JS-bundle. Для реальных деплоев всегда проксируй через собственный бэкенд.
• Несовместимые эндпоинты падают молча или с непонятными ошибками. Если провайдер требует нативного формата Anthropic/Gemini, ставь перед ним OpenAI-совместимый прокси (LiteLLM, OpenRouter).
• Блокировка CSP — сайты со строгой Content-Security-Policy могут отклонить загрузку скрипта с CDN или запретить inline-eval. В таком случае размести скрипт на своём домене.
• Перезапуск dev-сервера после редактирования .env в Варианте 3 — Vite читает переменные окружения только при старте.
• Версия Node — репозиторий объявляет ^22.13.0 || >=24. Node 20 завершит npm ci с ошибкой движка.
• npm 10 vs 11 — документация требует npm 11+; npm 10.9 на практике работает нормально.

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

• Репозиторий: https://github.com/alibaba/page-agent
• Документация: https://alibaba.github.io/page-agent/
• Лицензия: MIT (построен на внутренних компонентах обработки DOM из browser-use, Copyright 2024 Gregor Zunic)