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

# MastraBrowser 類別

`MastraBrowser` 類別是瀏覽器自動化 Provider 的抽象基底類別。其共用 interface 涵蓋瀏覽器啟動與 thread 隔離，以及 screencast 串流與輸入 event。

請勿直接建立 `MastraBrowser` instance，改用 Provider 實作：

- [`AgentBrowser`](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)：使用 ref 的確定性瀏覽器自動化
- [`StagehandBrowser`](https://mastra.zisheng.pro/zh-TW/reference/browser/stagehand-browser)：使用自然語言的 AI 驅動瀏覽器自動化
- [`BrowserViewer`](https://mastra.zisheng.pro/zh-TW/reference/browser/browser-viewer)：透過 CDP URL injection 操作的 CLI 型瀏覽器自動化

## 使用範例

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: 'You can browse the web to find information.',
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## Constructor 參數

**headless** (`boolean`): 是否以 headless 模式執行瀏覽器（不顯示 UI）。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 瀏覽器 viewport 尺寸，用於控制瀏覽器視窗大小。設為 window 可符合實際瀏覽器視窗，而不使用固定尺寸；agent-browser Provider 以及透過 CDP 連線的 Stagehand 支援此設定。 (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): 預設逾時毫秒數。各 Provider 會定義自己的語意與預設值，詳情請參閱 Provider 參考文件。

**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL、HTTP endpoint，或同步／非同步 Provider 函式。提供時會連線至現有瀏覽器，而不是啟動新瀏覽器。HTTP endpoint 會在內部解析為 WebSocket。不能與 scope: 'thread' 一起使用（會自動使用 shared scope）。

**scope** (`'shared' | 'thread'`): 瀏覽器 instance 跨 thread 的範圍。shared 表示所有 thread 共用一個瀏覽器 instance；thread 表示每個 thread 都有自己的瀏覽器 instance（完全隔離）。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 瀏覽器進入 'ready' 狀態後呼叫的 callback。

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

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

**screencast.format** (`'jpeg' | 'png'`): screencast frame 的圖片格式。

**screencast.quality** (`number`): 圖片品質（1 至 100），只適用於 JPEG 格式。

**screencast.maxWidth** (`number`): screencast frame 的最大寬度。

**screencast.maxHeight** (`number`): screencast frame 的最大高度。

**screencast.everyNthFrame** (`number`): 每 N 個 frame 擷取一次，以降低頻寬。

## 屬性

以下屬性（`id`、`name`、`provider`）為 abstract，必須由具體 Provider 實作定義：

**id** (`string`): 此瀏覽器 instance 的不重複識別碼。abstract，由 Provider 定義。

**name** (`string`): 方便閱讀的瀏覽器 Provider 名稱，例如 'AgentBrowser'、'StagehandBrowser'。abstract，由 Provider 定義。

**provider** (`string`): Provider 識別碼，例如 'vercel-labs/agent-browser'、'browserbase/stagehand'。abstract，由 Provider 定義。

**headless** (`boolean`): 瀏覽器是否以 headless 模式執行。

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

## 方法

### 生命週期

#### `ensureReady()`

確保瀏覽器已啟動並可供使用。在 Tool 執行前自動呼叫。實作位於基底類別。

```typescript
await browser.ensureReady()
```

#### `close()`

關閉瀏覽器並清理所有資源。實作位於基底類別，且能安全處理 race condition。

```typescript
await browser.close()
```

#### `isBrowserRunning()`

檢查瀏覽器目前是否正在執行。

```typescript
const isRunning = browser.isBrowserRunning()
```

**傳回：** `boolean`

### Thread 管理

#### `setCurrentThread(threadId)`

設定瀏覽器操作目前使用的 thread ID。由 Agent runtime 內部使用。

```typescript
browser.setCurrentThread('thread-123')
```

#### `getCurrentThread()`

取得目前的 thread ID。

```typescript
const threadId = browser.getCurrentThread()
```

**傳回：** `string`

#### `hasThreadSession(threadId)`

檢查 thread 是否具有有效的瀏覽器 session。

```typescript
const hasSession = browser.hasThreadSession('thread-123')
```

**傳回：** `boolean`

#### `closeThreadSession(threadId)`

關閉特定 thread 的瀏覽器 session。使用 'thread' scope 時，會關閉該 thread 的瀏覽器 instance；使用 'shared' scope 時，會清除 thread state。

```typescript
await browser.closeThreadSession('thread-123')
```

### Tool

#### `getTools()`

傳回供 Agent 使用的瀏覽器 Tool。各 Provider 會依模型傳回不同 Tool。

```typescript
const tools = browser.getTools()
```

**傳回：** `Record<string, Tool>`

### Screencast

#### `startScreencast(options?, threadId?)`

開始串流瀏覽器 frame。傳回會發出 frame event 的 `ScreencastStream`。

```typescript
const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')

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?)`

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

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

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

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

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

### State

#### `getState(threadId?)`

取得目前的瀏覽器 state，包括 URL 與分頁。

```typescript
const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)
```

**傳回：** `Promise<BrowserState>`

```typescript
interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}
```

#### `getCurrentUrl(threadId?)`

取得目前頁面 URL。

```typescript
const url = await browser.getCurrentUrl()
```

**傳回：** `Promise<string | null>`

## Browser scope

`scope` 選項控制瀏覽器 instance 在對話 thread 之間的共用方式：

| Scope      | 說明                          | 使用情境              |
| ---------- | --------------------------- | ----------------- |
| `'shared'` | 所有 thread 共用單一瀏覽器 instance  | 適用於不互相衝突的任務，可節省成本 |
| `'thread'` | 每個 thread 都有自己的瀏覽器 instance | 為並行使用者提供完整隔離      |

```typescript
// Shared browser for all threads
const sharedBrowser = new AgentBrowser({
  scope: 'shared',
})

// Isolated browser per thread
const isolatedBrowser = new AgentBrowser({
  scope: 'thread',
})
```

使用 `cdpUrl` 連線至外部瀏覽器時，scope 會自動改用 `'shared'`，因為無法建立新的瀏覽器 instance。

## 雲端瀏覽器 Provider

使用 `cdpUrl` 選項連線至雲端瀏覽器服務：

```typescript
// Static CDP URL
const browser = new AgentBrowser({
  cdpUrl: 'wss://browser.example.com/ws',
})

// Dynamic CDP URL (e.g., session-based)
const browser = new AgentBrowser({
  cdpUrl: async () => {
    const session = await createBrowserSession()
    return session.wsUrl
  },
})
```

## 相關內容

- [AgentBrowser](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)：確定性瀏覽器自動化
- [StagehandBrowser](https://mastra.zisheng.pro/zh-TW/reference/browser/stagehand-browser)：AI 驅動的瀏覽器自動化
- [Browser 概觀](https://mastra.zisheng.pro/zh-TW/docs/browser/overview)：瀏覽器自動化概念指南