> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 可接受以自然語言描述的操作：

- 「按下 Sign In 按鈕」
- 「在電郵欄位輸入 `'[user@example.com](mailto:user@example.com)'`」
- 「在國家／地區下拉式選單中選取 'United States'」

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 時，該 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/zh-HK/reference/browser/stagehand-browser)。

## 錄製

Stagehand 可選擇啟用 alpha 階段的瀏覽器錄製 Tool：

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

這會將 `browser_record` 及 `browser_record_caption` 加入 Agent 的 Tool 集合。詳情請參閱[瀏覽器錄製（alpha）](https://mastra.zisheng.pro/zh-HK/docs/browser/recording)。

## 相關內容

- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/zh-HK/docs/browser/agent-browser)
- [瀏覽器錄製（alpha）](https://mastra.zisheng.pro/zh-HK/docs/browser/recording)
- [StagehandBrowser 參考資料](https://mastra.zisheng.pro/zh-HK/reference/browser/stagehand-browser)