PageAgent

PageAgent 快速入门

一句话卖点：24.2k Star 的阿里巴巴开源项目，31.9KB JavaScript 让 AI 钻进网页内部操控 DOM，比 Python 无头浏览器方案轻 100 倍

产品概述

PageAgent 是阿里巴巴开源的一款纯前端 JavaScript GUI Agent，以 npm 包和 CDN script 标签两种方式分发。它的核心理念是”让 AI 直接住在网页里”——无需浏览器扩展、无需 Python 运行环境、无需无头浏览器，仅靠一段页面内运行的 JS 代码就能让 LLM 理解并操控网页 DOM。

与传统的网页自动化方案（如 Selenium、Playwright、Puppeteer）不同，PageAgent 不依赖截图和视觉模型，而是通过结构化的 DOM 文本表示让 LLM “读懂”网页，再通过 DOM API 直接操作页面元素。这套方案规避了多模态模型的高成本，也避免了截图→OCR→定位的精度损失，同时保持极小的体积（gzip 后仅 31.9KB）。

PageAgent 由阿里巴巴的 Simon（gaomeng1900）主导开发，基于 browser-use 项目的 DOM 处理组件和 prompt 设计思路进行重构，将其从 Python 服务端方案改造为纯前端方案。项目于 2025 年在 GitHub 上开源，目前（2026 年 7 月）已获得 24.2k Stars 和 2.1k Forks，npm 周下载量约 25,516 次，月下载量约 59,233 次。

技术亮点

核心功能

1. 一行代码集成

PageAgent 提供 CDN 和 npm 两种接入方式。最快只需要在 HTML 中加一行 <script> 标签即可激活 AI 操控能力。CDN 版本内置了免费的 Demo LLM 接口（阿里通义千问 Qwen 系列），供技术评估使用。生产环境可替换为自己的 LLM API Key。

<!-- CDN 方式，3 秒接入 -->
<script src="https://cdn.jsdelivr.net/npm/page-agent@1.11.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

npm 安装方式支持更细粒度的配置：

npm install page-agent

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

2. 文本化 DOM 操控

PageAgent 的核心创新在于不需要截图。它将当前页面的 DOM 结构序列化为 LLM 可理解的文本表示，LLM 直接分析 DOM 树来决定下一步操作（点击、输入、滚动等），然后通过 DOM API 执行。这种方法避免了截图方案的两个痛点：多模态模型的额外成本，以及视觉定位的精度问题。

支持的 DOM 操作包括：

• 点击（Click）任意可交互元素
• 文本输入（Type）表单字段
• 滚动（Scroll）页面区域
• 导航（Navigate）页面跳转
• 等待（Wait）元素出现/消失
• 提取（Extract）页面数据

3. 自带 LLM 支持（Bring Your Own LLMs）

PageAgent 不绑定特定 LLM 提供商。它内置了 LLM 抽象层，支持任何兼容 OpenAI API 格式的接口，包括：

• 阿里通义千问（Qwen 系列，内置免费测试 API）
• OpenAI（GPT-4o、GPT-4.1 等）
• Anthropic（Claude 系列）
• DeepSeek
• 其他兼容 OpenAI SDK 的模型

默认 Demo 使用阿里的免费测试 LLM API，适用于技术评估。生产环境建议配置自己的 API Key。

4. Chrome 扩展 — 跨页面 Agent

对于需要在多个标签页之间导航的复杂工作流，PageAgent 提供可选的 Chrome 扩展。扩展赋予了 Agent 跨标签页操作的能力，使其可以：

• 打开新标签页并执行任务
• 在标签页之间传递上下文
• 监控多个页面的状态变化
• 实现端到端的跨站点自动化流程

5. MCP Server（Beta）

PageAgent 还提供了一个 MCP（Model Context Protocol）Server，允许外部 Agent 客户端（如 Claude Desktop、VS Code Agent 等）通过 MCP 协议控制浏览器。这使得 PageAgent 可以成为其他 AI 工具的”浏览器操控后端”。

6. 技术架构

PageAgent 采用 monorepo 架构，包含 8 个包：

• packages/core — 核心 Agent 引擎，DOM 解析和操作调度
• packages/page-agent — 主入口，面向用户的 API
• packages/page-controller — DOM 控制器，页面元素操作
• packages/ui — 内置 UI 组件（聊天面板等）
• packages/llms — LLM 抽象层，多模型适配
• packages/mcp — MCP Server 实现
• packages/extension — Chrome 扩展
• packages/website — 官方文档站点

快速上手

方式一：CDN 一键体验（推荐新手）

在任意 HTML 页面中添加一行标签：

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

页面加载后会自动在右下角弹出一个 AI 对话面板，你可以直接用自然语言指令操控网页。例如：

• “帮我填写这个注册表单”
• “点击页面顶部的登录按钮”
• “提取表格中的所有数据并导出为 CSV”

