AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 函数计算 函数计算 AgentRun Sandbox 沙箱—BrowserTool

Sandbox 沙箱—BrowserTool

更新时间：
产品详情
我的收藏

BrowserTool 是一款基于 Go 语言构建的高性能、云原生无头浏览器沙箱服务。它通过标准的 CDP over WebSocket 协议，兼容 Puppeteer、Playwright 等主流自动化框架，提供稳定、高效且安全的浏览器自动化环境。无论是进行自动化测试、网页数据抓取，还是构建复杂的 AI Agent 应用，BrowserTool 都能作为强大的“云端浏览器”，简化开发流程，提升运行效率。

核心优势

  • 性能与资源效率

    • Go 语言重构：相比传统的 Node.js 实现，内存占用、API 响应时间均有明显提升。

    • 高并发处理能力：基于 goroutine 的并发管理，提升了浏览器任务并发处理能力。

  • 广泛的兼容性

    • 多浏览器支持：已支持 Chromium/Chrome，并计划支持 Firefox及Edge等浏览器。

    • 主流框架兼容：通过标准 WebSocket 代理，原生支持 Puppeteer、Playwright 等工具库，通常无需修改现有代码即可平滑迁移。

  • 丰富的功能集成

    • REST API：提供截图、PDF 生成、内容提取等开箱即用的 HTTP 接口。

    • 实时视图 (VNC)：通过 noVNC 实时查看浏览器操作界面，便于调试和监控。

    • 会话智能管理：内置浏览器生命周期和资源管理机制，确保服务稳定可靠。

  • 云原生与安全性

    • Serverless 架构：按需使用，弹性伸缩，简化运维工作。

    • 安全沙箱：每个浏览器实例都在隔离的容器环境中运行，保障任务安全性。

技术架构

BrowserTool 采用清晰的分层架构设计，确保了系统的高性能、高稳定性和易于扩展。整个系统自上而下分为客户端层、协议代理层和基础设施层，各组件协同工作，对外提供统一、强大的浏览器自动化能力。

整体架构图

image

核心组件

  1. BrowserTool 核心服务

    • HTTP API 服务：提供RESTful API接口，封装了常见的浏览器操作，如 /screenshot（截图）、/pdf（生成PDF）和 /content（提取网页内容），简化了轻量级任务的开发。

    • WebSocket 代理：作为连接客户端与浏览器的桥梁。它将来自 Puppeteer/Playwright 的 CDP 命令安全地转发给对应的浏览器实例，并将浏览器的响应传回客户端，实现了远程自动化。

    • VNC WebSocket 代理：为了实现实时画面直播，该组件将 tigervnc 产生的原生 VNC 流实时转码为 WebSocket 流，使前端可以通过 noVNC 等工具直接在网页上观看远程浏览器的操作画面。

  2. 浏览器自动化组件

    • Playwright 支持：内置 Playwright 的 Chromium 版本，提供稳定、现代化的浏览器自动化能力，兼容其丰富的 API 生态。

    • 会话管理：智能管理并发的浏览器会话。每个会话都在独立的 Browser Context 中运行，保证了环境隔离。系统还内置了自动清理和恢复机制，确保资源的有效利用和服务的稳定性。

  3. VNC 远程桌面服务
    这个服务由三个经典组件协同工作，共同提供远程桌面能力：

    • Xvfb 创建一个内存中的虚拟屏幕。

    • Openbox 在这个虚拟屏幕上提供一个极简的窗口界面。

    • tigervnc 将这个界面的内容实时地通过 VNC 协议广播出来。

  4. 容器化方案

    • 多阶段 Docker 构建：利用 Docker 的多阶段构建特性，将编译环境与运行环境分离，确保最终生成的镜像既纯净又小巧，极大地加快了部署和启动速度。

    • 统一的服务管理：通过一个统一的启动脚本（entrypoint），协同管理容器内的 BrowserTool 服务、VNC 服务和浏览器进程，实现了一键启动与平滑关闭。

    • 优化的运行时：镜像中预装了所有必要的依赖和浏览器驱动，避免了在运行时下载或安装，做到了开箱即用。

快速入门

第一步：创建BrowserTool实例

  1. 登录 AgentRun 控制台。

  2. 首次使用时，请根据页面提示为阿里云账号授予 AgentRun 服务关联角色（SLR）权限。

  3. 在控制台中创建 BrowserTool 实例。

也可以通过 OpenAPI 或 SDK 进行创建：

第二步：获取连接端点 (Endpoint)

  1. 创建成功后，在实例的详情 > 会话管理 > 启动新会话中，找到数据面访问端点（CDP Endpoint）。这是连接浏览器进行自动化的核心地址。

    image基础URL（BaseURL）通常采用以下格式：

    wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/

  2. 在上述的 BaseURL 后面添加路径 /ws/automation/，即可得到操作浏览器的 CDP 地址。

  3. 连接时，客户端需在 URL 参数中提供 sessionId，其值应为一个随机生成的 UIUID（其中首字符必须为 a-f 中任一英文字母），用于标识本次会话。

  4. 一个完整的连接示例如下：

    wss://1234567890.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/br-abcdef123456/ws/automation/?sessionId=a1b2c3d4-e5f6-7890-1234-567890abcdef&tenantId=1234567890

第三步：连接并执行自动化脚本

使用熟悉的自动化框架，将上一步获取的完整端点作为 browserWSEndpoint 或 wsEndpoint 传入即可。

Puppeteer 连接示例

const puppeteer = require('puppeteer-core');

// 从BrowserTool 实例详情页获取此端点
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation?sessionId={YOUR_SESSION_ID}&tenantId={accountID}';

