BrowserTool浏览器

第一步：创建BrowserTool服务

1. 登录 AgentRun 控制台。

2. 首次使用时，系统会提示您为阿里云账号授予 AgentRun 的服务关联角色（AliyunServiceRoleForAgentRun）。请根据页面指导完成授权，这是服务正常运行所必需。

3. 在运行时与沙箱页签下选择Sandbox沙箱，创建沙箱模板选择浏览器，立即创建BrowserTool服务。

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

• OpenAPI 文档：CreateBrowser API

• 多语言 SDK：AgentRun SDK 中心

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

1. 服务创建成功后，在控制台服务列表中找到您的 BrowserTool 服务，单击进入详情页。

2. 在详情页的VNC调试标签页下新建沙箱。

3. 创建成功后，您将获得一个用于自动化连接的 WebSocket 端点 (CDP Endpoint)，您可以直接从控制台复制使用。其格式示例如下：

   wss://1234567890.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/br-abcdef123456/ws/automation?tenantId=1234567890

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

将上一步获取的完整连接端点 URL 传入您熟悉的自动化框架脚本中，即可连接到 BrowserTool 并执行任务。

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

// 从BrowserTool服务详情页获取此端点
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/automation?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();

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

// 从BrowserTool 服务详情页获取此端点
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxId}/ws/automation?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)

   用于浏览器自动化，与Puppeteer和Playwright兼容。端点格式如下：

   wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxId}/ws/automation?tenantId={accountID}

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

   # 安装wscat
   npm install -g wscat
   
   # 连接到CDP代理
   wscat -c "wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/automation/?tenantId={accountID}"
   
   # 发送CDP命令
   {"id":1,"method":"Runtime.evaluate","params":{"expression":"navigator.userAgent"}}

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

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

   wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/livestream?tenantId={accountID}

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

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

框架集成示例

BrowserTool 可以与多种编程语言的 AI Agent 框架或自动化库轻松集成。

• BrowserUse 操作示例：

  from browser_use import Agent, BrowserSession
  from browser_use.llm import ChatDeepSeek
  from browser_use.browser import BrowserProfile
  
  from dotenv import load_dotenv
  import os
  import asyncio
  
  load_dotenv()
  
  async def main():
      # 填入CDP URL
      browser_session_wss_url = "wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/automation?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的api_key，如果使用其他模型，请自行修改
      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())

  效果预览：

  

• Puppeteer 连接示例

  const puppeteer = require('puppeteer-core');
  
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/automation?tenantId={accountID}'
  });
  
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'screenshot.png' });
  await browser.close();

  效果预览：

  

1、列出所有录制文件

获取系统中所有 VNC 录制文件的列表，支持分页查询。

{
  "recordings": [
    {
      "filename": "vnc_global_20251116_103022_seg000.mkv",
      "sessionId": "vnc_global_20251116_103022",
      "segment": 0,
      "size": 15728640,
      "createdAt": "2025-11-16T10:30:22+08:00",
      "format": "mkv",
      "downloadUrl": "/recordings/vnc_global_20251116_103022_seg000.mkv",
      "recordingType": "vnc",
      "status": "completed"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

# 获取第一页，每页 20 条记录（默认）
curl -X GET "http://localhost:3000/recordings/"

# 获取第二页，每页 10 条记录
curl -X GET "http://localhost:3000/recordings/?page=2&page_size=10"

# 获取所有录制文件（设置较大的 page_size）
curl -X GET "http://localhost:3000/recordings/?page_size=100"

2、下载录制文件

下载指定的 VNC 录制文件。

# 下载录制文件
curl -X GET "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv" \
  -o vnc_global_20251116_103022_seg000.mkv

# 在浏览器中直接访问
http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv

3、删除录制文件

删除指定的 VNC 录制文件。

{
  "message": "Recording file deleted successfully",
  "filename": "vnc_global_20251116_103022_seg000.mkv"
}

# 删除指定的录制文件
curl -X DELETE "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv"

# 使用 jq 格式化输出
curl -X DELETE "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv" | jq

RecordingInfo

录制文件信息对象

interface RecordingInfo {
  filename: string;           // 文件名
  sessionId: string;          // 会话 ID
  segment: number;            // 段索引（从 0 开始，分段录制时使用）
  size: number;               // 文件大小（字节）
  createdAt: string;          // 文件创建时间（ISO 8601 格式）
  format: "mkv";              // 文件格式（固定为 mkv）
  downloadUrl: string;        // 下载 URL
  recordingType: "vnc";       // 录制类型（固定为 vnc）
  status: "completed";        // 录制状态（固定为 completed）
}

RecordingListResponse

录制文件列表响应对象

interface RecordingListResponse {
  recordings: RecordingInfo[];  // 录制文件列表（按创建时间降序排列）
  total: number;                // 录制文件总数（不考虑分页）
  page?: number;                // 当前页码（仅在分页查询时返回）
  pageSize?: number;            // 每页数量（仅在分页查询时返回）
}

RecordingDeleteResponse

录制文件删除响应对象

interface RecordingDeleteResponse {
  message: string;   // 操作结果消息
  filename: string;  // 被删除的文件名
}

使用限制

• 会话生命周期：单个沙箱会话的默认最长生命周期为 6 小时。到期后会自动销毁。

• 闲置超时：您可以在创建服务时通过 sandboxIdleTimeoutSeconds 参数设置会话的闲置超时时长。若会话在此期间无任何操作，将被提前终止以节约成本。

• 浏览器支持：目前服务内置并支持 Chromium/Chrome 浏览器。未来计划支持 Firefox 及 Edge。

安全说明

• 环境隔离：每个浏览器沙箱实例都运行在独立的容器环境中，确保了任务之间、用户之间的文件系统和进程空间完全隔离，保障任务安全性。

• 权限管理：遵循最小权限原则，通过服务关联角色 (AliyunServiceRoleForAgentRun) 确保服务仅能访问必要的云资源

• 传输加密：所有数据面访问端点（CDP 和 VNC）均使用 WSS (WebSocket Secure) 协议，确保您的指令和浏览器返回的数据在传输过程中全程加密。

错误处理

{
  "code": 1001,
  "error": "invalid request"
}

计费说明

BrowserTool 采用 Serverless 计费模式，按需使用，按量付费。主要根据沙箱实例的运行时长进行计费，没有实例运行时不产生费用。

详细的计费规则和价格，请参考函数计算计费概述。

整体架构图

核心组件

• 协议代理层 (Go)

  • CDP WebSocket 代理：作为客户端与浏览器沙箱之间的桥梁，它负责安全地转发来自 Puppeteer/Playwright 的 CDP 命令，并处理鉴权和会话管理。核心服务基于 Go 语言和 goroutine 构建，相比传统的 Node.js 实现，优化了内存占用和并发连接处理能力。

  • VNC WebSocket 代理：将 TigerVNC 产生的原生 VNC 流实时转码为 WebSocket 流，从而允许 noVNC 等标准 Web客户端直接在网页上渲染远程桌面，提供实时视图。

• 浏览器运行时

  • 容器化方案：利用 Docker 多阶段构建技术生成轻量级运行镜像，加快部署与启动速度。镜像中已预装所有必要依赖和浏览器驱动。

  • VNC 远程桌面服务：在容器内，通过组合 Xvfb (虚拟屏幕)、Openbox (极简窗口管理器) 和 TigerVNC (VNC服务)，为无头浏览器提供了一个可被远程查看的图形化界面。