Page-Agent Reference Document

Page-Agent is an in-page GUI agent that reads a webpage's DOM as text (no screenshots) and executes natural-language instructions against the current page. It runs entirely client-side; the host site includes a script and passes an OpenAI-compatible LLM endpoint. The project was first released in 2024.

When to Use

Ship an AI copilot inside a web app (SaaS, admin panel, B2B tool, ERP, CRM) so users can type commands instead of clicking through screens.
Modernize a legacy web app without rewriting the frontend by dropping page-agent on top of existing DOM.
Add accessibility via natural language for voice/screen-reader users.
Demo or evaluate page-agent against a local (Ollama) or hosted (Qwen, OpenAI, OpenRouter) LLM.
Build interactive training/product demos where an AI walks a user through a workflow live in the real UI.

Capabilities

Reads the DOM as text (no screenshots, no multi-modal LLM).
Executes natural-language instructions like "click the login button, then fill username as John".
Runs entirely client-side; host site just includes a script and passes an OpenAI-compatible LLM endpoint.
Provides a floating UI panel for end-user interaction.
Supports programmatic execution via agent.execute().
Supports allowlist and data-masking hooks to restrict what the agent can touch.
Available as a CDN demo script, an npm package for production, or a source repo for development/contribution.
Includes a browser extension (Chrome/Firefox) for cross-tab automation.
Provides an MCP server (beta).

Prerequisites

Node ^22.13.0 || >=24, npm 10+ (10.9 works).
An OpenAI-compatible LLM endpoint: Qwen (DashScope), OpenAI, Ollama, OpenRouter, or anything speaking /v1/chat/completions.
Browser with devtools (for debugging).

Installation and Setup

Path 1 — 30-second demo via CDN (no install)

Add the script tag to any HTML page:

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

Alternatively, create a bookmarklet with:

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

A panel appears. Type an instruction.

Path 2 — npm install into your own web app (production use)

Run:

npm install page-agent

Import PageAgent:

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')

Never ship the demo CDN to real users.

Path 3 — clone the source repo (contributing, or hacking on it)

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

Create .env in repo root with LLM endpoint. For OpenAI:

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

For Ollama:

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

Common commands:

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

Test on any website: run npm run dev:demo, then use bookmarklet:

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

Auto-rebuilds on save.

Configuration Parameters

When creating an instance with new PageAgent({...}), the following parameters are available:

Parameter	Meaning	Required
`model`	LLM model name (e.g., `qwen3.5-plus`, `gpt-4o-mini`, `qwen3:14b`, `anthropic/claude-sonnet-4.6`)	Yes
`baseURL`	OpenAI-compatible LLM endpoint URL (e.g., `https://dashscope.aliyuncs.com/compatible-mode/v1`, `https://api.openai.com/v1`, `http://localhost:11434/v1`, `https://openrouter.ai/api/v1`)	Yes
`apiKey`	API key for the LLM endpoint (never hardcode in production; proxy through backend)	Yes
`language`	UI language (e.g., `en-US`, `zh-CN`)	No (default likely `en-US`)

Repository Structure

The monorepo contains these packages:

page-agent — packages/page-agent/
@page-agent/core — packages/core/
@page-agent/mcp — packages/mcp/
packages/llms/
packages/page-controller/
packages/ui/
packages/extension/
packages/website/

Constraints and Caveats

Demo CDN is for evaluation only, subject to alibaba's terms; rate-limited; not for production.
Any apiKey passed to new PageAgent({apiKey: ...}) ships in the JS bundle; always proxy through your own backend for real deployments.
Non-OpenAI-compatible endpoints fail silently or with cryptic errors; use an OpenAI-compatibility proxy (LiteLLM, OpenRouter) in front.
Sites with strict Content-Security-Policy may refuse to load the CDN script or disallow inline eval; self-host from your origin in that case.
After editing .env in Path 3, restart the dev server (Vite only reads env at startup).
Node version must be ^22.13.0 || >=24; Node 20 will fail npm ci with engine errors.
npm 10.9 works fine despite docs saying npm 11+.
In Path 3, the .env LLM_API_KEY is inlined into the IIFE bundle during dev builds; do not share the bundle, commit it, or paste the URL into Slack.

Failure Modes

CORS on the LLM endpoint.
Wrong baseURL.
Bad API key.
Non-OpenAI-compatible endpoints fail silently or with cryptic errors.
CSP blocks script loading or inline eval.
Node version mismatch causes npm ci to fail with engine errors.

Verification

After running npm run dev:demo, you should see Accepting connections at http://localhost:5174. Verify the bundle is served:

curl -I http://localhost:5174/page-agent.demo.js

Expected response:

HTTP/1.1 200 OK
Content-Type: application/javascript

Examples

CDN demo: add script tag or bookmarklet to any HTML page; panel appears; type instruction.
npm install: import PageAgent, create instance with model/baseURL/apiKey/language, show panel or execute programmatically.
Clone repo: git clone, npm ci, create .env, run npm run dev:demo, use bookmarklet on any site to test local IIFE bundle.

Embed an In-Page GUI Copilot with Page Agent