Перейти к содержанию

На этой странице Встраивайте alibaba/page-agent в своё веб-приложение — это чистый JavaScript-агент для GUI на странице, который поставляется в виде одного тега <script> или npm-пакета и позволяет конечным пользователям вашего сайта управлять интерфейсом с помощью естественного языка («нажми Login, заполни username как John»). Не требует Python, headless-браузера или расширения. Используйте этот навык, когда пользователь — веб-разработчик, который хочет добавить ИИ-помощника в свой SaaS / админ-панель / B2B-инструмент, сделать унаследованное веб-приложение доступным через естественный язык или протестировать page-agent с локальной (Ollama) или облачной (Qwen / OpenAI / OpenRouter) LLM. НЕ для серверной автоматизации браузера — направляйте таких пользователей к встроенному инструменту браузера Hermes.

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

| | |---|---| |Источник| Опциональный — установка: hermes skills install official/web-development/page-agent | |Путь| optional-skills/web-development/page-agent | |Версия| 1.0.0 | |Автор| Hermes Agent | |Лицензия| MIT | |Теги| web, javascript, agent, browser, gui, alibaba, embed, copilot, saas |

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

info Далее приведено полное определение навыка, которое Hermes загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

page-agent

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

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

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

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

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

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

Предварительные требования​

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

Путь 1 — 30-секундная демонстрация через CDN (без установки)​

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

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

[code]

[/code]

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

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

[code] 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);})();

[/code]

Путь 2 — npm-установка в ваше веб-приложение (продуктивное использование)​

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

[code] npm install page-agent

[/code]

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

[code] 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')

[/code]

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

Провайдер baseURL model
Qwen / DashScope https://dashscope.aliyuncs.com/compatible-mode/v1 qwen3.5-plus
OpenAI https://api.openai.com/v1 gpt-4o-mini
Ollama (локально) http://localhost:11434/v1 qwen3:14b
OpenRouter https://openrouter.ai/api/v1 anthropic/claude-sonnet-4.6

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

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

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

Путь 3 — клонирование исходного репозитория (для доработок или экспериментов)​

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

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

[/code]

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

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

[/code]

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

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

[/code]

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

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

[/code]

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

[code] 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);})();

[/code]

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

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

Структура репозитория (Путь 3)​

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

Пакет Путь Назначение
page-agent packages/page-agent/ Основной вход с UI-панелью
@page-agent/core packages/core/ Базовая логика агента, без UI
@page-agent/mcp packages/mcp/ MCP-сервер (бета)
— packages/llms/ LLM-клиент
— packages/page-controller/ DOM-операции + визуальная обратная связь
— packages/ui/ Панель + i18n
— packages/extension/ Расширение для Chrome/Firefox
— packages/website/ Документация + сайт

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

После Пути 1 или Пути 2:

  1. Откройте страницу в браузере с открытыми инструментами разработчика
  2. Вы должны увидеть плавающую панель. Если нет, проверьте консоль на наличие ошибок (самые частые: CORS на LLM-эндпоинте, неправильный baseURL или неверный API-ключ)
  3. Введите простую инструкцию, соответствующую чему-то видимому на странице («нажми ссылку Login»)
  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 в продакшене — не делайте так. Он имеет ограничение по запросам, использует бесплатный прокси alibaba, и их условия запрещают продуктивное использование.
  • Раскрытие API-ключа — любой ключ, переданный в new PageAgent({apiKey: ...}), попадает в ваш JS-бандл. Всегда проксируйте через свой бэкенд для реальных развёртываний.
  • Не-OpenAI-совместимые эндпоинты молча терпят неудачу или выдают непонятные ошибки. Если ваш провайдер требует нативного форматирования Anthropic/Gemini, используйте прокси для OpenAI-совместимости (LiteLLM, OpenRouter) перед ним.
  • Блокировки CSP — сайты со строгой Content-Security-Policy могут отказаться загружать скрипт с CDN или запретить inline eval. В таком случае разместите скрипт на своём домене.
  • Перезапускайте dev-сервер после изменения .env в Пути 3 — Vite читает env только при запуске.
  • Версия Node — репозиторий указывает ^22.13.0 || >=24. Node 20 не пройдёт npm ci с ошибками engine.
  • npm 10 vs 11 — документация говорит npm 11+; npm 10.9 на самом деле работает отлично.

Ссылки​