概述

Hyperagent 是由 AI 驱动的 Playwright 扩展。告别脆弱的脚本，只需强大的自然语言指令即可完成任务。
如果您只是在寻找可扩展的无头浏览器或爬虫基础设施，请访问 Hyperbrowser 免费开始使用！

在此查看 HyperAgent 文档：https://www.hyperbrowser.ai/docs/hyperagent/introduction

功能

• 🤖 AI 命令：提供简洁的 API，如 page.ai()、page.extract() 和 executeTask()，适用于任何 AI 自动化场景
• ⚡ 回退到常规 Playwright：当不需要 AI 时，可直接使用常规 Playwright
• 🥷 隐身模式 – 内置反机器人补丁，避免被检测
• ☁️ 云端就绪 – 通过 Hyperbrowser 即时扩展至数百个会话
• 🔌 MCP 客户端 – 可连接 Composio 等工具实现完整工作流（例如将网页数据写入 Google Sheets）
• 📼 操作缓存 – 录制并确定性地重放工作流，无需调用 LLM

快速入门

安装

# 使用 npm
npm install @hyperbrowser/agent

# 使用 yarn
yarn add @hyperbrowser/agent

CLI

$ npx @hyperbrowser/agent -c "查找从迈阿密到新奥尔良的路线，并提供详细的路线信息。"

CLI 支持调试选项，或选择使用 Hyperbrowser 而不是本地浏览器：

-d, --debug                       启用调试模式
-c, --command <任务描述>          要执行的命令
--hyperbrowser                    使用 Hyperbrowser 作为浏览器提供商

库

import { HyperAgent } from "@hyperbrowser/agent";
import { z } from "zod";

// 初始化代理
const agent = new HyperAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
  },
});

// 执行任务
const result = await agent.executeTask(
  "导航到 amazon.com，搜索 'laptop'，并提取前 5 条结果的价格"
);
console.log(result.output);

// 使用 page.ai、page.perform 和 page.extract
const page = await agent.newPage();
await page.goto("https://flights.google.com", { waitUntil: "load" });
await page.ai("搜索 7 月 16 日至 22 日从里约热内卢飞往洛杉矶的航班");
await page.perform("点击搜索按钮");
const res = await page.extract(
  "给我航班选项",
  z.object({
    flights: z.array(
      z.object({
        price: z.number(),
        departure: z.string(),
        arrival: z.string(),
      })
    ),
  })
);
console.log(res);

// 清理
await agent.closeAgent();

两种运行模式

HyperAgent 提供两种互补的 API，分别针对不同用例进行了优化：

🎯 page.perform() - 单一细粒度操作

page.aiAction() 已弃用，仍作为别名保留；建议今后优先使用 page.perform()。

适用场景：单一、特定的操作，例如“点击登录”、“填写邮箱 test@example.com”

优势：

• ⚡ 快速 - 使用无障碍树（无需截图）
• 💰 经济 - 每次操作仅需一次 LLM 调用
• 🎯 可靠 - 直接定位并执行元素操作
• 📊 高效 - 基于文本的 DOM 分析，自动过滤广告框架

示例：

const page = await agent.newPage();
await page.goto("https://example.com/login");

// 快速、可靠的单个操作
await page.perform("填写邮箱 user@example.com");
await page.perform("填写密码 mypassword");
await page.perform("点击登录按钮");

🧠 page.ai() - 复杂多步骤任务

适用场景：需要多步骤操作且依赖视觉上下文的复杂流程

优势：

• 🖼️ 视觉理解 - 可使用带有元素叠加的截图
• 🎭 复杂任务 - 自动处理多步骤工作流
• 🧠 上下文感知 - 更好地理解页面布局和元素关系
• 🔄 自适应 - 可根据页面状态调整策略

参数：

• useDomCache (boolean): 重复使用 DOM 快照以提高速度
• enableVisualMode (boolean): 启用截图和叠加层（默认为 false）

示例：

const page = await agent.newPage();
await page.goto("https://flights.google.com");

// 自动处理的复杂多步骤任务
await page.ai("搜索 7 月 16 日从迈阿密飞往新奥尔良的航班", {
  useDomCache: true,
});

🎨 混合使用

结合两种 API 以获得最佳性能：

// 使用 perform 进行快速、可靠的单个操作
await page.perform("点击搜索按钮");
await page.perform("在搜索框中输入 laptop");

// 使用 ai() 处理复杂、多步骤的工作流
await page.ai("筛选价格低于 1000 美元的结果，并按评分排序");

