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

# StagehandBrowser 类

`StagehandBrowser` 类使用 [Stagehand](https://github.com/browserbase/stagehand) 提供 AI 驱动的浏览器自动化。它使用自然语言指令进行交互，而不是元素 ref。

希望 AI 根据自然语言解释并执行浏览器操作时，请使用 `StagehandBrowser`。对于使用元素 ref 的确定性自动化，请参阅 [`AgentBrowser`](https://mastra.zisheng.pro/reference/browser/agent-browser)。

## 用法示例

```typescript
import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: true,
  model: 'openai/gpt-5.6-sol',
  selfHeal: true,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You can browse the web using natural language.
Use stagehand_act to perform actions like "click the login button".
Use stagehand_extract to get data from pages.`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## 构造函数参数

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

**viewport** (`{ width: number; height: number } | 'window'`): 浏览器视口尺寸。'window' 会匹配真实浏览器窗口，并且仅在通过 CDP 连接时适用；本地启动的浏览器会回退到默认尺寸。 (Default: `{ width: 1280, height: 720 }`)

**env** (`'LOCAL' | 'BROWSERBASE'`): 运行浏览器的环境。使用 'BROWSERBASE' 在云端执行。 (Default: `'LOCAL'`)

**apiKey** (`string`): Browserbase API key。env 为 'BROWSERBASE' 时必需。

**projectId** (`string`): Browserbase project ID。env 为 'BROWSERBASE' 时必需。

**model** (`string | ModelConfiguration`): AI 操作的模型配置。可以是类似 'openai/gpt-5.5' 的字符串，也可以是包含 modelName、apiKey 和 baseURL 的对象。 (Default: `'openai/gpt-5.5'`)

**selfHeal** (`boolean`): 启用自愈 selector。启用后，即使初始 selector 失败，Stagehand 也会使用 AI 查找元素。 (Default: `true`)

**domSettleTimeout** (`number`): 操作后等待 DOM 稳定的超时时间（毫秒）。 (Default: `5000`)

**verbose** (`0 | 1 | 2`): 日志详细程度。0 = 静默，1 = 仅错误，2 = 详细。 (Default: `1`)

**systemPrompt** (`string`): 用于 AI 操作的自定义 system prompt。

**cdpUrl** (`string | (() => string | Promise<string>)`): 用于连接现有浏览器的 CDP WebSocket URL 或 HTTP 端点。HTTP 端点会在内部解析为 WebSocket。

**scope** (`'shared' | 'thread'`): 跨线程的浏览器实例作用域。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**timeout** (`number`): Stagehand 操作的默认超时时间（毫秒）。 (Default: `30000`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 浏览器准备就绪后调用的回调。

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

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

**recording** (`BrowserRecordingOptions`): 用于添加浏览器录制工具的 Alpha 选项。提供 outputDir 可将 browser\_record 和 browser\_record\_caption 添加到工具集。还可以设置 maxDurationMs、maxWidth 和 maxHeight，作为每次录制的默认值。

**excludeTools** (`StagehandToolName[]`): 要从浏览器工具集中排除的工具名称。对于不支持某些能力（例如视觉）的模型，可用此选项禁用特定工具。

## 工具

`StagehandBrowser` 提供 7 个用于浏览器自动化的 AI 驱动工具。

配置 `recording` 后，`StagehandBrowser` 还会添加 Alpha 版 `browser_record` 和 `browser_record_caption` 工具。请参阅[浏览器录制（Alpha）](https://mastra.zisheng.pro/docs/browser/recording)。

核心工具：

| 工具                     | 描述                                             |
| ---------------------- | ---------------------------------------------- |
| `stagehand_act`        | 使用自然语言指令执行操作                                   |
| `stagehand_extract`    | 从页面中提取结构化数据                                    |
| `stagehand_observe`    | 发现页面中的有用元素                                     |
| `stagehand_navigate`   | 导航到 URL                                        |
| `stagehand_tabs`       | 管理浏览器标签页                                       |
| `stagehand_screenshot` | 截取 PNG 屏幕截图（默认为视口；设置 `fullPage: true` 可截取完整页面） |
| `stagehand_close`      | 关闭浏览器                                          |

要排除特定工具，请在构造函数中传入 `excludeTools`：

```typescript
const browser = new StagehandBrowser({
  excludeTools: ['stagehand_screenshot'],
})
```

## 工具参考

### `stagehand_act`

使用自然语言指令执行操作。AI 会解释你的指令并执行相应的浏览器操作。

```text
// Tool input
{
  "instruction": "click the login button",
  "variables": { "username": "john" },
  "useVision": true,
  "timeout": 30000
}

// With variable substitution
{
  "instruction": "type %email% into the email field",
  "variables": { "email": "user@example.com" }
}
```

| 参数            | 类型                       | 描述                          |
| ------------- | ------------------------ | --------------------------- |
| `instruction` | `string`                 | 自然语言指令（必需）                  |
| `variables`   | `Record<string, string>` | 用于 %variableName% 替换的变量（可选） |
| `useVision`   | `boolean`                | 启用视觉能力（可选）                  |
| `timeout`     | `number`                 | 超时时间（毫秒，可选）                 |

**返回：**

```typescript
interface ActResult {
  success: boolean
  message?: string
  action?: string
  url?: string
}
```

### `stagehand_extract`

使用自然语言指令从页面中提取结构化数据。

```text
// Basic extraction
{
  "instruction": "extract all product names and prices"
}

// With schema for structured output
{
  "instruction": "extract the product information",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" }
    }
  }
}
```

**返回：**

```typescript
interface ExtractResult<T = unknown> {
  success: boolean
  data?: T
  hint?: string
  error?: string
  url?: string
}
```

### `stagehand_observe`

发现页面中的有用元素。返回元素列表及其 selector 和描述。

```text
// Find specific elements
{
  "instruction": "find all buttons related to checkout"
}

// Find all interactive elements
{
  "onlyVisible": true
}
```

| 参数            | 类型        | 描述                 |
| ------------- | --------- | ------------------ |
| `instruction` | `string`  | 自然语言指令（可选，省略时查找全部） |
| `onlyVisible` | `boolean` | 是否仅包含可见元素（可选）      |
| `timeout`     | `number`  | 超时时间（毫秒，可选）        |

**返回：**

```typescript
interface ObserveResult {
  success: boolean
  actions: StagehandAction[]
  url?: string
}

interface StagehandAction {
  selector: string
  description: string
  method?: string
  arguments?: string[]
}
```

### `stagehand_navigate`

导航到 URL。

```text
// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded"
}
```

| 参数          | 类型                                              | 描述            |
| ----------- | ----------------------------------------------- | ------------- |
| `url`       | `string`                                        | 要打开的 URL（必需）  |
| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | 何时将导航视为完成（可选） |

### `stagehand_tabs`

管理浏览器标签页。

```text
// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index (or current if omitted)
{ "action": "close", "index": 1 }
```

### `stagehand_screenshot`

将当前页面截取为 PNG 屏幕截图（默认为视口。设置 `fullPage: true` 可截取完整页面）。返回支持视觉能力的模型可直接解读的图像内容。只需要文本或结构化数据时，请使用 `stagehand_observe` 或 `stagehand_extract`。

```text
// Viewport only (default)

// Full scrollable page
{ "fullPage": true }
```

| 参数         | 类型        | 描述                                  |
| ---------- | --------- | ----------------------------------- |
| `fullPage` | `boolean` | 是否截取完整的可滚动页面，而不是仅截取视口（可选，默认值：false） |

### `stagehand_close`

关闭浏览器并清理资源。

```text
// Tool input (no parameters required)

```

## 使用 Browserbase

使用 Browserbase 在云端运行 Stagehand：

```typescript
const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.6-sol',
})
```

## 模型配置

为 Stagehand 操作配置 AI 模型：

```typescript
// String format: "provider/model"
const browser = new StagehandBrowser({
  model: 'openai/gpt-5.6-sol',
})

// Object format for custom configuration
const browser = new StagehandBrowser({
  model: {
    modelName: 'gpt-5.4',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1',
  },
})
```

## AgentBrowser 与 StagehandBrowser 对比

| 方面       | AgentBrowser   | StagehandBrowser |
| -------- | -------------- | ---------------- |
| **方式**   | 确定性 ref（`@e5`） | 自然语言             |
| **精确度**  | 精确定位元素         | AI 解释            |
| **灵活性**  | 需要先获取快照        | 直接提供指令           |
| **使用场景** | 可复现的自动化        | 自适应自动化           |
| **速度**   | 更快（无 AI 推理）    | 更慢（需要 AI 推理）     |

需要精确、可复现的自动化时，请选择 `AgentBrowser`。需要灵活的自然语言交互时，请选择 `StagehandBrowser`。

## 相关内容

- [MastraBrowser](https://mastra.zisheng.pro/reference/browser/mastra-browser)：基类参考
- [AgentBrowser](https://mastra.zisheng.pro/reference/browser/agent-browser)：确定性替代方案
- [Browser 概述](https://mastra.zisheng.pro/docs/browser/overview)：概念指南
- [Stagehand 指南](https://mastra.zisheng.pro/docs/browser/stagehand)：用法指南