Embed an In-Page GUI Copilot with Page Agent

Page Agent is a client-side TypeScript library that turns any webpage into a natural-language interface. It reads the DOM as text, sends instructions to an OpenAI-compatible LLM, and executes actions like clicking buttons or filling forms. You embed it with a single script tag or npm package, and your users can type "create an invoice for Acme Corp" instead of clicking through five screens.

What it does

Page Agent lives inside a webpage. It reads the page's DOM structure as plain text (no screenshots, no multi-modal model) and maps natural-language instructions to DOM operations. The library handles the full loop: parse the instruction, inspect the current DOM, decide which element to act on, execute the action, and report back. The host site only needs to include a script and point to an OpenAI-compatible LLM endpoint.

This is useful for:

• Adding an AI copilot to a SaaS, admin panel, B2B tool, ERP, or CRM
• Modernizing a legacy web app without rewriting the frontend
• Improving accessibility for voice or screen-reader users
• Evaluating page-agent against a local (Ollama) or hosted (Qwen, OpenAI, OpenRouter) LLM
• Building interactive product demos where an AI walks a user through a workflow live in the real UI

Before you start

• Node 22.13+ or 24+, npm 10+ (the docs say 11+ but 10.9 works fine)
• An OpenAI-compatible LLM endpoint: Qwen (DashScope), OpenAI, Ollama, OpenRouter, or anything speaking /v1/chat/completions
• A browser with devtools open for debugging

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

This is the fastest way to see page-agent work. It uses Alibaba's free testing LLM proxy. Use this for evaluation only; it is subject to their terms.

Add this script to any HTML page, or paste it into the devtools console as a bookmarklet:

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

A panel appears. Type an instruction. Done.

Bookmarklet form (drop into bookmarks bar, click on any page):

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

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

Inside an existing web project (React, Vue, Svelte, or plain HTML):

npm install page-agent

Wire it up with your own LLM endpoint. Never ship the demo CDN to real users.

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

Provider examples (any OpenAI-compatible endpoint works):

Provider	baseURL	model
Qwen / DashScope	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen3.5-plus
OpenAI	https://api.openai.com/v1	gpt-4o-mini
Ollama (local)	http://localhost:11434/v1	qwen3:14b
OpenRouter	https://openrouter.ai/api/v1	anthropic/claude-sonnet-4.6

Key config fields (passed to new PageAgent({...})):

• model, baseURL, apiKey, LLM connection
• language, UI language (en-US, zh-CN, etc.)
• Allowlist and data-masking hooks exist for locking down what the agent can touch, see https://alibaba.github.io/page-agent/ for the full option list

Security. Don't put your apiKey in client-side code for a real deployment. Proxy LLM calls through your backend and point baseURL at your proxy. The demo CDN exists because Alibaba runs that proxy for evaluation.

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

Use this when you want to modify page-agent itself, test it against arbitrary sites via a local IIFE bundle, or develop the browser extension.

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 the repo root with an LLM endpoint. Example:

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

Ollama flavor:

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 using the local IIFE bundle. Add this 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);})();

Then: npm run dev:demo, click the bookmarklet on any page, and the local build injects. Auto-rebuilds on save.

Warning: your .env LLM_API_KEY is inlined into the IIFE bundle during dev builds. Don't share the bundle. Don't commit it. Don't paste the URL into Slack. (Verified: grepping the public dev bundle returns the literal values from .env.)

Repo layout (Path 3)

Monorepo with npm workspaces. Key packages:

Package	Path	Purpose
page-agent	packages/page-agent/	Main entry with UI panel
@page-agent/core	packages/core/	Core agent logic, no UI
@page-agent/mcp	packages/mcp/	MCP server (beta)
,	packages/llms/	LLM client
,	packages/page-controller/	DOM ops + visual feedback
,	packages/ui/	Panel + i18n
,	packages/extension/	Chrome/Firefox extension
,	packages/website/	Docs + landing site

Verifying it works

After Path 1 or Path 2:

1. Open the page in a browser with devtools open
2. You should see a floating panel. If not, check the console for errors (most common: CORS on the LLM endpoint, wrong baseURL, or a bad API key)
3. Type a simple instruction matching something visible on the page ("click the Login link")
4. Watch the Network tab, you should see a request to your baseURL

After Path 3:

1. npm run dev:demo prints Accepting connections at http://localhost:5174
2. curl -I http://localhost:5174/page-agent.demo.js returns HTTP/1.1 200 OK with Content-Type: application/javascript
3. Click the bookmarklet on any site; panel appears

Pitfalls

• Demo CDN in production, don't. It's rate-limited, uses Alibaba's free proxy, and their terms forbid production use.
• API key exposure, any key passed to new PageAgent({apiKey: ...}) ships in your JS bundle. Always proxy through your own backend for real deployments.
• Non-OpenAI-compatible endpoints fail silently or with cryptic errors. If your provider needs native Anthropic/Gemini formatting, use an OpenAI-compatibility proxy (LiteLLM, OpenRouter) in front.
• CSP blocks, sites with strict Content-Security-Policy may refuse to load the CDN script or disallow inline eval. In that case, self-host from your origin.
• Restart dev server after editing .env in Path 3, Vite only reads env at startup.
• Node version, the repo declares ^22.13.0 || >=24. Node 20 will fail npm ci with engine errors.
• npm 10 vs 11, docs say npm 11+; npm 10.9 actually works fine.

When not to use it

• If you want Hermes itself to drive a browser, use Hermes' built-in browser tool (Browserbase / Camofox). Page Agent works in the opposite direction: it lives inside the page.
• If you need cross-tab automation without embedding, use Playwright, browser-use, or the page-agent Chrome extension.
• If you need visual grounding or screenshots, page-agent is text-DOM only. Use a multimodal browser agent instead.

Limits and gotchas

• The demo CDN is for evaluation only. Do not use it in production.
• API keys shipped in client-side code are exposed. Always proxy through your backend.
• Non-OpenAI-compatible endpoints may fail silently. Use a compatibility proxy if needed.
• Strict CSP policies can block the CDN script or inline eval. Self-host from your origin.
• After editing .env in Path 3, restart the dev server. Vite only reads env at startup.
• Node 20 will fail npm ci with engine errors. Use Node 22.13+ or 24+.
• npm 10.9 works fine despite the docs saying npm 11+.

Reference

• Repo: https://github.com/alibaba/page-agent
• Docs: https://alibaba.github.io/page-agent/
• License: MIT (built on browser-use's DOM processing internals, Copyright 2024 Gregor Zunic)