一句话搞定亚马逊比价、IMDb 信息提取！HyperAgent：AI 驱动的 Playwright 增强工具实测

在现代开发中，浏览器自动化场景日益复杂，传统脚本因页面结构变化频繁而变得脆弱。HyperAgent 作为一款基于 Playwright 增强的 AI 浏览器自动化工具，通过 LLM（大语言模型）能力实现了自然语言驱动的自动化操作，同时兼容原生 Playwright 功能，兼顾灵活性与稳定性。本文将从环境准备、基础使用、进阶功能到云部署，全面讲解 HyperAgent 的实操流程，帮助开发者快速上手并落地自动化需求。

一、环境准备：搭建基础运行环境

在使用 HyperAgent 前，需完成本地开发环境的配置，确保依赖包与工具链正常工作。

1.1 系统与依赖要求

• • 操作系统：支持 Windows、macOS、Linux（64 位系统，推荐 Ubuntu 20.04+/macOS 12+/Windows 10+）
• • Node.js 版本：v16.0.0 及以上（建议使用 v18 LTS 版本，避免依赖兼容性问题）
• • 包管理器：npm（v8+）或 yarn（v1.22+）
• • 可选依赖：Git（用于克隆示例代码）、OpenAI/Anthropic API 密钥（用于 LLM 功能）

1.2 安装 HyperAgent 核心包

通过 npm 或 yarn 直接安装官方包，命令如下：

# 使用npm安装
npm install @hyperbrowser/agent --save
# 使用yarn安装（推荐，依赖安装更稳定）
yarn add @hyperbrowser/agent

1.3 配置 LLM API 密钥

HyperAgent 依赖 LLM 实现 AI 指令解析，需提前获取对应 API 密钥并配置环境变量：

• • OpenAI（推荐 gpt-4o）：从OpenAI 控制台获取 API 密钥，设置为OPENAI_API_KEY
• • Anthropic Claude：从Anthropic 控制台获取密钥，设置为ANTHROPIC_API_KEY

环境变量配置方式：

• • Windows（命令提示符）：

set OPENAI_API_KEY=your-api-key-here

• • macOS/Linux（终端）：

export OPENAI_API_KEY=your-api-key-here

• • 长期配置：将上述命令添加到~/.bashrc（Linux）、~/.zshrc（macOS）或 Windows 的系统环境变量中。

二、基础使用：快速实现自动化任务

HyperAgent 提供两种核心使用方式 ——CLI（命令行）和代码库，适用于不同场景。以下通过实际案例演示基础功能。

2.1 CLI 方式：零代码快速执行任务

CLI 模式适合简单的一次性任务，无需编写代码，直接通过命令行输入自然语言指令即可。

2.1.1 基本语法

npx @hyperbrowser/agent -c "你的自动化任务描述" [可选参数]

2.1.2 示例 1：查询航班信息

# 指令：查询迈阿密到新奥尔良的航线详情
npx @hyperbrowser/agent -c "Find a route from Miami to New Orleans, and provide the detailed route information."

2.1.3 示例 2：开启调试模式

若需查看自动化过程（如浏览器界面、日志），添加-d参数开启调试：

npx @hyperbrowser/agent -d -c "Navigate to amazon.com, search for 'laptop', and show the first 3 results."

2.1.4 核心参数说明

2.2 代码库方式：灵活实现复杂逻辑

对于多步骤、需自定义逻辑的任务（如数据提取、多页面管理），推荐使用代码库模式，通过 JavaScript/TypeScript 编写脚本。

2.2.1 示例 1：亚马逊商品价格提取

需求：访问亚马逊官网，搜索 “笔记本电脑”，提取前 5 个结果的价格并打印。

// 引入HyperAgent及依赖
import { HyperAgent } from "@hyperbrowser/agent";
import { ChatOpenAI } from "@langchain/openai";
// 初始化Agent（配置LLM）
const agent = new HyperAgent({
 llm: new ChatOpenAI({
   openAIApiKey: process.env.OPENAI_API_KEY, // 从环境变量读取API密钥
   modelName: "gpt-4o", // 使用gpt-4o模型（推荐，解析精度更高）
 }),
});

// 执行自动化任务
async function extractAmazonLaptopPrices() {
 try {
   const result = await agent.executeTask(
     "Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results"
   );
   // 打印提取结果
   console.log("亚马逊笔记本价格（前5条）：");
   console.log(result.output);
 } catch (error) {
   console.error("任务执行失败：", error);
 } finally {
   // 关闭Agent，释放资源
   await agent.closeAgent();
 }
}

// 调用函数

extractAmazonLaptopPrices();

2.2.2 示例 2：结构化数据提取（使用 Zod Schema）

