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

# BrowserViewer

`@mastra/browser-viewer` 包为 [agent-browser](https://www.npmjs.com/package/agent-browser)、[browser-use](https://pypi.org/project/browser-use/) 和 [browse](https://www.npmjs.com/package/browse) 等基于 CLI 的 Tool 提供浏览器自动化。BrowserViewer 通过 Playwright 启动 Chrome，公开 Chrome DevTools Protocol（CDP）URL，并自动将其注入通过 [Workspace Tool](https://mastra.zisheng.pro/docs/workspace/overview) 运行的 CLI 命令。

## 何时使用 BrowserViewer

当 Agent 通过 CLI Tool（而不是 SDK）操控浏览器时，请使用 BrowserViewer。BrowserViewer 负责：

- 启动并管理 Chrome，供 CLI Tool 连接
- 自动将 CDP URL 注入 `workspace_execute_command` 调用
- 向 Studio 实时传输投屏画面
- 按线程隔离浏览器

对于基于 SDK 的浏览器自动化，请改用 [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser) 或 [Stagehand](https://mastra.zisheng.pro/docs/browser/stagehand)。

## 快速开始

安装 `@mastra/browser-viewer` 以及 Agent 将使用的 CLI Tool。BrowserViewer 负责管理 Chrome，但 CLI Tool 本身必须单独安装。

**npm**:

```bash
npm install @mastra/browser-viewer
```

**pnpm**:

```bash
pnpm add @mastra/browser-viewer
```

**Yarn**:

```bash
yarn add @mastra/browser-viewer
```

**Bun**:

```bash
bun add @mastra/browser-viewer
```

在 Workspace 环境中安装 CLI Tool。此示例使用 `browser-use`：

```bash
pip install browser-use
```

安装相应的 [Skill](https://mastra.zisheng.pro/docs/workspace/skills)，让 Agent 知道如何使用该 CLI：

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

使用 BrowserViewer 创建 Workspace，并将其分配给 Agent：

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

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.
Use browser-use commands to navigate and interact with websites.`,
  memory: new Memory(),
})

export const mastra = new Mastra({
  agents: { browserAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})
```

当 Agent 运行 `browser-use open https://example.com` 之类的 CLI 命令时，Mastra 会自动启动 Chrome 并注入 CDP 连接，同时开始向 Studio 传输投屏画面。

## 工作原理

1. Agent 使用浏览器 CLI 命令调用 `workspace_execute_command`。
2. Mastra 检测到 CLI 命令，并通过 Playwright 启动 Chrome（如果尚未运行）。
3. CDP URL 会注入命令，使 CLI 连接到托管浏览器。
4. 投屏帧从页面级 CDP 会话传输到 Studio。

## 支持的 CLI

BrowserViewer 支持三个 CLI Provider。每个 CLI 都必须单独安装到 Workspace 环境中。每个 CLI 还会发布一个 [Skill](https://mastra.zisheng.pro/docs/workspace/skills)，向 Agent 说明其命令和工作方式。

设置 `cli` 选项，使其与 Agent 使用的 CLI 一致：

```typescript
const viewer = new BrowserViewer({
  cli: 'browser-use',
  headless: false,
})
```

### `agent-browser`

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

CDP 标志：`--cdp`

### `browser-use`

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

CDP 标志：`--cdp-url`

### `browse`

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

CDP 标志：`--ws`。有关所有配置选项、高级连接模式和方法详情，请参阅 [BrowserViewer 参考](https://mastra.zisheng.pro/reference/browser/browser-viewer)。

## 相关内容

- [Browser 概览](https://mastra.zisheng.pro/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser)
- [Stagehand](https://mastra.zisheng.pro/docs/browser/stagehand)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)
- [Workspace Skill](https://mastra.zisheng.pro/docs/workspace/skills)