Stagehand v3
自然言語ベースのブラウザ自動化 — act（実行）・extract（抽出）・observe（観察）・agent（エージェント）という4つの基本要素
- 4つの主要なプリミティブ —
act()、extract()、observe()、agent()：act()は、自然言語による指示（「ログインボタンをクリック」など）で単一のブラウザアクションを実行し、extract()はZodスキーマに基づいてページから構造化されたデータを抽出し、observe()は現在のページで実行可能なアクションのリストを事前に探索し、agent()は多段階のワークフローを自律的に実行します。これら4つを組み合わせることで、決定的なステップ制御と自律エージェントの実行を1つのSDKに統合します。 - v3アーキテクチャのリライト — Playwright内部依存性の削除：v3では、内部のPlaywright依存性を完全に削除し、CDP（Chrome DevTools Protocol）エンジンと直接通信する構造に移行します。Playwright、Puppeteer、Patchrightの中から選択してバックエンドとして使用できます。
act()、extract()、observe()全体で20〜40％の速度向上を達成します。 - 3つのエージェントモード — CUA、DOM、ハイブリッド：CUA（Computer Use Agent）モードは、視覚ベースの座標クリックで画面を直接認識し、DOMモードはアクセシビリティツリーの分析によってセマンティックアクションを実行し、ハイブリッドモード（v3.4.0からデフォルト）は、視覚とDOMを組み合わせて、精度と速度を同時に確保します。互換性のないモデルは、自動的にDOMモードにルーティングされます。
- 複数のLLMプロバイダーのサポート：Vercel AI SDKをベースに、OpenAI、Anthropic（Claude）、Google Geminiなどの主要なプロバイダーを自由に切り替えることができます。Computer Use APIは、Anthropic、OpenAI、Google、Microsoftすべてをサポートします。Browserbaseを使用する場合、Model Gatewayを通じて単一のAPIキーで、すべてのサポート対象モデルにアクセスできます。
- セルフヒーリング（Self-Healing）の自動化：自然言語ベースの指示は、実行時にAIによって解釈されるため、Webサイトのマークアップが変更されても、スクリプトが自動的に適応します。CSSセレクターのハードコーディング方式と比較して、メンテナンスコストを根本的に削減します。v3では、Shadow DOM（オープン/クローズドモードの両方）とiFrameの自動トラバーサルが追加されました。
- アクションキャッシュシステム：Browserbaseサーバーサイドキャッシュ（指示+ページコンテンツに基づくキャッシュキー、HIT時に100ms未満の応答）とローカルファイルキャッシュ（
cacheDir設定）の二重構造です。v3の自動アクションキャッシュは、CUAの実行を推論を必要としない決定的なスクリプトに自動的に変換できます。 - v3の新機能である非AIプリミティブ：
page、locator、frameLocator、deepLocator（iFrame + Shadow Rootのクロス探索）—AI推論なしで、直接DOMを制御する必要がある場合に使用します。従来の自動化ツールの精度とAIの柔軟性を、1つのSDK内で選択的に活用できます。 - カスタムツールとMCPの統合：
agent()にユーザー定義のツールを注入することで、メールの送信、外部APIの呼び出しなど、ブラウザ外のアクションを実行できます。MCP（Model Context Protocol）サーバーのURLをintegrations配列として渡すことで、外部ツールエコシステムに即座に接続できます。 - フレームワークとの統合：CrewAI、LangChain JS、Playwright、Puppeteer、Selenium、Next.js/Vercel、Convexなどの主要な自動化・Webフレームワークと直接連携します。Bunランタイムもv3から公式にサポートされます。
💻 必要なスペック
不要（すべてのLLM推論は外部APIプロバイダーに委任されます）
npmパッケージを基準にすると、数十MB程度です。ローカルキャッシュを有効にすると、キャッシュファイルの蓄積に応じて追加のスペースが必要になります（数百MB以内）
⚡ インストール
4-1. 簡単な始め方
# TypeScript — プロジェクトのスケルトン作成（推奨）
npx create-browser-app
# TypeScript — 既存のプロジェクトへの追加
npm install @browserbasehq/stagehand
# Python
pip install stagehand
# または uv を使用する場合
uv pip install stagehand
4-2. 基本的な使用例（TypeScript）
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";
const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");
// 単一のアクションを実行
await stagehand.act("click on the stagehand repo");
// 構造化されたデータの抽出（Zod スキーマ）
const { author, title } = await stagehand.extract(
"extract the author and title of the PR",
z.object({
author: z.string().describe("The username of the PR author"),
title: z.string().describe("The title of the PR"),
}),
);
// 複数段階の自律エージェント
const agent = stagehand.agent({
provider: "anthropic",
model: "claude-sonnet-4-6",
});
await agent.execute("Get to the latest PR");
4-3. 環境変数の設定
# .env ファイル
BROWSERBASE_API_KEY=your_api_key # Browserbase クラウドを使用する場合
OPENAI_API_KEY=your_key # OpenAI モデルを使用する場合
ANTHROPIC_API_KEY=your_key # Anthropic モデルを使用する場合
GOOGLE_API_KEY=your_key # Gemini モデルを使用する場合
🧬 バイオ活用シナリオ
本番環境向けウェブスクレイピングパイプライン
APIを提供しないウェブサイトから、構造化されたデータを定期的に収集する自動化パイプラインを構築。observe()でページ構造を事前に探索し、extract()にZodスキーマを渡して、価格、在庫、レビューなどをJSON構造で抽出。自己修復機能により、対象サイトのUI変更があっても、スクリプトを修正することなく継続的に運用可能。キャッシュヒット時には100ms未満の応答で、大量のページ処理時にトークンコストを最大90%削減
E2Eテスト自動化の高度化
従来のPlaywright/Seleniumテストが、セレクターの変更ごとに壊れる問題を解決。 「ログイン → 商品検索 → カートに追加 → 決済」のような主要なユーザーフローを自然言語で記述すると、AIが実行時に要素を識別して実行。ハイブリッドモード（v3.4.0のデフォルト）でDOMベースの高速で決定的なテストを実行し、互換性のないモデルを使用する場合は、自動的にDOMモードにフォールバックして安定性を確保
ブラウザベースのRPAエージェント
agent()プリミティブにカスタムツールを注入して、ブラウザ自動化とビジネスロジックを統合したRPAエージェントを構築。 例：毎日特定のポータルにログインしてレポートをダウンロードし、データを抽出してメールで送信するワークフローを、agent()の1回の呼び出しで自律的に実行。MCP統合により、Slack通知、データベース保存などの後続アクションもエージェント内で直接処理
FAQ
Stagehand v3とは何ですか？
4つの主要なプリミティブ — act()、extract()、observe()、agent()：act()は、自然言語による指示（「ログインボタンをクリック」など）で単一のブラウザアクションを実行し、extract()はZodスキーマに基づいてページから構造化されたデータを抽出し、observe()は現在のページで実行可能なアクションのリストを事前に探索し、agent()は多段階のワークフローを自律的に実行します。これら4つを組み合わせることで、決定的なステップ制御と自律エージェントの実行を1つのSDKに統合します。 v3アーキテクチャのリライト — Playwright内部依存性の削除：v3では、内部のPlaywright依存性を完全に削除し、CDP（Chrome DevTools Protocol）エンジンと直接通信する構造に移行します。Playwright、Puppeteer、Patchrightの中から選択してバックエンドとして使用できます。act()、extract()、observe()全体で20〜40％の速度向上を達成します。 3つのエージェントモード — CUA、DOM、ハイブリッド：CUA（Computer Use Agent）モードは、視覚ベースの座標クリックで画面を直接認識し、DOMモードはアクセシビリティツリーの分析によってセマンティックアクションを実行し、ハイブリッドモード（v3.4.0からデフォルト）は、視覚とDOMを組み合わせて、精度と速度を同時に確保します。互換性のないモデルは、自動的にDOMモードにルーティングされます。 複数のLLMプロバイダーのサポート：Vercel AI SDKをベースに、OpenAI、Anthropic（Claude）、Google Geminiなどの主要なプロバイダーを自由に切り替えることができます。Computer Use APIは、Anthropic、OpenAI、Google、Microsoftすべてをサポートします。Browserbaseを使用する場合、Model Gatewayを通じて単一のAPIキーで、すべてのサポート対象モデルにアクセスできます。 セルフヒーリング（Self-Healing）の自動化：自然言語ベースの指示は、実行時にAIによって解釈されるため、Webサイトのマークアップが変更されても、スクリプトが自動的に適応します。CSSセレクターのハードコーディング方式と比較して、メンテナンスコストを根本的に削減します。v3では、Shadow DOM（オープン/クローズドモードの両方）とiFrameの自動トラバーサルが追加されました。 アクションキャッシュシステム：Browserbaseサーバーサイドキャッシュ（指示+ページコンテンツに基づくキャッシュキー、HIT時に100ms未満の応答）とローカルファイルキャッシュ（cacheDir設定）の二重構造です。v3の自動アクションキャッシュは、CUAの実行を推論を必要としない決定的なスクリプトに自動的に変換できます。 v3の新機能である非AIプリミティブ：page、locator、frameLocator、deepLocator（iFrame + Shadow Rootのクロス探索）—AI推論なしで、直接DOMを制御する必要がある場合に使用します。従来の自動化ツールの精度とAIの柔軟性を、1つのSDK内で選択的に活用できます。 カスタムツールとMCPの統合：agent()にユーザー定義のツールを注入することで、メールの送信、外部APIの呼び出しなど、ブラウザ外のアクションを実行できます。MCP（Model Context Protocol）サーバーのURLをintegrations配列として渡すことで、外部ツールエコシステムに即座に接続できます。 フレームワークとの統合：CrewAI、LangChain JS、Playwright、Puppeteer、Selenium、Next.js/Vercel、Convexなどの主要な自動化・Webフレームワークと直接連携します。Bunランタイムもv3から公式にサポートされます。
Stagehand v3はいつ使いますか？
自然言語ベースのブラウザ自動化 — act（実行）・extract（抽出）・observe（観察）・agent（エージェント）という4つの基本要素
Stagehand v3のバイオ研究での活用例は何ですか？
本番環境向けウェブスクレイピングパイプライン: APIを提供しないウェブサイトから、構造化されたデータを定期的に収集する自動化パイプラインを構築。observe()でページ構造を事前に探索し、extract()にZodスキーマを渡して、価格、在庫、レビューなどをJSON構造で抽出。自己修復機能により、対象サイトのUI変更があっても、スクリプトを修正することなく継続的に運用可能。キャッシュヒット時には100ms未満の応答で、大量のページ処理時にトークンコストを最大90%削減
📝 アップデートノート
まだアップデートノートはありません。
🧪 関連「生命のコード」
関連する「生命のコード」記事はまだありません。