需求：访问 IMDb 官网，搜索《黑客帝国》，提取导演、上映年份、评分（指定数据格式）。

import { HyperAgent } from "@hyperbrowser/agent";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod"; // 用于定义数据 schema
async function extractMovieInfo() {
 const agent = new HyperAgent({
   llm: new ChatOpenAI({
     openAIApiKey: process.env.OPENAI_API_KEY,
     modelName: "gpt-4o",
   }),
 });
 try {
   // 定义输出数据的 schema（强制结构化）
   const movieSchema = z.object({
     director: z.string().describe("电影导演姓名，多个导演用逗号分隔"),
     releaseYear: z.number().describe("电影上映年份，仅数字"),
     rating: z.string().describe("IMDb评分，格式如'8.7/10'"),
   });
   // 执行任务并指定 schema
   const response = await agent.executeTask(
     "Navigate to imdb.com, search for 'The Matrix', and extract the required info",
     { outputSchema: movieSchema }
   );
   // 打印结构化结果
   console.log("《黑客帝国》信息：");
   console.log(JSON.stringify(response.output, null, 2));
 } catch (error) {
   console.error("提取失败：", error);
 } finally {
   await agent.closeAgent();
 }
}

extractMovieInfo();

2.2.3 核心 API 说明

三、进阶功能：解锁复杂自动化场景

HyperAgent 提供多页面管理、自定义 LLM、MCP 工具集成等进阶功能，满足企业级自动化需求。

3.1 多页面管理：同时操作多个浏览器页面

需求：创建两个页面，分别获取 “纽约推荐旅行目的地” 和 “该目的地的景点推荐”。

import { HyperAgent } from "@hyperbrowser/agent";
import { ChatOpenAI } from "@langchain/openai";
async function multiPageDemo() {
 const agent = new HyperAgent({
   llm: new ChatOpenAI({
     openAIApiKey: process.env.OPENAI_API_KEY,
     modelName: "gpt-4o",
   }),
 });
 try {
   // 创建两个独立页面
   const page1 = await agent.newPage();
   const page2 = await agent.newPage();
   // 页面1：获取纽约推荐目的地
   const destinationRes = await page1.ai(
     "Go to google.com/travel/explore, set starting location to New York, return only the first recommended destination name"
   );
   const destination = destinationRes.output;
   console.log("纽约推荐目的地：", destination);
   // 页面2：基于目的地推荐景点
   const attractionRes = await page2.ai(
     `Recommend 3 must-visit attractions in ${destination}, return name and brief intro`
   );
   console.log(`n${destination}景点推荐：`);
   console.log(attractionRes.output);
   // 获取所有活跃页面（可选）
   const activePages = await agent.getPages();
   console.log(`n当前活跃页面数量：${activePages.length}`);
 } catch (error) {
   console.error("多页面任务失败：", error);
 } finally {
   await agent.closeAgent();
 }
}

multiPageDemo();

3.2 自定义 LLM 提供商：切换 Anthropic Claude

除 OpenAI 外，HyperAgent 支持所有 Langchain 兼容的 LLM，以下以 Anthropic Claude 为例：

import { HyperAgent } from "@hyperbrowser/agent";
import { ChatAnthropic } from "@langchain/anthropic";
const agent = new HyperAgent({
 llm: new ChatAnthropic({
   anthropicApiKey: process.env.ANTHROPIC_API_KEY, // 配置Claude密钥
   modelName: "claude-3-7-sonnet-latest", // 使用Claude 3 Sonnet模型
 }),
});

// 后续任务执行逻辑与OpenAI示例一致

3.3 MCP 工具集成：连接外部应用（以 Google Sheets 为例）

HyperAgent 可作为 MCP（工具调用协议）客户端，集成第三方工具（如 Google Sheets、Exa 搜索）。以下示例实现 “从维基百科提取美国人口 Top5 州数据，并写入 Google Sheets”。

3.3.1 前置准备

1. 1. 安装 MCP 依赖：npm install @composio/mcp
2. 2. 获取 Composio Google Sheets MCP 链接（从Composio 控制台创建）
3. 3. 配置环境变量：export COMPOSIO_API_KEY=your-composio-key

3.3.2 代码实现

