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

# BrowserViewer

`BrowserViewer` 類別為 CLI 型 Tool 提供瀏覽器自動化。它會透過 Playwright 啟動 Chrome，公開 Chrome DevTools Protocol（CDP）URL，並自動將其注入透過 Workspace Tool 執行的 CLI 指令。

當 Agent 透過 `browser-use`、`agent-browser` 或 `browse` 等 CLI Tool 操作瀏覽器時，請使用 `BrowserViewer`。以 SDK 為基礎的瀏覽器自動化請使用 [`AgentBrowser`](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser) 或 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-TW/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'`。

## Constructor 參數

**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'`): 瀏覽器 instance scope。thread 讓每個 thread 使用自己的瀏覽器；shared 讓所有 thread 共用一個瀏覽器。提供 cdpUrl 時預設為 shared。 (Default: `'thread'`)

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

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

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

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

**screencast** (`ScreencastOptions`): 將瀏覽器 frame 串流至 Studio 的設定。

## 屬性

**id** (`string`): 此瀏覽器 instance 的不重複識別碼，格式為 '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'`): 此 instance 設定使用的 CLI Provider。

**status** (`BrowserStatus`): 目前瀏覽器狀態：'pending'、'launching'、'ready'、'error'、'closing' 或 'closed'。

## 方法

### 生命週期

#### `launch(threadId?)`

啟動 Chrome。使用 `'shared'` scope 時會啟動單一共用瀏覽器；使用 `'thread'` scope 時，會為指定 thread 啟動瀏覽器。

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

#### `ensureReady()`

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

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

#### `isBrowserRunning(threadId?)`

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

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

傳回：`boolean`

#### `close()`

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

```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 event 的 `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>`

### 輸入 injection

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

透過 CDP 將滑鼠 event 注入瀏覽器。Studio 使用此方法進行即時互動。

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

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

透過 CDP 將鍵盤 event 注入瀏覽器。Studio 使用此方法進行即時互動。

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

## 支援的 CLI

每個 CLI 都必須分別安裝，也都會發布 [Skill](https://mastra.zisheng.pro/zh-TW/docs/workspace/skills)，教導 Agent 使用其指令與 Workflow。CLI 指令透過 `workspace_execute_command` 執行時，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-TW/docs/browser/browser-viewer)：設定與使用教學
- [MastraBrowser](https://mastra.zisheng.pro/zh-TW/reference/browser/mastra-browser)：基底類別 API 參考文件
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)：Workspace 設定