> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# BrowserViewer

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

当 Agent 通过 `browser-use`、`agent-browser` 或 `browse` 等 CLI 工具驱动浏览器时，请使用 `BrowserViewer`。对于基于 SDK 的浏览器自动化，请使用 [`AgentBrowser`](https://mastra.zisheng.pro/reference/browser/agent-browser) 或 [`StagehandBrowser`](https://mastra.zisheng.pro/reference/browser/stagehand-browser)。

## 用法示例

```typescript
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(),
})
```

### 连接现有浏览器

```typescript
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`): 是否以无头模式运行 Chrome。 (Default: `true`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 用于连接现有浏览器而非启动新浏览器的 CDP WebSocket URL。

**cdpPort** (`number`): Chrome 远程调试端口。仅在启动 Chrome 时使用（通过 cdpUrl 连接时不使用）。 (Default: `0 (auto-assign)`)

**scope** (`'shared' | 'thread'`): 浏览器实例作用域。'thread' 为每个线程提供独立浏览器。'shared' 让所有线程共享一个浏览器。提供 cdpUrl 时默认为 'shared'。 (Default: `'thread'`)

**viewport** (`{ width: number; height: number }`): 浏览器视口尺寸。 (Default: `{ 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'` 作用域，为指定线程启动浏览器。

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

#### `ensureReady()`

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

```typescript
await viewer.ensureReady()
```

#### `isBrowserRunning(threadId?)`

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

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

返回：`boolean`

#### `close()`

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

```typescript
await viewer.close()
```

### CDP 访问

#### `getCdpUrl(threadId?)`

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

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

返回：`string | null`

#### `connectToExternalCdp(cdpUrl, threadId?)`

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

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

### 屏幕串流

#### `startScreencast(options?)`

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

```typescript
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 使用此方法进行实时交互。

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

#### `injectKeyboardEvent(params, threadId?)`

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

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

## 支持的 CLI

每个 CLI 都必须单独安装。它们还各自发布了一个 [Skill](https://mastra.zisheng.pro/docs/workspace/skills)，用于向 Agent 传授其命令和工作流。通过 `workspace_execute_command` 运行 CLI 命令时，Mastra 会检测该命令，并使用正确的 flag 自动注入 CDP URL。

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

### [`agent-browser`](https://www.npmjs.com/package/agent-browser)

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

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

### [`browser-use`](https://pypi.org/project/browser-use/)

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

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

### [`browse`](https://www.npmjs.com/package/browse)（命令：`browse`）

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

```bash
npm install -g browse
browse skills install
```

## 相关内容

- [BrowserViewer 指南](https://mastra.zisheng.pro/docs/browser/browser-viewer)：设置和用法演练
- [MastraBrowser](https://mastra.zisheng.pro/reference/browser/mastra-browser)：基类 API 参考
- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)：Workspace 配置