// 提取结构化数据
const products = await page.extract(
  "获取前 5 名产品",
  z.object({
    products: z.array(z.object({ name: z.string(), price: z.number() }))
  })
);

☁️ 云端

您可以通过 Hyperbrowser 的云无头浏览器来扩展 HyperAgent。

1. 从 Hyperbrowser 获取免费 API 密钥
2. 将其添加到环境变量中，命名为 HYPERBROWSER_API_KEY
3. 将 browserProvider 设置为 "Hyperbrowser"

const agent = new HyperAgent({
  browserProvider: "Hyperbrowser",
});

const response = await agent.executeTask(
  "前往 hackernews，列出最近 5 篇文章的标题"
);

console.log(response);
await agent.closeAgent();

使用指南

多页面管理

// 创建并管理多个页面
const page1 = await agent.newPage();
const page2 = await agent.newPage();

// 在特定页面上执行任务
const page1Response = await page1.ai(
  "前往 google.com/travel/explore，并将出发地设置为纽约。然后，返回给我第一个出现的推荐目的地。只返回地点名称。"
);
const page2Response = await page2.ai(
  `我想计划一次去 ${page1Response.output} 的旅行。请推荐一些值得一去的地方。`
);

console.log(page2Response.output);

// 获取所有活动页面
const pages = await agent.getPages();
await agent.closeAgent();

自定义功能

输出模式定义

HyperAgent 可以按照指定的模式提取数据。模式可以在每个任务级别传递。

import { z } from "zod";

const agent = new HyperAgent();
const agentResponse = await agent.executeTask(
  "导航到 imdb.com，搜索‘黑客帝国’，并提取导演、上映年份和评分",
  {
    outputSchema: z.object({
      director: z.string().describe("电影导演的名字"),
      releaseYear: z.number().describe("电影的上映年份"),
      rating: z.string().describe("电影在 IMDb 上的评分"),
    }),
  }
);
console.log(agentResponse.output);
await agent.closeAgent();

{
  "director": "拉娜·沃卓斯基、莉莉·沃卓斯基",
  "releaseYear": 1999,
  "rating": "8.7/10"
}

使用不同的大模型提供商

HyperAgent 支持多种大模型提供商，并提供原生 SDK 以提升性能和可靠性。

// 使用 OpenAI
const agent = new HyperAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
  },
});

// 使用 Anthropic 的 Claude
const agent = new HyperAgent({
  llm: {
    provider: "anthropic",
    model: "claude-sonnet-4-0",
  },
});

// 使用 Google Gemini
const agent = new HyperAgent({
  llm: {
    provider: "gemini",
    model: "gemini-2.5-flash",
  },
});

// 使用 DeepSeek
const agent = new HyperAgent({
  llm: {
    provider: "deepseek",
    model: "deepseek-chat",
  },
});

MCP 支持

HyperAgent 可以作为功能齐全的 MCP 客户端使用。为了获得最佳效果，我们建议使用 gpt-4o 作为您的大模型。

以下是一个从维基百科读取信息，并使用 Composio 的 Google 表格 MCP 将信息插入 Google 表格的示例。完整示例请参见 这里。

const agent = new HyperAgent({
  llm: llm,
  debug: true,
});

await agent.initializeMCPClient({
  servers: [
    {
      command: "npx",
      args: [
        "@composio/mcp@latest",
        "start",
        "--url",
        "https://mcp.composio.dev/googlesheets/...",
      ],
      env: {
        npm_config_yes: "true",
      },
    },
  ],
});

const response = await agent.executeTask(
  "前往 https://en.wikipedia.org/wiki/List_of_U.S._states_and_territories_by_population，获取表格中人口最多的前五州的数据。然后将这些数据插入 Google 表格。你可能需要先检查是否已连接到 Google 表格，如果没有，请先连接，并向我提供登录链接。"
);

console.log(response);
await agent.closeAgent();

自定义操作

可以通过自定义操作扩展 HyperAgent 的功能。自定义操作需要满足以下三个条件：

• type：操作名称，应能描述该操作的内容。
• actionParams：一个 Zod 对象，用于描述该操作可能接收的参数。
• run：一个函数，接受上下文和操作参数，并根据参数生成结果。

以下是一个使用 Exa 进行搜索的示例：

const exaInstance = new Exa(process.env.EXA_API_KEY);