async function main() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: BROWSERTOOL_CDP_ENDPOINT,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png' });
  console.log('Screenshot taken!');
  await browser.close();
}

main();

Playwright 连接示例

const { chromium } = require('playwright-core');

// 从BrowserTool 实例详情页获取此端点
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation?sessionId={YOUR_SESSION_ID}&tenantId={accountID}';

async function main() {
  const browser = await chromium.connectOverCDP({
    endpointURL: BROWSERTOOL_CDP_ENDPOINT,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png' });
  console.log('Screenshot taken!');
  await browser.close();
}

main();

功能指南

WebSocket自动化端点

BrowserTool 提供了两个主要的 WebSocket 端点，用于不同的自动化场景。

  1. CDP 自动化端点 (/ws/automation)

    用于浏览器自动化的WebSocket端点，与Puppeteer和Playwright兼容。

    云服务可用端点：

    • 通用： 

      wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation?sessionId={YOUR_SESSION_ID}&tenantId={accountID}

    • Chromium：

      wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation/chromium?sessionId={YOUR_SESSION_ID}&tenantId={accountID}

    使用 wscat 手动调试：

    使用 `wscat` 工具直接与 CDP 端点交互，发送原始 CDP 命令进行调试。

    # 安装wscat
npm install -g wscat

# 连接到CDP代理
wscat -c "wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation/?sessionId={YOUR_SESSION_ID}&tenantId={accountID}"

# 发送CDP命令
{"id":1,"method":"Runtime.evaluate","params":{"expression":"navigator.userAgent"}}

  2. VNC实时流端点（/ws/liveview）

    用于实时查看浏览器桌面环境的WebSocket端点，支持通过NoVNC客户端查看，详细参考实时查看浏览器界面（VNC）。

    VNC连接端点：

    wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/liveview?sessionId={YOUR_SESSION_ID}&tenantId={accountID}

实时查看浏览器界面（VNC）

BrowserTool 支持通过 VNC 实时查看远程浏览器的桌面环境，非常适合在开发和调试阶段监控自动化任务的执行情况。

方案一：使用预置的Docker镜像

我们提供了一个预置的noVNC客户端的Docker镜像，方便快速启动查看器。

操作步骤：

  1. 在本地运行 noVNC 客户端容器：

    docker run -p 8184:80 -d --rm registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:browsertool-sandbox-vnc-client_v0.3.1

  2. 打开浏览器访问 http://localhost:8184。

  3. 在连接设置中，填入VNC 连接端点，即可看到浏览器界面。

    image

说明

初始界面可能是灰色背景，这是正常的。当有自动化请求（如 page.goto）时，浏览器才会启动并显示内容。

方案二：使用noVNC客户端

如果希望将 VNC 视图嵌入到自己的项目中，可以使用 noVNC 的 JavaScript库。

  1. noVNC 官方提供了一个公开的 Web 客户端，无需部署或编写任何代码即可使用。

    访问地址：https://novnc.com/noVNC/vnc.html

    操作步骤：与方案一类似，点击页面上的Settings图标，在WebSocket中填入 URL地址、端口、路径等信息，然后点击连接。

  2. 自定义前端集成，允许完全控制 VNC 视图的展现形式和交互逻辑。需要引入 noVNC 的核心 JS 库，并在前端代码中进行初始化。

    示例地址：https://github.com/novnc/noVNC/blob/master/vnc_lite.html

集成与生态

BrowserTool 可以轻松集成到各种工作流和平台中。

  • BrowserUse 操作示例：

    配置示例：

    from browser_use import Agent, BrowserSession
from browser_use.llm import ChatDeepSeek
from browser_use.browser import BrowserProfile
from playwright.async_api import async_playwright

from dotenv import load_dotenv
import os
import asyncio

load_dotenv()

async def main():
    browser_session_wss_url = "wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation?sessionId={YOUR_SESSION_ID}&tenantId={accountID}"
    
    browser_session = BrowserSession(
        cdp_url=browser_session_wss_url, 
        browser_profile=BrowserProfile(
            headless=False,
            user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.X.X Safari/537.36",
            timeout=3000000,
            keep_alive=True,
        )
    )
    
    # 需要修改DeepSeek的sk，如果您使用其他模型，请自行修改
    llm = ChatDeepSeek(api_key="sk-your-deepseek-sk")

    agent = Agent(
        task="请访问 https://www.aliyun.com/product/list 并分析一下阿里云目前都提供了哪些产品",
        llm=llm,
        browser_session=browser_session,
        use_vision=True
    )
    result = await agent.run()
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

    效果预览：

    image

  • Puppeteer 连接示例

    配置示例：

    const puppeteer = require('puppeteer-core');

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/2025-09-10/agents/browsers/{browserID}/ws/automation?sessionId=bc8728db-cf2e-4710-9764-f9aa9a4a5dab&tenantId={accountID}'
});

const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

    效果预览：

    image

应用场景

  • AI Agent 与大模型工具调用
    作为 AI Agent 的“眼睛”和“手”，执行网页浏览、信息提取、表单填写等复杂任务，增强大模型与真实世界的交互能力。

  • 自动化测试

    • E2E 测试：在云端隔离环境中运行端到端测试，确保应用功能稳定。

    • 视觉回归测试：利用截图 API 对比 UI 变化，防止非预期的视觉变更。

  • 数据采集与监控

    • 网页抓取：高效、稳定地从各类网站提取文本、图片和结构化数据。

    • 可用性监控：定时访问网站或应用，监测服务可用性并及时告警。

  • 内容生成与报告

    • 自动报告：将动态数据网页或后台看板生成为 PDF 报告，用于归档或分发。

    • 文档转换：批量将网页内容转换为 PDF 文档。

上一篇：AgentRun下一篇：应用-即将下线