Встройте агента page-agent – внутристраничный GUI-агент – в веб-приложение

Как применить

Page-agent – это внутристраничный GUI-агент, написанный на TypeScript, который находится внутри веб-страницы, считывает DOM как текст (без скриншотов, без мультимодальных LLM) и выполняет инструкции на естественном языке, такие как «нажмите на кнопку входа, затем введите имя пользователя Джон» на текущей странице. Это чисто клиентская часть; хост-сайт подключает скрипт и передаёт ему эндпоинт LLM, совместимый с OpenAI.

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

Модернизируйте устаревшее веб-приложение без переписывания фронтенда: page-agent размещается поверх существующего DOM.

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

Продемонстрируйте или оцените работу page-agent с локальным (Ollama) или удалённым (Qwen, OpenAI, OpenRouter) LLM.

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

Если пользователь хочет, чтобы сам Hermes управлял браузером, используйте встроенный инструмент браузера Hermes (Browserbase / Camofox); page-agent работает в противоположном направлении.

Для автоматизации между вкладками без встраивания используйте Playwright, browser-use или расширение page-agent для Chrome.

Если пользователю нужны визуальные данные или скриншоты, имейте в виду, что page-agent работает только с текстовым DOM; используйте мультимодального браузерного агента вместо него.

Примеры провайдеров для настройки эндпоинта LLM (подходит любой эндпоинт, совместимый с OpenAI) приведены в таблице ниже.

После шага 1 или шага 2 проверьте следующее.

После шага 3 проверьте следующее.

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

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

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

<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 в собственное веб-приложение (для производственного использования).

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

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,   // never hardcode
    language: 'en-US',
})

// Show the panel for end users:
agent.panel.show()

// Or drive it programmatically:
await agent.execute('Click submit button, then fill username as John')

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

model, baseURL и apiKey отвечают за подключение к LLM.

language устанавливает язык интерфейса (en-US, zh-CN и т.д.).

Существуют списки разрешений и хуки маскирования данных для ограничения доступа агента — полный перечень опций смотрите на https://alibaba.github.io/page-agent/.

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

Вариант 3 — склонируйте исходный репозиторий (для вклада или экспериментов с ним).

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

git clone https://github.com/alibaba/page-agent.git
cd page-agent
npm ci              # exact lockfile install (or `npm i` to allow updates)

Создайте файл .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           # docs/website dev server
npm run build       # build every package
npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
npm run dev:ext     # develop the browser extension (WXT + React)
npm run build:ext   # build the extension

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

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, нажмите на букмарклет на любой странице, и локальная сборка будет внедрена; она автоматически пересобирается при сохранении изменений.

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

Откройте страницу в браузере с открытыми инструментами разработчика.

Вы должны увидеть плавающую панель; если этого не произошло, проверьте консоль на наличие ошибок (чаще всего: проблемы с CORS на эндпоинте LLM, неверный baseURL или некорректный API-ключ).

Введите простую инструкцию, соответствующую чему-то видимому на странице («нажмите на ссылку Войти»).

Посмотрите на вкладке «Сеть» — вы должны увидеть запрос к вашему baseURL.

npm run dev:demo выводит Accepting connections at http://localhost:5174.

curl -I http://localhost:5174/page-agent.demo.js возвращает HTTP/1.1 200 OK с Content-Type: application/javascript.

Нажмите на букмарклет на любом сайте — появится панель.

Демо-CDN в продакшене — не используйте его. Он ограничен по скорости, использует бесплатный прокси Alibaba, и их условия запрещают его применение в продакшене.

Раскрытие API-ключа: любой ключ, переданный в new PageAgent({apiKey: ...}), попадает в ваш JS-бандл. Всегда перенаправляйте запросы через собственный бэкенд при реальном развертывании.

Эндпоинты, несовместимые с OpenAI, работают либо молча, либо с непонятными ошибками; если ваш провайдер требует формата Anthropic/Gemini, используйте прокси совместимости с OpenAI (LiteLLM, OpenRouter) перед ним.

Блокировки CSP: сайты со строгой политикой безопасности контента могут отказаться загружать скрипт с CDN или запретить inline-eval; в таком случае размещайте его на своем домене.

Перезапустите сервер разработки после изменения .env в варианте 3 — Vite считывает переменные окружения только при старте.

Версия Node: в репозитории указана ^22.13.0 || >=24; Node 20 вызовет ошибки npm ci из-за несоответствия версии.

npm 10 против 11: в документации сказано, что нужен npm 11+; на деле npm 10.9 работает нормально.