import { HyperAgent } from "@hyperbrowser/agent";
import { ChatOpenAI } from "@langchain/openai";
async function wikiToGoogleSheets() {
 const agent = new HyperAgent({
   llm: new ChatOpenAI({
     openAIApiKey: process.env.OPENAI_API_KEY,
     modelName: "gpt-4o", // MCP功能推荐使用gpt-4o
   }),
   debug: true, // 开启调试，查看工具调用日志
 });
 try {
   // 初始化MCP客户端（连接Google Sheets工具）
   await agent.initializeMCPClient({
     servers: [
       {
         command: "npx",
         args: [
           "@composio/mcp@latest",
           "start",
           "--url",
           "https://mcp.composio.dev/googlesheets/your-mcp-url", // 替换为你的MCP链接
         ],
         env: { npm_config_yes: "true" }, // 自动确认npm安装
       },
     ],
   });
   // 执行任务：提取维基数据并写入Google Sheets
   const response = await agent.executeTask(
     "Go to https://en.wikipedia.org/wiki/List_of_U.S._states_and_territories_by_population, extract data of top 5 most populous states (state name, population). Then insert the data into Google Sheets. If no Google Sheets connection exists, present the sign-in link first."
   );
   console.log("任务结果：", response.output);
 } catch (error) {
   console.error("MCP任务失败：", error);
 } finally {
   await agent.closeAgent();
 }
}

wikiToGoogleSheets();

四、部署拓展：从本地到云环境

当需要大规模执行自动化任务（如批量数据采集、多地区测试）时，本地浏览器资源有限，可通过 Hyperbrowser 云服务实现弹性扩展。

4.1 Hyperbrowser 云服务部署

Hyperbrowser 是官方提供的云浏览器平台，支持数百个并发会话，无需本地部署浏览器，步骤如下：

4.1.1 获取 Hyperbrowser API 密钥

1. 1. 访问Hyperbrowser 官网，注册并登录
2. 2. 进入 “API Keys” 页面，创建新密钥，保存为HYPERBROWSER_API_KEY

4.1.2 配置云浏览器提供商

在初始化 Agent 时，指定browserProvider: "Hyperbrowser"，即可使用云浏览器：

import { HyperAgent } from "@hyperbrowser/agent";
import { ChatOpenAI } from "@langchain/openai";
async function cloudBrowserDemo() {
 // 初始化云Agent
 const agent = new HyperAgent({
   llm: new ChatOpenAI({
     openAIApiKey: process.env.OPENAI_API_KEY,
     modelName: "gpt-4o",
   }),
   browserProvider: "Hyperbrowser", // 使用云浏览器
   hyperbrowserApiKey: process.env.HYPERBROWSER_API_KEY, // 配置云服务密钥
 });
 try {
   // 执行任务（云环境中运行，本地无浏览器窗口）
   const response = await agent.executeTask(
     "Go to hackernews, list the 5 most recent article titles and their URLs"
   );
   console.log("HackerNews最新文章：");
   console.log(response.output);
 } catch (error) {
   console.error("云任务失败：", error);
 } finally {
   await agent.closeAgent();
 }
}

cloudBrowserDemo();

4.2 企业级部署建议

1. 1. 密钥管理：避免硬编码 API 密钥，使用 Kubernetes Secrets、AWS Secrets Manager 等工具管理
2. 2. 资源控制：通过 Hyperbrowser 控制台设置并发会话数，避免超出配额
3. 3. 日志监控：开启debug: true，并集成 ELK Stack（Elasticsearch、Logstash、Kibana）监控任务执行日志
4. 4. 容错处理：添加任务重试逻辑（如try/catch+ 延时重试），应对网络波动或页面加载延迟
5. 5. 合规性：确保自动化任务符合目标网站的robots.txt规则，避免触发反爬机制

五、常见问题与解决方案

5.1 问题 1：LLM API 调用失败

• • 可能原因：API 密钥无效、余额不足、网络代理问题
• • 解决方案：

1. 1. 验证 API 密钥是否正确（从官方控制台重新生成）
2. 2. 检查 OpenAI/Anthropic 账户余额（避免免费额度耗尽）
3. 3. 若使用代理，配置环境变量HTTP_PROXY/HTTPS_PROXY

5.2 问题 2：浏览器启动失败（本地模式）

• • 可能原因：Playwright 浏览器未安装、权限不足
• • 解决方案：

1. 1. 手动安装 Playwright 浏览器：npx playwright install
2. 2. 以管理员 /root 权限运行脚本（Windows 需右键 “以管理员身份运行” 终端）

5.3 问题 3：云浏览器连接超时

• • 可能原因：Hyperbrowser API 密钥错误、网络防火墙拦截
• • 解决方案：

1. 1. 确认HYPERBROWSER_API_KEY正确（从官网重新获取）
2. 2. 检查防火墙是否允许访问hyperbrowser.ai域名（开放 443 端口）

5.4 问题 4：数据提取格式不符合预期

• • 可能原因：LLM 解析精度不足、schema 定义不清晰
• • 解决方案：

1. 1. 升级 LLM 模型（如从 gpt-3.5-turbo 切换到 gpt-4o）
2. 2. 优化 schema 描述（如添加示例：z.string ()