> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/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 を使用すると、自然言語による操作の説明を受け取ります。

- 「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 を使用すると、現在のページを分析し、実行可能な操作を返します。

指示の例: 「このログインフォームではどのような操作が可能ですか？」

利用可能な操作の一覧が返されます。

```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 画像としてキャプチャし、Vision 対応モデルが直接解釈できる画像コンテンツとして返します。

画像、レイアウト、色など、ページを視覚的に確認する必要がある場合はスクリーンショットを使用します。テキストや構造化データには、代わりに `stagehand_extract` または `stagehand_observe` を使用してください。

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

Vision をサポートしないモデルでスクリーンショット 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/ja/reference/browser/stagehand-browser)を参照してください。

## 録画

Stagehand では、アルファ版のブラウザ録画 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` が追加されます。詳細は[ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)を参照してください。

## 関連情報

- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/ja/docs/browser/agent-browser)
- [ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)
- [StagehandBrowser リファレンス](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser)