Page Agent: an in-page GUI agent that drives the DOM as text

The problem Page Agent addresses: agents that live in the page, not next to it

Most browser automation assumes the agent sits outside the page. It launches a browser, takes screenshots, and clicks at coordinates. That model needs a runtime, a driver, and often a vision-capable model. Page Agent inverts the arrangement. The README describes it as "the GUI Agent Living in Your Webpage" and says one script gives any web page its own AI agent. Integration requires no browser extension, no Python, and no headless browser. Everything happens inside the page. The audience is therefore not the person scraping a competitor's site. It is the team that owns a web application and wants to add a natural-language layer on top of it. The README lists SaaS AI copilots, smart form filling for ERP, CRM and admin systems, accessibility through voice commands and screen readers, multi-page tasks via the Chrome extension, and MCP clients that control the browser. The common thread is that you control the page the agent operates on. That constraint shapes almost every other design decision in the project.

Text-based DOM manipulation instead of screenshots

The mechanism the README emphasises is that Page Agent works on the DOM as text. It states plainly: no screenshots, no multi-modal LLMs or special permissions needed. The practical consequence is that the model receives a textual representation of the interactive elements in the page and returns actions against them, rather than receiving a rendered image and returning pixel coordinates. This removes the requirement for a vision model and for the screen-capture permissions that come with one. It also means the agent's accuracy depends on how well your markup exposes intent, which is a different failure surface from a screenshot pipeline. The README's acknowledgements section states that DOM processing components and the prompt are derived from browser-use, the MIT-licensed project by Gregor Zunic, and reproduces the copyright notice. So the DOM-to-text extraction and prompting strategy are not invented here; they are adapted from an existing web automation project. The README does not describe the exact serialisation format, the token budget, or how elements are ranked before being sent to the model. Those details live in the linked documentation, not in the repository README, and I cannot confirm them from the supplied material.

Bring your own model: the configuration surface

Page Agent does not ship a model. The README says it works with most mainstream models, including locally deployed ones, and points to a supported models page. The npm example shows the constructor taking four options: model, baseURL, apiKey and language. In the example those are set to 'qwen3.5-plus', a DashScope compatible-mode endpoint, a placeholder key, and 'en-US'. The execute method then takes a natural-language instruction such as 'Click the login button' and is awaited. That shape implies an OpenAI-compatible chat endpoint behind baseURL, though the README does not state the protocol contract explicitly. The language option suggests the agent's own prompts and outputs are localised, which matters if the interface text and the instruction language differ. One detail worth noting for anyone reading the badges: the bundle size badge is labelled as excluding the Zod peer dependency, so a real deployment carries Zod on top of whatever the minified and gzipped figure shows. The README does not give a numeric size in the body text, so I will not quote one.

Getting it running: the two paths the README documents

There are two integration paths. The fastest is a single script tag pointing at the IIFE build on jsDelivr, pinned to version 1.12.4, with a crossorigin attribute. The README also gives a China CDN mirror on registry.npmmirror.com for the same file. That demo build auto-creates an agent backed by a free testing LLM API. The README carries a warning directly under the snippet: for technical evaluation only, with terms linked in docs/terms-and-privacy.md. It also documents an escape hatch: appending ?autoInit=false to the script URL loads the code without creating the demo agent, after which you construct one yourself with new window.PageAgent(...) and your own model credentials. The second path is npm install page-agent, followed by an ES import of PageAgent and the constructor call shown above. The repository also ships a Chrome extension, listed on the Chrome Web Store, for multi-page tasks, and an MCP server marked Beta that lets outside agent clients drive the browser. Both are separate from the core library. Contributing is documented in CONTRIBUTING.md and docs/developer-guide.md, and the README states that contributions generated entirely by bots or AI without substantial human involvement will not be accepted.

Where Page Agent is the wrong tool

The README is unusually direct about the boundary: PageAgent is designed for client-side web enhancement, not server-side automation. That single sentence rules out a large class of uses. If you need to drive a site you do not own, run unattended jobs in CI, or operate across many origins, this is the wrong layer, because the agent runs inside one page's JavaScript context and is subject to that page's origin, CSP and lifecycle. Tab reloads, client-side navigation and cross-origin frames are not addressed in the README at all. The multi-page story is delegated to the optional Chrome extension, which means the core library alone does not solve it. There is also a cost model question the README does not answer: every instruction becomes at least one model call, and the DOM text sent per step is not quantified. For a long form-filling workflow, that is a per-interaction expense the adopter has to measure. Finally, the demo CDN path uses a shared free testing API with its own terms, so it is a way to evaluate the library, not a way to ship it.

How it differs from browser-use, the project it credits

The README's acknowledgements name browser-use as the upstream for the DOM processing components and the prompt, and reproduce its MIT notice. The difference in approach is stated in the same section: Page Agent is for client-side web enhancement, not server-side automation. browser-use, as described in that acknowledgement, is a web automation project whose DOM interaction patterns were adapted here. The architectural split follows from that. A server-side automation framework owns the browser process, so it can open tabs, manage sessions and survive navigation. Page Agent is a script inside a page you already control, so it inherits the page's constraints and gains the ability to be dropped into a product without a backend rewrite, which is the phrasing the README uses for the SaaS copilot case. If your requirement is orchestrating browsers you do not own, the upstream project's model fits better. If your requirement is adding a copilot to your own application, the in-page model is the shorter path.

Maintenance, releases and what the MIT licence means here

The repository is not archived and the last push recorded is 2026-09-09. The three most recent releases are v1.12.4 on 2026-09-06, v1.12.3 the day before, and v1.12.2 on 2026-07-16, which suggests a burst of patch work in early September after a quieter July. The licence is MIT, and the README carries a separate acknowledgement block for browser-use under the same licence. MIT is permissive, so redistribution and modification inside a commercial product are permitted subject to the notice requirements; the browser-use copyright notice reproduced in the README is part of that picture, and I am not giving legal advice on how to satisfy it. The upgrade cost that matters here is not the library itself but the model layer. Because Page Agent does not pin you to a provider, a model swap is a change to the model, baseURL and apiKey options rather than a code rewrite, which is a genuine advantage. The counterweight is that prompt behaviour derived from browser-use may shift between releases, and the README's own note about AI-generated contributions suggests the maintainers are deliberately keeping the human review bar high, which tends to mean slower merges for outside contributors.

Editorial conclusion

Adopt Page Agent if you ship a web application and want a natural-language layer over your own interface without a browser extension, a Python runtime or a headless browser, and if your LLM endpoint is compatible with the OpenAI-style baseURL and apiKey configuration shown in the README. Do not adopt it for unattended server-side automation or cross-origin scraping; the project states it is designed for client-side web enhancement, and the multi-page case is pushed to the separate Chrome extension. Before committing, verify three things: that your target model is listed on the supported models page, that your CSP and bundle budget tolerate an in-page agent loop, and that your use case survives the demo CDN warning, which marks the free testing LLM API as being for technical evaluation only.

Official sources

1. alibaba/page-agent on GitHub
2. License: MIT
3. Project website
4. README
5. Releases