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

# MastraBrowser 类

`MastraBrowser` 类是浏览器自动化 Provider 的抽象基类。它的通用接口涵盖浏览器启动、线程隔离、screencast 流式传输和输入事件。

你不会直接实例化 `MastraBrowser`。请改用 Provider 实现：

- [`AgentBrowser`](https://mastra.zisheng.pro/reference/browser/agent-browser)：使用 ref 的确定性浏览器自动化
- [`StagehandBrowser`](https://mastra.zisheng.pro/reference/browser/stagehand-browser)：使用自然语言的 AI 驱动浏览器自动化
- [`BrowserViewer`](https://mastra.zisheng.pro/reference/browser/browser-viewer)：注入 CDP URL 的基于 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,
})
```

## 构造函数参数

**headless** (`boolean`): 是否以无头模式（无可见 UI）运行浏览器。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 浏览器视口尺寸。控制浏览器窗口的大小。设为 'window' 可匹配真实浏览器窗口，而不使用固定尺寸；agent-browser Provider 和通过 CDP 连接时的 Stagehand 支持此设置。 (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): 默认超时时间（毫秒）。每个 Provider 都定义自己的语义和默认值。详情请参阅相应 Provider 参考。

**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL、HTTP 端点或同步/异步 Provider 函数。提供后，会连接现有浏览器，而不是启动新浏览器。HTTP 端点会在内部解析为 WebSocket。不能与 scope: 'thread' 一起使用（会自动使用 shared 作用域）。

**scope** (`'shared' | 'thread'`): 跨线程的浏览器实例作用域。'shared' 表示所有线程共享一个浏览器实例。'thread' 表示每个线程都有自己的浏览器实例（完全隔离）。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 浏览器达到 'ready' 状态后调用的回调。

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 浏览器关闭前调用的回调。

**screencast** (`ScreencastOptions`): 流式传输浏览器帧的配置。

**screencast.format** (`'jpeg' | 'png'`): screencast 帧的图像格式。

**screencast.quality** (`number`): 图像质量（1-100）。仅适用于 JPEG 格式。

**screencast.maxWidth** (`number`): screencast 帧的最大宽度。

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

**screencast.everyNthFrame** (`number`): 每 N 帧捕获一次，以减少带宽。

## 属性

以下属性（`id`、`name`、`provider`）是抽象属性，必须由具体的 Provider 实现定义：

**id** (`string`): 此浏览器实例的唯一标识符。抽象属性，由 Provider 定义。

**name** (`string`): 浏览器 Provider 的人类可读名称（例如 'AgentBrowser'、'StagehandBrowser'）。抽象属性，由 Provider 定义。

**provider** (`string`): Provider 标识符（例如 'vercel-labs/agent-browser'、'browserbase/stagehand'）。抽象属性，由 Provider 定义。

**headless** (`boolean`): 浏览器是否正以无头模式运行。

**status** (`BrowserStatus`): 当前浏览器状态：'pending'、'launching'、'ready'、'error'、'closing' 或 'closed'。

## 方法

### 生命周期

#### `ensureReady()`

确保浏览器已启动并可供使用。在工具执行前自动调用。由基类实现。

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

#### `close()`

关闭浏览器并清理所有资源。由基类实现，并提供避免竞态条件的处理。

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

#### `isBrowserRunning()`

检查浏览器当前是否正在运行。

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

**返回：** `boolean`

### 线程管理

#### `setCurrentThread(threadId)`

设置浏览器操作的当前线程 ID。由 Agent runtime 在内部使用。

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

#### `getCurrentThread()`

获取当前线程 ID。

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

**返回：** `string`

#### `hasThreadSession(threadId)`

检查线程是否有活跃的浏览器 session。

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

**返回：** `boolean`

#### `closeThreadSession(threadId)`

关闭特定线程的浏览器 session。使用 'thread' 作用域时，它会关闭该线程的浏览器实例。使用 'shared' 作用域时，它会清除线程状态。

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

### 工具

#### `getTools()`

返回供 Agent 使用的浏览器工具。每个 Provider 都会根据其模型返回不同的工具。

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

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

### 屏幕串流

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

开始流式传输浏览器帧。返回一个发出帧事件的 `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>`

### 输入注入

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

将鼠标事件注入浏览器。Studio 使用此方法进行实时交互。

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

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

将键盘事件注入浏览器。Studio 使用此方法进行实时交互。

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

### 状态

#### `getState(threadId?)`

获取当前浏览器状态，包括 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>`

## 浏览器作用域

`scope` 选项控制如何跨对话线程共享浏览器实例：

| 作用域        | 描述             | 使用场景          |
| ---------- | -------------- | ------------- |
| `'shared'` | 所有线程共享一个浏览器实例  | 适用于无冲突任务，成本更低 |
| `'thread'` | 每个线程都有自己的浏览器实例 | 为并发用户提供完全隔离   |

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

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

使用 `cdpUrl` 连接外部浏览器时，由于无法生成新的浏览器实例，作用域会自动回退为 `'shared'`。

## 云浏览器 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/reference/browser/agent-browser)：确定性浏览器自动化
- [StagehandBrowser](https://mastra.zisheng.pro/reference/browser/stagehand-browser)：AI 驱动的浏览器自动化
- [Browser 概述](https://mastra.zisheng.pro/docs/browser/overview)：浏览器自动化概念指南