Guide · Open source

How to use page-agent: install, connect an LLM and run tasks

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

page-agent is an open-source JavaScript library from alibaba that runs inside a web page and lets an AI agent operate that page's interface from a plain-language instruction, such as clicking a login button. This guide is for developers who want to add an in-page assistant to their own web application. By the end you will know how to try it with the demo model, install it with npm, connect your own language model, and decide whether it fits your project.

Page Agentalibaba/page-agent · ★ 29.6k · MIT Install options & downloads

Quick start

1Try the demo. Add the demo script tag from the README to a test page and check the agent responds. Use it for evaluation only.
2Install from npm. Run npm install page-agent in your project. Confirm your Node.js version meets your own tooling needs, since the README does not specify one.
3Get an LLM endpoint. Obtain an API key or a compatible model endpoint, including a locally deployed model if you have one.
4Create the agent. Import PageAgent and pass model, baseURL, apiKey and language settings to the constructor.
5Run an instruction. Call agent.execute with a plain-language instruction such as Click the login button and check the result on the page.
6Add optional features. If you need multi-page tasks or external control, look at the Chrome extension and the MCP Server (Beta) in the docs.

What page-agent does and who it is for

page-agent is a GUI agent that lives in your web page. According to the project README, it needs no browser extension, no Python and no headless browser: it is just in-page JavaScript, and everything happens in your web page.

It works by reading the page's text-based DOM rather than screenshots, and the README says it needs no multi-modal LLMs or special permissions. You bring your own language model, including locally deployed ones.

Good fit: adding an AI copilot to your own web app
Good fit: automating repetitive form filling in internal ERP, CRM or admin tools you control
Good fit: client-side agents without a headless browser or backend
Poor fit: automating websites you do not control, since the README says it is designed for client-side web enhancement, not server-side automation
Poor fit: screenshot-based or multi-modal understanding, since it uses text-based DOM only

Try page-agent quickly with the demo model

The fastest way to see it working is the one-line integration with the free Demo LLM. Load the script from a CDN tag in your page. The README pins a specific npm version in the URL, so use the exact URL from the README rather than assuming a version.

The demo model is for technical evaluation only. The README says the demo CDN uses a free testing LLM API and that you agree to its terms by using it. Do not put it in production.

To load the script without creating the demo agent automatically, add ?autoInit=false to the script URL. You can then create the agent yourself with new window.PageAgent(...) and your own LLM settings.

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

Install page-agent with npm

For a real application, install the package from npm. The README lists Node.js as a prerequisite but does not specify a version, so check your project's own Node requirement. You also need an LLM API key or a compatible model endpoint.

Import PageAgent from the package and pass it your model settings. The README example uses a model name, a baseURL, an apiKey and a language option. Replace the placeholder API key with your own key and keep it out of public client code where possible.

Prerequisites: Node.js (version not specified in README)
Prerequisites: an LLM API key or a compatible model endpoint

npm install page-agent

Connect your own LLM and run an instruction

Create a PageAgent instance with your model, baseURL, apiKey and language, then call execute with a plain-language instruction. The README example runs the instruction 'Click the login button'.

The README example uses an OpenAI-compatible endpoint URL and a qwen model name. Any compatible endpoint should work the same way, but the README says the project works with most mainstream models and points to a supported models page for details.

model: the model name your endpoint serves
baseURL: the compatible API endpoint
apiKey: your key for that endpoint
language: for example en-US

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: 'YOUR_API_KEY',
    language: 'en-US',
})

await agent.execute('Click the login button')

Use the optional Chrome extension and MCP server

The README describes an optional Chrome extension for multi-page tasks, which extends your web agent's reach across browser tabs. It also mentions an MCP Server (Beta) that lets outside clients control it. Both are separate features documented on the project's docs site.

The core library does not need either. Use them only if your task spans multiple pages or you want an external agent client to drive the browser.

Chrome extension: multi-page tasks across tabs
MCP Server (Beta): control from outside agent clients

Contribute or get help

The project is MIT licensed and accepts contributions. The README points to CONTRIBUTING.md for guidelines and docs/developer-guide.md for local development workflows. It also asks contributors to read a maintainer's note, and it states that contributions generated entirely by bots or AI without substantial human involvement will not be accepted.

For usage questions beyond the README, the README links to the project's documentation site and to a Show and Tell discussion category.

What people use it for

Ship an AI copilot inside your own SaaS product, as described in the README's SaaS AI Copilot use case.
Turn multi-click workflows in ERP, CRM or admin systems into a single sentence.
Make a web app easier to use through natural language, which the README lists as an accessibility use case.
Extend your own web agent across browser tabs with the optional Chrome extension.

Frequently asked questions

Is page-agent free to use?

The project is licensed under the MIT License, according to the README. The demo LLM is a free testing API for technical evaluation only, and the README says you must agree to its terms to use it. Any model you connect yourself is billed by its own provider.

Do I need Python or a headless browser to run page-agent?

No. The README says it needs no browser extension, no Python and no headless browser, because it is just in-page JavaScript.

Does page-agent use screenshots?

No. The README says it uses text-based DOM manipulation with no screenshots and no multi-modal LLMs.

Can I use a local LLM with page-agent?

Yes. The README says it works with most mainstream models, including locally deployed ones, and links to a supported models page.

Can I use page-agent on websites I do not own?

The README says it is designed for client-side web enhancement, not server-side automation. It is intended for pages and apps you control, so check the README and terms before using it elsewhere.

How does page-agent compare to browser-use, Stagehand or Skyvern?

The README says page-agent builds on browser-use's DOM processing and prompt. Its main difference is that it runs inside your page as JavaScript rather than as a separate browser automation process. Compare the three against your own requirements, such as whether you need server-side control or screenshot-based understanding.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose page-agent if you are a developer adding an in-page AI assistant or form-filling helper to a web app you control, and you want it to run client-side with your own model. Pick something else if you need to automate sites you do not own, need screenshot or multi-modal understanding, or want a production-ready hosted LLM with no setup.

Install options & downloads