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

# Stagehand

`@mastra/stagehand` 包使用 Browserbase 的 [Stagehand SDK](https://docs.browserbase.com/stagehand/introduction) 提供浏览器自动化。Stagehand 使用 AI 理解页面上下文并定位元素，因此可以使用自然语言描述，而无需显式选择器。

## 何时使用 Stagehand

当你需要以下能力时，请使用 Stagehand：

- 使用自然语言定位元素（“选择登录按钮”）
- 从页面中提取 AI 驱动的数据
- 原生集成 Browserbase 云服务
- 为常用操作提供更简单的 Tool 接口

## 快速开始

安装该包：

**npm**:

```bash
npm install @mastra/stagehand
```

**pnpm**:

```bash
pnpm add @mastra/stagehand
```

**Yarn**:

```bash
yarn add @mastra/stagehand
```

**Bun**:

```bash
bun add @mastra/stagehand
```

创建浏览器实例并将其分配给 Agent：

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

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

export const stagehandAgent = new Agent({
  id: 'stagehand-agent',
  name: 'Stagehand Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

Use stagehand tools to interact with pages:
- stagehand_navigate to go to URLs
- stagehand_act to perform actions described in natural language
- stagehand_extract to get structured data from the page
- stagehand_observe to find available actions on the page
- stagehand_screenshot to visually inspect the page`,
})
```

## 自然语言操作

Agent 使用 `stagehand_act` Tool 时，该 Tool 接受操作的自然语言描述：

- “按下登录按钮”
- “在电子邮件字段中输入 `'[user@example.com](mailto:user@example.com)'`”
- “从国家/地区下拉列表中选择‘美国’”

Stagehand 的 AI 会解读操作，并在页面上找到相应元素。

## 数据提取

Agent 使用 `stagehand_extract` Tool 时，可以从页面提取结构化数据。

指令示例：“提取产品名称、价格和库存状态”

Tool 会根据页面内容返回结构化数据：

```json
{
  "name": "Widget Pro",
  "price": "$29.99",
  "availability": "In Stock"
}
```

## 观察操作

Agent 使用 `stagehand_observe` Tool 时，该 Tool 会分析当前页面并返回可执行的操作。

指令示例：“我可以在此登录表单上执行哪些操作？”

返回可用操作列表：

```json
[
  { "action": "Press 'Sign In' button", "element": "button" },
  { "action": "Type in 'Email' field", "element": "input" },
  { "action": "Open 'Forgot Password' link", "element": "a" }
]
```

## 截图

当 Agent 使用 `stagehand_screenshot` Tool 时，它会捕获当前页面的 PNG 图像，并以支持视觉的模型可直接解读的图像内容形式返回。

需要直观检查页面（例如评估图像、布局或颜色）时，请使用截图。对于文本或结构化数据，请改用 `stagehand_extract` 或 `stagehand_observe`。

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

要为不支持视觉的模型禁用截图 Tool，请使用 `excludeTools`：

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  excludeTools: ['stagehand_screenshot'],
})
```

## Browserbase

Stagehand 原生集成 Browserbase 云浏览器基础设施：

```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',
})
```

有关所有配置选项，请参阅 [StagehandBrowser 参考](https://mastra.zisheng.pro/reference/browser/stagehand-browser)。

## 录制

Stagehand 可选择启用 alpha 版浏览器录制 Tool：

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  recording: {
    outputDir: './browser-recordings',
  },
})
```

这会向 Agent 的 Tool 集添加 `browser_record` 和 `browser_record_caption`。有关详细信息，请参阅[浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)。

## 相关内容

- [Browser 概览](https://mastra.zisheng.pro/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser)
- [浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)
- [StagehandBrowser 参考](https://mastra.zisheng.pro/reference/browser/stagehand-browser)