export const RunSearchActionDefinition: AgentActionDefinition = {
  type: "perform_search",
  actionParams: z.object({
    search: z
      .string()
      .describe(
        "您想要搜索的内容查询。请保持查询简洁明了。"
      ),
  }).describe("搜索并返回给定查询的结果。"),
  run: async function (
    ctx: ActionContext,
    params: { search: string }
  ): Promise<ActionOutput> {
    const results = (await exaInstance.search(params.search, {})).results
      .map(
        (res) =>
          `标题: ${res.title} || 链接: ${res.url} || 相关性: ${res.score}`
      )
      .join("\n");

    return {
      success: true,
      message: `成功执行了关于 ${params.search} 的搜索。结果如下：\n${results}`,
    };
  },
};

const agent = new HyperAgent({
  customActions: [RunSearchActionDefinition],
});

const result = await agent.executeTask(
  "搜索今天纽约的新闻"
);

📼 操作缓存

HyperAgent 会在每次 page.ai() 运行时自动记录所有操作，包括 XPath、框架索引和执行细节。这使得无需调用大模型即可进行确定性重放，非常适合回归测试、CI 流水线和成本优化。

工作原理

每次 page.ai() 运行都会生成一个包含所执行操作序列的 actionCache：

const page = await agent.newPage();
const { actionCache } = await page.ai(
  "前往 flights.google.com，搜索从里约热内卢飞往洛杉矶的航班"
);

// actionCache 包含记录的步骤
console.log(actionCache);

缓存条目示例：

{
  "taskId": "86d13abe-b9f3-4ca3-a9bb-bdeddf234cd1",
  "createdAt": "2025-12-06T05:44:52.257Z",
  "status": "completed",
  "steps": [
    {
      "stepIndex": 0,
      "instruction": "点击出发地字段",
      "elementId": "0-138",
      "method": "click",
      "arguments": [],
      "frameIndex": 0,
      "xpath": "/html[1]/body[1]/div[1]/input[1]",
      "actionType": "actElement",
      "success": true
    }
  ]
}

重放缓存的操作

可以使用 runFromActionCache() 重放已记录的会话。它首先尝试基于 XPath 执行（无需调用大模型），只有当页面结构发生变化时才会回退到大模型：

import { ActionCacheOutput } from "@hyperbrowser/agent";
import fs from "fs";

// 加载之前保存的操作缓存
const cache: ActionCacheOutput = JSON.parse(
  fs.readFileSync("action-cache.json", "utf-8")
);

const agent = new HyperAgent();
const page = await agent.newPage();

// 重放缓存的操作
const replay = await page.runFromActionCache(cache, {
  maxXPathRetries: 3,  // 在回退到大模型之前，最多尝试 3 次解析 XPath
  debug: true,
});

console.log(replay);
// {
//   replayId: "...",
//   sourceTaskId: "86d13abe-...",
//   status: "completed",
//   steps: [{ stepIndex: 0, usedXPath: true, fallbackUsed: false, success: true }]
// }

await agent.closeAgent();

生成回放脚本

从操作缓存中生成一个独立的 TypeScript 脚本，以便轻松集成到您的测试套件中：

const { actionCache } = await page.ai("搜索从迈阿密飞往纽约的航班");

// 生成回放脚本
const script = agent.createScriptFromActionCache(actionCache.steps);
console.log(script);

这将生成一个使用类型化辅助方法（如 performClick()、performType() 等）的脚本，可以独立运行。

使用场景

• 回归测试：只需录制一次工作流，在 CI 中无需 LLM 成本即可回放。
• 不稳定测试调试：比较基于 XPath 的回放与 LLM 驱动的执行结果。
• 成本优化：缓存昂贵的多步骤工作流，并以确定性方式回放。
• 工作流模板：保存常用流程（登录、结账等），并在不同环境中回放。

CDP 优先

HyperAgent 原生支持 Chrome 开发者工具协议。元素查找、滚动、输入、框架管理以及截图等操作都通过 CDP 进行，因此每个操作都有精确的坐标、执行上下文和浏览器事件。这使得自定义命令更加灵活，并能深入跟踪嵌套 iframe。

HyperAgent 可与 Playwright 无缝集成，您仍然可以使用熟悉的命令，同时这些操作会充分利用原生 CDP 协议，实现快速定位和高级 iframe 跟踪。

主要特性：

• 自动广告过滤：自动过滤广告和跟踪 iframe，保持上下文干净。
• 深度 iframe 支持：跨嵌套和跨源 iframe（OOPIF）的跟踪。
• 精确坐标：操作使用精确的 CDP 坐标，确保可靠性。

