🟢 Beginner–Intermediate ⚙️ Type: In-Page AI Copilot / DOM Agent 💸 Free & Open Source (MIT) ⭐ 18,000+ GitHub Stars
What is Page-Agent?
Page-Agent is a groundbreaking open-source JavaScript library developed by Alibaba. It flips the standard paradigm of web automation entirely on its head. Most browser AI agents (like browser-use or Puppeteer scripts) operate from the outside in—using headless browsers, Python backends, and heavy visual scraping to navigate pages.
Page-Agent works from the inside out. It is a lightweight JS library that you embed directly into your web application’s HTML. The AI lives inside the live DOM alongside your users. When a user gives a natural language command (e.g., “Fill out this expense report for my trip to London and submit it”), Page-Agent instantly dehydrates the visible DOM into highly optimized text, feeds it to an LLM, and then programmatically dispatches native browser events (clicks, typing) to execute the workflow.
There are no screenshots, no OCR, and no heavy Vision-Language Models required. Because it processes text representations of the DOM, it acts almost instantaneously while consuming a fraction of the token costs associated with multimodal visual agents.
Who is it for?
- SaaS Developers who want to ship an AI copilot inside their product in minutes without rewriting their backend infrastructure.
- Enterprise IT Admins managing heavy ERP or CRM tools. They can deploy Page-Agent so operators can bypass 30-click form-filling workflows using a single sentence.
- Accessibility Experts looking to make web applications entirely navigable through natural language or voice commands, leveraging the same underlying DOM structure that screen readers use.
- Automation Builders who want to securely automate their own workflows without relying on fragile external browser extensions or costly third-party RPA services.
What makes it special?
- Zero Infrastructure — It is a pure front-end solution. You just add the NPM package or drop a CDN script tag into your HTML and connect your API key. There is no server or Python required.
- Bring Your Own LLM (BYOLLM) — You are not locked into Alibaba’s ecosystem. You can configure Page-Agent to use OpenAI’s GPT-4o, Anthropic’s Claude, Qwen, Mistral, or even a local Ollama instance depending on your privacy requirements.
- Incredibly Cheap to Run — Because it reads the DOM as compact text rather than taking massive screenshots of the page, the LLM token consumption is incredibly low compared to vision-based agents.
- MCP Server (Beta) — While designed for single-page embedded use, the project now includes a Model Context Protocol (MCP) server and a Chrome extension, allowing external agents to drive the browser across multiple tabs.
Requirements before you start
Integrating Page-Agent is intentionally simple and requires almost no prerequisites:
- A Web Project — Any modern web application, static HTML site, or dashboard.
- Node.js & NPM (Optional) — If you are building a modern React/Vue app, you will install it via NPM. Otherwise, a standard CDN script tag works perfectly.
- An LLM API Key — An active API key from OpenAI, Anthropic, or an OpenAI-compatible endpoint.
Step-by-step installation
You can deploy Page-Agent into your project using two primary methods depending on your environment.
Method 1 — The CDN Quick Start (One Line of Code)
If you just want to test it immediately, add this single script tag to the <head> of any HTML page:
<script src="https://cdn.jsdelivr.net/npm/page-agent@1.10.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>(Note: The demo script uses Alibaba’s free testing LLM API. Once you are ready for production, you should switch to the NPM installation and provide your own API keys.)
Method 2 — NPM Installation (For Production Apps)
In your modern JavaScript/TypeScript project, install the package via your terminal:
npm install page-agentNext, instantiate the agent in your frontend code and configure it with your preferred LLM (we strongly recommend loading your API key from environment variables on the backend to keep it secure):
import { PageAgent } from 'page-agent'
const agent = new PageAgent({
model: 'gpt-4o',
baseURL: 'https://api.openai.com/v1',
apiKey: process.env.VITE_LLM_API_KEY,
language: 'en-US',
})
// Trigger an action via code, or let the built-in UI handle user input
await agent.execute('Fill out the checkout form with John Doe and click Submit')
Step 3 — Customizing Data Masking (Optional but Recommended)
Since the agent sends DOM text to an LLM, you should protect sensitive user data. You can configure data masking rules so that passwords, credit cards, or internal IDs are scrambled before the context leaves the browser:
Review the Data Masking section in the official docs to set up regex patterns that automatically sanitize the DOM state.
💡 Pro-Tip: Bypassing Anti-Bot Protections
Because Page-Agent interacts dynamically with live DOM elements, target websites (especially e-commerce, social media, or travel sites) will often detect the automated behavior and block your browser via Cloudflare or Datadome.
To successfully run Page-Agent on strict websites, you need to route the headless browser through a high-trust residential IP. We use Proxy-Seller for this exact purpose because their IPs look like real human traffic. Don’t forget to apply code GLOBALAI15 at checkout to save 15%.
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
| Agent cannot click elements hidden in deeply nested iFrames or Shadow DOMs | Because Page-Agent lives in the primary document context, cross-origin security policies prevent it from reading or interacting with content isolated in external iFrames. | There is no simple bypass for strict cross-origin iFrames. For complex Shadow DOM structures, ensure you are passing the correct configuration flags to allow the agent’s query selectors to pierce the shadow boundary. |
| Token Limit Exceeded (Context Window Too Large) | The webpage has thousands of interactive elements (like a massive unpaginated data table), resulting in a dehydrated DOM text string that exceeds your chosen LLM’s maximum input size. | Implement pagination in your UI, or configure Page-Agent to ignore specific complex container IDs that the user does not need the AI to interact with. |
| API Keys Exposed in Browser Console | You hardcoded your Anthropic or OpenAI API key directly into your client-side JavaScript. | Never ship a bare API key to the frontend in a public application. You should route the LLM API calls through your own secure backend proxy server, setting the baseURL in Page-Agent to point to your proxy instead. |
Free vs Paid comparison
| Feature | Page-Agent (Open Source) | Traditional Browser Automation (e.g., Browser-Use) |
|---|---|---|
| Deployment Scope | 🟢 Embedded directly in the web app | 🔴 Requires external scripts & headless browsers |
| Token Costs & Latency | 🟢 Very Low (Text-based DOM parsing) | 🔴 High (Screenshot vision models) |
| Multi-Tab Control | ⚠️ Requires installing the optional Chrome extension | ✅ Native capability |
| Target User | ✅ End-users navigating an existing SaaS interface | ✅ Developers scraping data or automating testing |
Bottom line: Page-Agent is a brilliant architectural shift. By moving the agent logic directly into the client-side JavaScript, Alibaba has created the fastest, cheapest way for developers to add an AI Copilot to their own platforms. While external tools like
browser-useare better for personal automation and scraping across the wild internet, Page-Agent is the absolute best choice if you actually own the application and want your users to interact with it via natural language.
Alternatives — 3 similar tools
1. Browser-Use
The definitive open-source standard for external web automation. Unlike Page-Agent, which lives inside the page, browser-use is a Python library that drives a headless browser using Playwright and Vision-Language Models. It is far more robust for navigating complex, unknown websites across multiple tabs, but it is too heavy to embed inside a SaaS product for end-users.
🔗 github.com/browser-use/browser-use
2. Skyvern
An incredible open-source platform specifically designed for automating complex, multi-step workflows on external websites (like ordering products or filling out government forms). It provides a full UI dashboard to manage agent tasks, making it ideal for large-scale enterprise automation rather than client-side UX enhancement.
🔗 github.com/Skyvern-AI/skyvern
3. Stagehand
A modern web-browsing API framework built specifically for Node.js developers. Like browser-use, it controls the browser from the outside, but it is heavily optimized for developers who want to write resilient scraping and interaction scripts in TypeScript rather than relying on brittle CSS selectors.
🔗 github.com/browserbase/stagehand
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce