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

# BrowserViewer

`BrowserViewer` 類別為以 CLI 為基礎的 Tool 提供瀏覽器自動化功能。它會透過 Playwright 啟動 Chrome、提供 Chrome DevTools Protocol（CDP）URL，並自動將該 URL 注入經由 Workspace Tool 執行的 CLI 指令。

當 Agent 透過 `browser-use`、`agent-browser` 或 `browse` 等 CLI Tool 操控瀏覽器時，請使用 `BrowserViewer`。如要使用以 SDK 為基礎的瀏覽器自動化功能，請使用 [`AgentBrowser`](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser) 或 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-HK/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` 會連接現有瀏覽器，而不會啟動新瀏覽器。scope 預設為 `'shared'`。

## 建構函式參數

**cli** (`'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'`): Agent 用於瀏覽器自動化的 CLI。CLI 會透過 CDP URL 連接 Chrome。

**headless** (`boolean`): 是否以 headless 模式執行 Chrome。 (Default: `true`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 用於連接現有瀏覽器而非啟動新瀏覽器的 CDP WebSocket URL。

**cdpPort** (`number`): Chrome 遙距除錯使用的連接埠。只會在啟動 Chrome 時使用（透過 cdpUrl 連接時不會使用）。 (Default: `0 (auto-assign)`)

**scope** (`'shared' | 'thread'`): 瀏覽器實例的 scope。'thread' 會為每個 thread 提供獨立的瀏覽器；'shared' 則讓所有 thread 共用同一個瀏覽器。提供 cdpUrl 時，預設為 'shared'。 (Default: `'thread'`)

**viewport** (`{ width: number; height: number }`): 瀏覽器 viewport 的尺寸。 (Default: `{ width: 1280, height: 720 }`)

**executablePath** (`string`): Chrome 執行檔的路徑。預設使用 Playwright 隨附的 Chromium。

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 瀏覽器準備就緒後呼叫的 callback。

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 瀏覽器關閉前呼叫的 callback。

**screencast** (`ScreencastOptions`): 將瀏覽器 frame 串流至 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。scope 為 `'shared'` 時，會啟動一個共用瀏覽器；scope 為 `'thread'` 時，則會為指定的 thread 啟動瀏覽器。

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

#### `ensureReady()`

確保瀏覽器已啟動並準備就緒。scope 為 `'thread'` 時，會按需要為目前的 thread 建立新瀏覽器。

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

#### `isBrowserRunning(threadId?)`

檢查瀏覽器是否正在執行。scope 為 `'thread'` 時，會檢查指定的 thread。

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

傳回：`boolean`

#### `close()`

關閉所有瀏覽器實例並清理資源。

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

### 存取 CDP

#### `getCdpUrl(threadId?)`

傳回目前或指定 thread 的 CDP WebSocket URL。CLI Tool 會使用此 URL 連接受管理的瀏覽器。

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

傳回：`string | null`

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

透過 CDP URL 連接外部瀏覽器以進行 screencast。當 Agent 提供自己的瀏覽器 endpoint（例如雲端瀏覽器服務）時，可使用此方法。BrowserViewer 會連接瀏覽器以進行 screencast，但不會管理瀏覽器的生命週期。

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

### Screencast

#### `startScreencast(options?)`

開始串流瀏覽器 frame。此方法會傳回發出 frame 事件的 `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/zh-HK/docs/workspace/skills)，讓 Agent 學會相關指令和 Workflow。透過 `workspace_execute_command` 執行 CLI 指令時，Mastra 會偵測該指令，並使用正確的 flag 自動注入 CDP URL。

與 SDK Provider 不同，`BrowserViewer` 不會提供 Agent Tool。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/zh-HK/docs/browser/browser-viewer)：設定及使用逐步說明
- [MastraBrowser](https://mastra.zisheng.pro/zh-HK/reference/browser/mastra-browser)：基礎類別 API 參考
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)：Workspace 設定