如果想手动控制 Agent 的初始化时机，添加 ?autoInit=false 参数：

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

然后在代码中手动创建实例：

const agent = new window.PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: 'your-api-key',
})
await agent.execute('你的指令')

方式二：npm 安装（用于生产项目）

npm install page-agent

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',              // 或 gpt-4o、claude-sonnet-4-20250514 等
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: process.env.LLM_API_KEY,
    language: 'zh-CN',                   // 界面语言
})

// 单次任务执行
await agent.execute('找到页面上所有价格并计算总和')

// 持续对话模式
agent.on('response', (msg) => console.log('Agent:', msg))
await agent.chat('帮我找到联系客服的方式')

环境要求

• 浏览器：支持现代 ES2022+ 的浏览器（Chrome 90+、Firefox 90+、Safari 15+、Edge 90+）
• Node.js（仅 npm 开发模式）：^22.22.1 或 >=24
• LLM API：兼容 OpenAI API 格式的任意 LLM 接口
• 无后端依赖：纯前端运行，不需要 Python、Docker 或其他服务端组件

典型应用场景

SaaS AI Copilot

在现有 SaaS 产品中嵌入 AI 操作助手，让用户用自然语言完成复杂操作。PageAgent 只需要一行 <script> 标签，无需后端改造。

示例：在项目管理工具中，用户说”把上周五之前所有未完成的 Issues 移到下个 Sprint”，Agent 自动解析指令→定位元素→执行批量操作。

智能表单填写

将 20 步的点选填表流程压缩为一句自然语言指令。特别适合 ERP、CRM、后台管理系统等表单密集型场景。

示例：在 HR 系统中，“录入张三，男，1990 年出生，本科学历，2020 年入职，技术部高级工程师”→ Agent 逐字段填入。

无障碍访问

通过语音指令或自然语言让残障用户操控任何网页应用。PageAgent 可以配合屏幕阅读器使用，降低操作门槛。

跨页面自动化

配合 Chrome 扩展，Agent 可在多个标签页/站点间完成端到端工作流。

示例：从 CRM 提取客户信息→在邮件平台打开撰写窗口→填入收件人、主题和模板内容→发送。

数据提取与监控

让 Agent 定期提取页面数据、监控价格变化、抓取竞品信息等。

示例：“每小时检查一次这个商品的库存状态，变化时通知我”。

竞品速览

PageAgent 的核心差异化在于彻底去除了服务端依赖。Browser-Use、Playwright、Stagehand 都需要在服务器上运行浏览器实例，而 PageAgent 的 Agent 逻辑就在用户的浏览器中执行，利用用户已经打开的页面，不需要额外的浏览器实例开销。

❓ 常见问题 FAQ

PageAgent 适合哪些网页？

PageAgent 适合任何基于标准 DOM 的网页应用，包括 SPA（React/Vue/Angular）、传统多页面应用、后台管理系统等。对于 Canvas/WebGL 渲染的应用（如游戏、在线设计工具），由于 DOM 结构有限，效果会打折扣。

免费 Demo LLM 有什么限制？

内置的免费测试 LLM API 仅用于技术评估，有速率限制和每日配额。不建议用于生产环境。生产使用请配置自己的 LLM API Key（支持通义千问、OpenAI、Claude 等）。

PageAgent 与 RPA 工具（如 UiPath）有什么区别？

RPA 工具通常需要安装客户端、录制操作流程、编写脚本。PageAgent 是 LLM 驱动的，用户只需用自然语言描述意图，Agent 自动理解并执行。RPA 适合固定流程自动化，PageAgent 适合灵活、非结构化的交互。

PageAgent 需要特殊权限吗？

不需要。PageAgent 完全在网页的 JavaScript 沙箱中运行，遵循同源策略。唯一的限制是无法跨域操作（除非使用 Chrome 扩展模式）。不需要浏览器扩展权限、不需要系统级权限。

数据安全如何保障？

PageAgent 的 JavaScript 代码完全在你的浏览器中运行。DOM 文本是页面本地的，LLM API 调用只发送结构化的 DOM 摘要和用户指令。使用自己的 LLM API Key 时，数据只流经你的 LLM 提供商，不经过 PageAgent 的任何服务器（CDN 只是分发 JS 文件，不收集数据）。

支持移动端吗？

PageAgent 的核心库可以在移动端浏览器中运行，但 UI 面板主要为桌面端设计。移动端的触摸交互和较小的屏幕空间可能影响体验。官方尚未提供专门的移动端适配。

与其他 AI 网页 Agent（如 Claude Computer Use）有什么区别？

Anthropic 的 Computer Use 是操作系统级别的屏幕操控（截图+鼠标键盘模拟），需要在桌面端运行。PageAgent 是网页级的 DOM 操控，直接在浏览器内运行，不需要桌面权限。两者可以互补——Computer Use 用于非 Web 应用，PageAgent 用于 Web 应用。