メインコンテンツへ移動

Stagehand

@mastra/stagehand パッケージは、Browserbase の Stagehand SDK を使用したブラウザ自動化を提供します。Stagehand は AI でページのコンテキストを理解して要素を特定するため、明示的なセレクターの代わりに自然言語で指定できます。

Stagehand を使用する場面
Stagehand を使用する場面への直接リンク

次のような場合に Stagehand を使用します。

  • 自然言語による要素指定（「ログインボタンを選択」など）
  • AI を利用したページからのデータ抽出
  • Browserbase クラウドとのネイティブ統合
  • 一般的な操作に対応するシンプルな Tool インターフェース

クイックスタート
クイックスタートへの直接リンク

パッケージをインストールします。

npm install @mastra/stagehand

ブラウザインスタンスを作成し、Agent に割り当てます。

src/mastra/agents/stagehand-agent.ts
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 はページ内容に基づいて構造化データを返します。

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

操作の確認
操作の確認への直接リンク

Agent が stagehand_observe Tool を使用すると、現在のページを分析し、実行可能な操作を返します。

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

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

[
  { "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 を使用してください。

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

Vision をサポートしないモデルでスクリーンショット Tool を無効にするには、excludeTools を使用します。

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

Browserbase
Browserbaseへの直接リンク

Stagehand は、クラウドブラウザインフラストラクチャ向けの Browserbase ネイティブ統合を備えています。

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 リファレンスを参照してください。

録画
録画への直接リンク

Stagehand では、アルファ版のブラウザ録画 Tool をオプトインで有効にできます。

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

これにより、Agent の Tool セットに browser_record と browser_record_caption が追加されます。詳細はブラウザ録画（アルファ版）を参照してください。

On this page