HyperAgent · 智能体框架与编排

HyperAgent：给浏览器装上 AI 大脑

场景切入：厌倦了爬虫的" brittle script"

想象这样一个场景：产品经理要求你"每天早上 8 点爬取竞品页面上的最新价格"。传统的做法是写 XPath 定位按钮、用 sleep 等待加载——但竞品改一个 class 名，你的脚本就废了。更糟糕的是，很多网站有反爬机制，直接 selenium 裸奔上去不是被拦截就是被弹验证码。

HyperAgent 试图从根本上解决这个问题：不再让人类写死的指令去控制浏览器，而是让 AI 大模型直接理解页面的结构和意图，用自然语言描述任务，AI 自己决定点击哪里、填什么、提取什么。

一句话概括：HyperAgent = Playwright + AI 大模型 + Chrome DevTools Protocol，让浏览器自动化从"脚本"进化到"智能体"。

背景故事：从 Hyperbrowser 到开源 Agent

HyperAgent 的背后是 Hyperbrowser.ai——一个提供大规模无头浏览器的云平台。初创团队发现，开发者对"AI 控制浏览器"的需求远比想象的强烈，但市面上的工具要么太底层（直接操作 CDP），要么太封闭（纯 SaaS 黑盒）。

2025 年 4 月，他们在 GitHub 上开源了 HyperAgent 的核心逻辑，采用 AGPL-3.0 许可（有趣的是 package.json 里又标注了 AGPL-3.0），让开发者可以在本地免费使用完整功能，云端服务则提供规模化能力。截至 2026 年初，项目已积累超过 1400 颗星、172 个 fork，issue 活跃度保持在 25 个左右，发展势头稳健。

HyperAgent Banner 图1：HyperAgent 项目 Banner

核心原理：三种控制模式

HyperAgent 提供了三个层次的浏览器控制 API，设计上层层递进，开发者可以根据任务复杂度自由选择。

第一层：page.perform() — 单步精准操作

这是 HyperAgent 最推荐的日常用法。它的工作原理是：捕获页面的可访问性树（Accessibility Tree），交给 LLM 分析，LLM 输出"要点击哪个元素、执行什么操作"，最后通过 CDP（Chrome DevTools Protocol）执行。

可访问性树是什么？简单说就是浏览器对页面 DOM 结构的一种语义化表达——比原始 HTML 简洁，比截图省 token，而且天然过滤掉了广告 iframe。配合 LLM 的 element ranking 算法，page.perform() 能在单次 LLM 调用内完成"定位→点击"动作，速度快、成本低。

const page = await agent.newPage();
await page.perform("fill email with user@example.com");
await page.perform("fill password with mypassword");
await page.perform("click the login button");

第二层：page.ai() — 多步视觉理解

当任务需要理解页面的视觉布局（比如"点击搜索结果里价格最低的那个"）或者需要多轮推理时，page.ai() 更合适。它默认开启视觉模式：截取页面截图、叠加元素标注框，组成图文混合上下文送给多模态大模型（如 GPT-4o）。

代价是：每次操作需要截图 + 上传 token，成本和延迟都比 page.perform() 高。所以项目文档建议：能用 perform() 就不用 ai()。

await page.ai("search for flights from Rio to LAX from July 16 to July 22");
const res = await page.extract(
  "give me the flight options",
  z.object({
    flights: z.array(z.object({ price: z.number(), departure: z.string() }))
  })
);

第三层：executeTask() — 全自动复杂工作流

最高层 API，只需描述目标，Agent 自动完成多步规划、执行和结果提取，适合"一键完成"的简单脚本场景。

技术架构：七层模块化设计

理解 HyperAgent 的架构，看懂 src/ 目录就够了：

模块	职责	关键文件
`agent/`	运行时核心循环，工具调用编排	`agent/tools/agent.ts`
`cdp/`	Chrome DevTools Protocol 封装，元素解析与动作分发	优先于 Playwright Helper
`context-providers/a11y-dom/`	可访问性树捕获、DOM 快照缓存、视觉叠加生成	核心 DOM 捕获逻辑
`browser-providers/`	浏览器生命周期管理，支持本地/云端两种模式	`LocalBrowserProvider`（Playwright + stealth）
`llm/`	多 LLM 适配器（OpenAI/Anthropic/Gemini/DeepSeek）	`createLLMClient`
`custom-actions/`	自定义动作扩展点	通过 `HyperAgentConfig.customActions` 注册
`cli/`	命令行入口	`src/cli/index.ts`

几个值得注意的技术细节：

Stealth Mode：内置了 anti-bot patch（通过 patchright 实现），能绕过大多数网站的基础反爬检测。
DOM Cache 机制：默认开启 ~1s 的 DOM 快照缓存，useDomCache=true 时复用，避免每次操作都重新解析 DOM。
Action Caching：记录工作流执行路径，下次可直接 replay，跳过 LLM 调用，适合定时任务。
MCP 集成：通过 @modelcontextprotocol/sdk 连接 MCP 服务器，将远程工具（如 Composio）注册为本地 actions，甚至可以把网页数据写入 Google Sheets。

快速上手：npm 一行安装

HyperAgent 本身没有 Docker 支持（不支持一键部署），但安装极简：

npm install @hyperbrowser/agent
# 或
yarn add @hyperbrowser/agent

CLI 模式一行命令搞定：

npx @hyperbrowser/agent -c "Find a route from Miami to New Orleans"

编程模式也只需要几行代码：

import { HyperAgent } from "@hyperbrowser/agent";
const agent = new HyperAgent({ llm: { provider: "openai", model: "gpt-4o" } });
const result = await agent.executeTask("Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results");
console.log(result.output);

依赖项中值得注意的是 patchright（反爬增强版 Playwright）、playwright-core、@anthropic-ai/sdk、openai、@google/genai（Gemini）、zod（输出校验）。

局限与争议

坦率说，HyperAgent 并不是银弹：

需要本地 Chrome/Chromium：无 Docker 支持意味着开发者必须自己在机器上装浏览器，对于 CI/CD 环境不够友好。
反爬对抗有限："Stealth Mode"只能对抗基础检测，有 PayPal 登录验证或 Cloudflare 时依然会触发。
成本考量：page.ai() 每次截图都消耗大量 token，跑大规模任务时成本不容忽视。
npm 包发布 vs 开源代码对齐：package.json 显示版本 1.1.2，但 GitHub 仓库的更新节奏是否能保持一致，需要使用者自己验证。

行业意义：AI Agent 的"手脚"

2025-2026 年是 AI Agent 爆发年。从 AutoGPT 到 MetaGPT，Agent 框架层出不穷，但大多数只解决了"脑子"（推理规划）的问题，缺少可靠的"手脚"（执行能力）。

浏览器是互联网最大众的执行环境——几乎所有 Web 应用最终都在浏览器里运行。HyperAgent 补上了这一环：让 AI Agent 能够可靠地操作真实浏览器环境，而不只是跑跑 Python 脚本。

更值得关注的是 MCP（Model Context Protocol）集成。通过 MCP，HyperAgent 可以把浏览器操作能力暴露给其他 Agent 框架（比如 CrewAI、LangGraph），形成"浏览器操作 Agent + 其他专业 Agent"的协作网络。这个想象空间，远比单个工具要大。

HyperAgent Demo 图2：CLI 模式执行任务演示