> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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/zh-HK/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/zh-HK/docs/browser/agent-browser) 或 [Stagehand](https://mastra.zisheng.pro/zh-HK/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/zh-HK/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/zh-HK/docs/workspace/skills)，教導 Agent 其指令及 Workflow。

設定 `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/zh-HK/reference/browser/browser-viewer)。

## 相關內容

- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/zh-HK/docs/browser/agent-browser)
- [Stagehand](https://mastra.zisheng.pro/zh-HK/docs/browser/stagehand)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [Workspace Skill](https://mastra.zisheng.pro/zh-HK/docs/workspace/skills)