请注意，CDP 仍处于实验阶段，稳定性无法保证。如果您希望代理使用 Playwright 的原生定位器/操作，请在创建代理时设置 cdpActions: false，它将自动回退到 Playwright 的默认行为。

CDP 层仍在不断演进——预计会有快速的改进（但也可能偶尔出现一些问题）。如果遇到特殊情况，您可以为该工作流关闭 CDP 功能，并向我们提交 bug 报告。

贡献

我们欢迎对 Hyperagent 的贡献！以下是您可以帮助的方式：

1. 克隆仓库并创建分支。
2. 创建您的功能分支（git checkout -b feature/AmazingFeature）。
3. 提交更改（git commit -m '添加 AmazingFeature'）。
4. 推送到分支（git push origin feature/AmazingFeature）。
5. 打开一个 Pull Request。

支持

• 📚 文档
• 💬 Discord 社区
• 🐛 问题追踪
• 📧 邮件支持

HyperAgent 快速上手指南

HyperAgent 是一款由 AI 大语言模型（LLM）驱动的智能浏览器自动化工具。它基于 Playwright 构建，允许开发者使用自然语言命令控制浏览器，无需编写脆弱的选择器脚本，同时保留了原生 Playwright 的高性能与灵活性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议版本 v18 或更高。
• 包管理器: npm, yarn, 或 pnpm。
• LLM API Key: 您需要拥有支持的 LLM 提供商 API Key（如 OpenAI, Anthropic, Google Gemini, DeepSeek 等）。
  • 注：国内开发者可使用 DeepSeek 或符合网络环境的其他模型提供商。
• 环境变量: 确保在终端中配置好对应的 API Key（例如 OPENAI_API_KEY 或 DEEPSEEK_API_KEY）。

安装步骤

通过 npm 或 yarn 安装 HyperAgent 核心包：

# 使用 npm
npm install @hyperbrowser/agent

# 使用 yarn
yarn add @hyperbrowser/agent

提示：如果在国内安装速度较慢，可配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

基本使用

HyperAgent 提供两种主要使用方式：命令行工具 (CLI) 和 TypeScript/JavaScript 库。

1. 命令行快速体验 (CLI)

无需编写代码，直接在终端运行自然语言任务：

npx @hyperbrowser/agent -c "Find a route from Miami to New Orleans, and provide the detailed route information."

常用参数：

• -c, --command: 要执行的任务描述。
• -d, --debug: 开启调试模式。
• --hyperbrowser: 使用 Hyperbrowser 云服务而非本地浏览器。

2. 代码集成 (Library)

以下是使用 TypeScript 进行初始化和执行任务的最小化示例：

import { HyperAgent } from "@hyperbrowser/agent";
import { z } from "zod";

// 1. 初始化 Agent (以 OpenAI 为例，也可替换为 deepseek, anthropic 等)
const agent = new HyperAgent({
  llm: {
    provider: "openai", // 或 "deepseek", "anthropic", "gemini"
    model: "gpt-4o",
  },
});

// 2. 执行简单任务
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);

// 3. 高级用法：混合使用精确操作与 AI 意图理解
const page = await agent.newPage();
await page.goto("https://flights.google.com", { waitUntil: "load" });

// 使用自然语言执行复杂搜索
await page.ai("search for flights from Rio to LAX from July 16 to July 22");

// 使用精确指令点击按钮 (更快、更稳定)
await page.perform("click the search button");

// 结构化提取数据
const res = await page.extract(
  "give me the flight options",
  z.object({
    flights: z.array(
      z.object({
        price: z.number(),
        departure: z.string(),
        arrival: z.string(),
      })
    ),
  })
);
console.log(res);

// 4. 清理资源
await agent.closeAgent();

核心 API 说明

• page.ai(): 适用于复杂的多步骤工作流。它能理解视觉上下文，自动处理多个操作步骤。
• page.perform(): 适用于单一的颗粒化动作（如“点击登录”、“填写邮箱”）。基于无障碍树执行，速度快且成本低。
• page.extract(): 配合 Zod Schema 使用，从页面提取结构化数据。

云端扩展 (可选)

若需大规模并发或避免本地环境配置问题，可接入 Hyperbrowser 云服务：

1. 在 Hyperbrowser 获取免费 API Key。
2. 设置环境变量 HYPERBROWSER_API_KEY。
3. 初始化时指定 browserProvider: "Hyperbrowser"。

const agent = new HyperAgent({
  browserProvider: "Hyperbrowser",
});
// 后续用法与本地上完全一致