alibaba / page-agent

alibaba/page-agent

open_in_new前往仓库

阿里巴巴出品的JavaScript页面内GUI代理，通过自然语言控制网页界面。

项目概览

项目概述

Page Agent 是一个纯 JavaScript 实现的页面内 GUI 代理（in-page GUI agent），允许用户通过自然语言控制网页界面。它由阿里巴巴开源，采用 TypeScript 编写，基于 MIT 许可证发布。Page Agent 的核心优势在于无需浏览器扩展、Python 环境或无头浏览器，只需在网页中引入一段脚本即可为任意网页赋予 AI 代理能力。项目基于 browser-use 的优秀工作构建，专为客户端网页增强设计，而非服务端自动化。

核心功能

  • 轻松集成：无需浏览器扩展、Python 或无头浏览器，纯页面内 JavaScript 即可运行。
  • 基于文本的 DOM 操作：不依赖截图或多模态模型，通过文本方式提取和操作 DOM 结构。
  • 自带 LLM（BYOK）：支持主流大语言模型，包括本地部署的模型（如 Ollama），用户可自由配置模型、API 地址和密钥。
  • 可选 Chrome 扩展：支持跨标签页任务，扩展提供多标签控制、历史记录、任务审批等功能。
  • MCP Server（Beta）：通过 MCP 协议允许外部 Agent 客户端（如 Claude Desktop）控制浏览器。
  • 内置工具系统：提供点击、输入、滚动、选择等常用操作工具，并支持自定义工具扩展。
  • 生命周期钩子：支持在代理执行过程中挂载自定义逻辑。
  • 数据脱敏：可在发送给 LLM 前转换页面内容，保护敏感信息。
  • 多语言支持：界面支持英文和中文。

适用与不适用场景

适用场景：

  • SaaS AI Copilot：为产品快速添加 AI 副驾驶，无需重写后端。
  • 智能表单填写：将多步骤工作流简化为一句自然语言指令，适用于 ERP、CRM 和管理后台。
  • 无障碍增强：通过自然语言、语音指令或屏幕阅读器让网页更易访问。
  • 跨页面 Agent：通过 Chrome 扩展实现跨标签页的自动化任务。
  • MCP 集成：为现有 Agent 客户端增加浏览器控制能力。

不适用场景：

  • 服务端自动化：Page Agent 专为客户端网页增强设计，不适用于服务端自动化。
  • 跨页面导航：核心库仅支持单页应用，无法在页面间导航（需借助扩展）。
  • 视觉识别：依赖 DOM 结构，不支持基于截图的视觉识别。
  • 复杂交互：不支持悬停、拖拽、Canvas 操作等高级交互。

技术架构与依赖

Page Agent 是一个使用 npm workspaces 管理的 monorepo，主要包含以下包：

  • page-agent：主入口，包含内置 UI 面板。
  • @page-agent/core：核心代理逻辑，无 UI。
  • @page-agent/llms：LLM 客户端，支持重试和请求修补。
  • @page-agent/page-controller：DOM 操作和视觉反馈，独立于 LLM。
  • @page-agent/ui：面板和国际化。
  • @page-agent/mcp：MCP 服务器，用于通过扩展控制浏览器。

依赖方面，项目使用 TypeScript、Vite 构建，支持 Zod 校验，并依赖 browser-use 的 DOM 处理组件和提示词。开发环境要求 Node.js ^22.13 或 >=24，npm >=11。

安装与快速开始

一行代码集成（使用免费 Demo LLM）：

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

注意：Demo CDN 使用免费测试 LLM API，仅用于技术评估，使用即表示同意相关条款。可通过 ?autoInit=false 禁用自动初始化。

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: 'zh-CN',
})

await agent.execute('点击登录按钮')

典型使用方法

编程式使用：

const agent = new PageAgent({
    model: 'gpt-5.2',
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'sk-...',
})

await agent.execute('填写表单并提交')

自定义系统提示词：

const agent = new PageAgent({
    // ...
    systemPrompt: '你是一个专注于表单填写的助手。',
})

使用本地模型（Ollama）：

const agent = new PageAgent({
    baseURL: 'http://localhost:11434/v1',
    apiKey: 'NA',
    model: 'qwen3:14b',
})

通过 Chrome 扩展控制多标签页： 安装扩展后，可在侧边栏中管理多个标签页，并下达跨页任务。

通过 MCP 控制浏览器： 使用 @page-agent/mcp 包，配置 MCP 客户端（如 Claude Desktop）连接扩展。

配置与部署要点

  • LLM 配置：必须配置模型名称、API 地址和 API 密钥。对于不需要密钥的部署（如本地模型），可省略 apiKey。
  • 安全注意事项：客户端脚本会内联 API 密钥，分发时需谨慎。建议使用 BYOK 模式，避免使用免费测试 API 处理敏感数据。
  • 扩展配置：扩展的配置（API 端点、密钥、模型）存储在浏览器本地，不同步到云端。
  • MCP 服务器：默认绑定到 localhost，仅允许本地连接。
  • 部署限制：核心库仅支持单页应用，跨页任务需使用扩展。
  • 性能调优：可通过 stepDelay 调整步骤间隔，通过 maxSteps 控制最大步骤数。

限制、风险与许可证

已知限制：

  • 仅支持单页应用，无法跨页面导航（核心库）。
  • 不进行视觉识别，依赖 DOM 结构。
  • 不支持悬停、拖拽、Canvas 操作等复杂交互。
  • 免费测试 API 可能限流、降级或随时停止，不保证可用性。

风险：

  • 使用免费测试 API 时，数据可能经过中国大陆服务器，请遵守当地数据保护法规。
  • 页面内容发送给 LLM 前虽经简化，但不保证敏感信息完全移除，请谨慎使用。
  • 客户端脚本可能暴露 API 密钥，请勿在公开环境中分发。

许可证： MIT License。项目基于 browser-use（MIT License）构建，DOM 处理组件和提示词源自该项目的贡献。

官方链接

信息来源和分析时间

本指南基于 2026 年 7 月 16 日获取的 GitHub 仓库 alibaba/page-agent 的 README、文档和变更日志编写。仓库资料未提供更详细的信息，如完整的 API 参考或贡献指南，请参阅官方文档。