BrowserViewer

BrowserViewer 类为基于 CLI 的工具提供浏览器自动化。它通过 Playwright 启动 Chrome，公开 Chrome DevTools Protocol（CDP）URL，并自动将其注入由 workspace 工具运行的 CLI 命令中。

当 Agent 通过 browser-use、agent-browser 或 browse 等 CLI 工具驱动浏览器时，请使用 BrowserViewer。对于基于 SDK 的浏览器自动化，请使用 AgentBrowser 或 StagehandBrowser。

用法示例

src/mastra/index.ts

import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { Memory } from '@mastra/memory'
import { BrowserViewer } from '@mastra/browser-viewer'
import { Agent } from '@mastra/core/agent'

const workspace = new Workspace({
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  browser: new BrowserViewer({
    cli: 'browser-use',
    headless: false,
  }),
})

const browserAgent = new Agent({
  id: 'browser-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
  instructions: 'You are a web automation assistant.',
  memory: new Memory(),
})

连接现有浏览器

const viewer = new BrowserViewer({
  cli: 'browser-use',
  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
})

提供 cdpUrl 后，BrowserViewer 会连接现有浏览器，而不是启动新浏览器。作用域默认为 'shared'。

构造函数参数

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

Agent 使用哪个 CLI 进行浏览器自动化。该 CLI 通过 CDP URL 连接 Chrome。

headless?:

boolean

= true

是否以无头模式运行 Chrome。

cdpUrl?:

string | (() => string | Promise<string>)

用于连接现有浏览器而非启动新浏览器的 CDP WebSocket URL。

cdpPort?:

number

= 0 (auto-assign)

Chrome 远程调试端口。仅在启动 Chrome 时使用（通过 cdpUrl 连接时不使用）。

scope?:

'shared' | 'thread'

= 'thread'

浏览器实例作用域。'thread' 为每个线程提供独立浏览器。'shared' 让所有线程共享一个浏览器。提供 cdpUrl 时默认为 'shared'。

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

浏览器视口尺寸。

executablePath?:

string

Chrome 可执行文件的路径。默认使用 Playwright 捆绑的 Chromium。

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

浏览器准备就绪后调用的回调。

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

浏览器关闭前调用的回调。

screencast?:

ScreencastOptions

将浏览器帧流式传输到 Studio 的配置。

属性

id:

string

此浏览器实例的唯一标识符。生成为 'browser-viewer-{timestamp}'。

name:

string

'BrowserViewer'

provider:

string

'browser-viewer'

providerType:

'cli'

始终为 'cli'。用于区分 BrowserViewer 与 AgentBrowser 等基于 SDK 的 Provider。

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

为此实例配置的 CLI Provider。

status:

BrowserStatus

当前浏览器状态：'pending'、'launching'、'ready'、'error'、'closing' 或 'closed'。

方法

生命周期

launch(threadId?)

启动 Chrome。对于 'shared' 作用域，启动一个共享浏览器。对于 'thread' 作用域，为指定线程启动浏览器。

await viewer.launch()
await viewer.launch('thread-123')

ensureReady()

确保浏览器已启动并准备就绪。对于 'thread' 作用域，如有需要，会为当前线程创建新浏览器。

await viewer.ensureReady()

isBrowserRunning(threadId?)

检查浏览器是否正在运行。对于 'thread' 作用域，检查指定线程。

const running = viewer.isBrowserRunning()
const threadRunning = viewer.isBrowserRunning('thread-123')

返回：boolean

close()

关闭所有浏览器实例并清理资源。

await viewer.close()

CDP 访问

getCdpUrl(threadId?)

返回当前线程或指定线程的 CDP WebSocket URL。CLI 工具使用此 URL 连接托管浏览器。

const cdpUrl = viewer.getCdpUrl()
// => 'ws://127.0.0.1:52481/devtools/browser/abc...'

返回：string | null

connectToExternalCdp(cdpUrl, threadId?)

通过 CDP URL 连接外部浏览器以进行 screencast。当 Agent 提供自己的浏览器端点（例如云浏览器服务）时使用。BrowserViewer 会连接以进行 screencast，但不管理浏览器生命周期。

await viewer.connectToExternalCdp('wss://cloud.example.com/session', 'thread-123')

屏幕串流

startScreencast(options?)

开始流式传输浏览器帧。返回一个发出帧事件的 ScreencastStream。当标签页发生变化时，会创建新的 CDP session，从而自动处理标签页切换。

const stream = await viewer.startScreencast({
  format: 'jpeg',
  quality: 80,
})

stream.on('frame', frame => {
  console.log('Frame received:', frame.data.length, 'bytes')
})

stream.on('stop', reason => {
  console.log('Screencast stopped:', reason)
})

返回：Promise<ScreencastStream>

输入注入

injectMouseEvent(params, threadId?)

通过 CDP 将鼠标事件注入浏览器。Studio 使用此方法进行实时交互。

await viewer.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1,
})

injectKeyboardEvent(params, threadId?)

通过 CDP 将键盘事件注入浏览器。Studio 使用此方法进行实时交互。

await viewer.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
})

支持的 CLI

每个 CLI 都必须单独安装。它们还各自发布了一个 Skill，用于向 Agent 传授其命令和工作流。通过 workspace_execute_command 运行 CLI 命令时，Mastra 会检测该命令，并使用正确的 flag 自动注入 CDP URL。

与 SDK Provider 不同，BrowserViewer 不提供 Agent 工具。Agent 改为通过 workspace_execute_command 使用 CLI 命令。

agent-browser

配置值：'agent-browser' · CDP flag：--cdp

npm install -g agent-browser
npx skills add vercel-labs/agent-browser

browser-use

配置值：'browser-use' · CDP flag：--cdp-url

pip install browser-use
npx skills add browser-use/browser-use --skill browser-use

browse（命令：browse）

配置值：'browse' · CDP flag：--ws

npm install -g browse
browse skills install

相关内容

• BrowserViewer 指南：设置和用法演练
• MastraBrowser：基类 API 参考
• Workspace 概述：Workspace 配置