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

# StagehandBrowser クラス

`StagehandBrowser` クラスは、[Stagehand](https://github.com/browserbase/stagehand) を使用した AI 駆動のブラウザ自動化を提供します。要素の refs の代わりに、自然言語の指示を使用して操作します。

AI に自然言語からブラウザ操作を解釈・実行させたい場合は、`StagehandBrowser` を使用します。要素の refs を使用した決定論的な自動化については、[`AgentBrowser`](https://mastra.zisheng.pro/ja/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 キー。env が 'BROWSERBASE' の場合は必須です。

**projectId** (`string`): Browserbase プロジェクト ID。env が 'BROWSERBASE' の場合は必須です。

**model** (`string | ModelConfiguration`): AI 操作用のモデル設定。'openai/gpt-5.5' のような文字列、または modelName、apiKey、baseURL を含むオブジェクトを指定できます。 (Default: `'openai/gpt-5.5'`)

**selfHeal** (`boolean`): 自己修復セレクターを有効にします。有効にすると、最初のセレクターが失敗した場合でも、Stagehand が AI を使用して要素を検出します。 (Default: `true`)

**domSettleTimeout** (`number`): 操作後に DOM が安定するまでのタイムアウト（ミリ秒）。 (Default: `5000`)

**verbose** (`0 | 1 | 2`): ログの詳細レベル。0 = 出力なし、1 = エラーのみ、2 = 詳細。 (Default: `1`)

**systemPrompt** (`string`): AI 操作用のカスタムシステムプロンプト。

**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`): ブラウザ録画 Tool を追加するためのアルファ版オプション。outputDir を指定すると、browser\_record と browser\_record\_caption が Tool セットに追加されます。また、すべての録画に対するデフォルト値として maxDurationMs、maxWidth、maxHeight を設定できます。

**excludeTools** (`StagehandToolName[]`): ブラウザの Tool セットから除外する Tool 名。vision など、特定の機能をサポートしないモデルに対して個別の Tool を無効化するために使用します。

## Tool

`StagehandBrowser` は、ブラウザ自動化用の AI 駆動 Tool を 7 個提供します。

`recording` を設定すると、`StagehandBrowser` はアルファ版の `browser_record` Tool と `browser_record_caption` Tool も追加します。[ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)を参照してください。

コア Tool:

| Tool                   | 説明                                                                      |
| ---------------------- | ----------------------------------------------------------------------- |
| `stagehand_act`        | 自然言語の指示を使用して操作を実行                                                       |
| `stagehand_extract`    | ページから構造化データを抽出                                                          |
| `stagehand_observe`    | ページ上の有用な要素を検出                                                           |
| `stagehand_navigate`   | URL へ移動                                                                 |
| `stagehand_tabs`       | ブラウザタブを管理                                                               |
| `stagehand_screenshot` | PNG 形式でスクリーンショットをキャプチャ（デフォルトはビューポート。ページ全体を対象にするには `fullPage: true` を設定） |
| `stagehand_close`      | ブラウザを閉じる                                                                |

特定の Tool を除外するには、コンストラクターに `excludeTools` を渡します。

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

## Tool リファレンス

### `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`                | vision 機能を有効化（任意）         |
| `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`

ページ上の有用な要素を検出します。セレクターと説明を含む要素のリストを返します。

```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` を設定）。vision 対応モデルが直接解釈できる画像コンテンツを返します。テキストまたは構造化データのみが必要な場合は、`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 |
| ---------- | ----------------- | ---------------- |
| **アプローチ**  | 決定論的な refs（`@e5`） | 自然言語             |
| **精度**     | 要素を正確に指定          | AI による解釈         |
| **柔軟性**    | 最初にスナップショットが必要    | 直接指示             |
| **ユースケース** | 再現可能な自動化          | 適応型の自動化          |
| **速度**     | 高速（AI 推論なし）       | 低速（AI 推論あり）      |

正確で再現可能な自動化には `AgentBrowser` を選択します。柔軟な自然言語による操作には `StagehandBrowser` を選択します。

## 関連項目

- [MastraBrowser](https://mastra.zisheng.pro/ja/reference/browser/mastra-browser): 基底クラスのリファレンス
- [AgentBrowser](https://mastra.zisheng.pro/ja/reference/browser/agent-browser): 決定論的な代替手段
- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview): 概念ガイド
- [Stagehand ガイド](https://mastra.zisheng.pro/ja/docs/browser/stagehand): 使用ガイド