Page Agent

Page Agent follows a client-side only architecture with a "Bring Your Own Key" (BYOK) model.

Key privacy characteristics:

• No Backend: The software does not include a built-in backend service and does not collect or transmit user data on its own.
• Data Control: All data transmission occurs exclusively between your browser and the LLM provider you configure. You have full control over which provider receives your data.
• Local Execution: For the browser extension (Page Agent Ext), DOM analysis and automation actions are performed locally in your browser.
• Local Storage: Configuration settings (API endpoint, API key, model selection) are stored locally in your browser using chrome.storage.local (or equivalent) and are not synced to any external server.

When you initiate an automation task using the Page Agent browser extension, the following data is transmitted to the LLM API endpoint configured in your settings:

1. Task Instructions: Your natural language commands.
2. Simplified Page Structure: Cleaned HTML of the pages under the extension's control.

Security Note on HTML Cleaning: The HTML cleaning process simplifies the structure for AI readability but does not guarantee the removal of sensitive information (such as visible text, form values, or personal data). Always be mindful of the content on the page before initiating a task.

The @page-agent/mcp server acts as a bridge between an AI agent client (via MCP/stdio) and the Page Agent browser extension (via WebSockets).

Workflow:

1. Initialization: The agent client starts the server using npx @page-agent/mcp via stdio.
2. Server Startup: The server starts an HTTP + WebSocket server on localhost:PORT and opens a local launcher page in your browser.
3. Extension Connection: The launcher page triggers the Page Agent extension to open a hub tab (hub.html?ws=PORT).
4. Task Proxying: The hub tab connects to the WebSocket server. When the agent client calls an MCP tool, the server proxies that task to the hub tab, which then controls the browser via the extension's useAgent logic.

If you discover a security vulnerability, do not report it through public GitHub issues, discussions, or pull requests.

Use GitHub's private vulnerability reporting flow:

1. Navigate to https://github.com/alibaba/page-agent/security/policy.
2. Click Report a vulnerability.

If private reporting is unavailable, you may open a minimal public issue to request a private contact channel, but do not include exploit details in the public issue.

To use Page Agent in your project, install the package using npm:

npm install page-agent

The fastest way to test Page Agent is by including the demo script via jsDelivr. This version uses a free testing LLM API provided by the maintainers.

Note: This is for technical evaluation only. By using it, you agree to the terms and privacy policy.

To prevent the agent from initializing automatically, append ?autoInit=false to the script URL. This allows you to manually instantiate new window.PageAgent(...) with your own LLM configuration.

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

To work on the browser extension located in packages/extension/, use the following commands:

npm run dev:ext    # Start extension development mode
npm run build:ext  # Build the extension

For details on how to integrate with the extension API, refer to packages/extension/docs/extension_api.md.

To develop locally on Page Agent, ensure you meet the following prerequisites and follow the setup steps.

Prerequisites

• OS: macOS, Linux, or WSL
• Node.js: ^22.13 or >=24
• npm: >= 11
• Editor: Must support ts, eslint, and prettier.

Setup Steps

Run the following commands in the repository root to install dependencies and start the development environment:

npm i            # Install dependencies (use `npm ci` to preserve the lockfile)
npm start        # Start the website development server
npm run build    # Build the entire monorepo