PlaywrightにAI機能を追加したStagehandとはなにか?

## 1. Stagehandの機能詳細

**Stagehandとは:**  
Stagehandは、Webブラウザを自動操作するためのAI搭載フレームワークです。Playwright（Microsoft製のブラウザ自動化ライブラリ）を基盤として拡張しており、自然言語で指示を与えるだけでブラウザ操作を実行できる点が特徴です ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20is%20the%20easiest%20way,web%20automation%20via%20natural%20language))。Stagehand自体は「インターネットへのAIインタフェース」と位置付けられており、複雑な抽象化を避けつつモデルに依存しない軽量なフレームワークを目指しています ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=What%20is%20Stagehand%3F))。例えば「ログインボタンをクリックして」「ページの価格情報を取得して」といった**自然言語の指示**を与えると、裏側で適切なPlaywrightのコード（操作手順）を生成・実行してくれます ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=will%20help%20you%20execute%20steps,click%20the%20order%20button))。これにより、通常は手作業でセレクタやスクリプトを書くようなブラウザ操作を、簡潔な指示だけで実現できます。

**主な機能:**  
StagehandはPlaywrightの`Page`クラスを拡張し、以下の3つのAI支援APIを提供します ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20is%20the%20easiest%20way,web%20automation%20via%20natural%20language))。

- **`act()`** – 指定した動作をページ上で実行します。例えば`act("Add to cartボタンをクリック")`のように**ユーザー操作（クリックや入力など）**を自然言語で記述できます ([Act -  Stagehand](https://docs.stagehand.dev/reference/act#:~:text=,Browserbase%27%20into%20the%20search%20bar))。Stagehandはその指示を達成するためのPlaywrightアクションをLLM（大規模言語モデル）で生成し、実行します ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=Each%20Stagehand%20function%20takes%20in,that%20instruction%2C%20and%20executes%20it))。大きな動作を一度に行わせるより、**単一の明確な操作（アトミックな指示）**に分けることで信頼性が高まります ([Act -  Stagehand](https://docs.stagehand.dev/reference/act#:~:text=,Browserbase%27%20into%20the%20search%20bar))。  
- **`extract()`** – ページから情報を抽出します。`extract()`には「ページの説明文を抽出して」といった**データ抽出の指示**を与え、さらにオプションで抽出結果の構造（スキーマ）を指定できます ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=%2F%2F%20Stagehand%20AI%3A%20Extract%20data,description%3A%20z.string%28%29%2C%20%7D%29%2C))。Stagehandはページ内容を分析し、指定されたスキーマに沿ったデータ（例えばテキストや数値）をLLMで抽出します。これにより、手動でDOMをパースして情報を取り出す手間を軽減できます。  
- **`observe()`** – 現在のページ上で「取りうる操作」の候補を一覧取得します。`observe()`を呼び出すと、Stagehandは現在ページ内でユーザーが操作可能な要素を探索し、それぞれに対応するXPathセレクタと短い説明文を返します ([Observe -  Stagehand](https://docs.stagehand.dev/reference/observe#:~:text=,of%20what%20page%20you%E2%80%99re%20on))。任意の指示を与えて特定の種類の要素だけを探すこともでき（例: `observe({ instruction: "このページ上のボタンを探す" })`）、その場合は該当する要素のセレクタと説明だけが得られます ([Observe -  Stagehand](https://docs.stagehand.dev/reference/observe#:~:text=,description))。この機能は、後述するような**エージェントの文脈把握**（今どのページにいて何ができるか確認する）に役立ちます。

**用途とユースケース:**  
Stagehandは「ブラウザで人間が行うあらゆる操作」を自動化できることを目指しています ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=Anything%20that%20can%20be%20done,Think%20about%20stuff%20like))。具体的なユースケースとして、公式ドキュメントでは次のような例が挙げられています ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=Anything%20that%20can%20be%20done,Think%20about%20stuff%20like)):

- Amazonにログインし、「AirPods」で検索して最も関連性の高い商品を購入する  
- Hacker Newsにアクセスして、その日のトップ記事を一覧取得する  
- 出前サービスサイト（Doordashなど）で一番安いパッタイを見つけて注文する  

これらはいずれもPlaywrightなどの従来手法でも実現可能ですが、**Stagehandでは自然言語で指示を記述できるためコード記述が大幅に簡略化**されます ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=These%20automations%20can%20be%20built,minor%20changes%20in%20the%20UI))。さらに、LLMによる柔軟な要素指定のおかげでUIの細かな変更にも強く、**自動回復的（セルフヒーリング）に動作する堅牢なスクリプト**を構築できる点がメリットです ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20adds%20determinism%20to%20otherwise,unpredictable%20agents))。公式も「Stagehandを使えば、単一サイトごとに都度スクリプトを書き直すのではなく、耐久性・自己修復性・再現性の高いワークフローを記述できる」と謳っています ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20adds%20determinism%20to%20otherwise,unpredictable%20agents))。

また、Stagehandは**Browserbase**というプラットフォームとシームレスに統合できるよう設計されています ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=Stagehand%20is%20the%20easiest%20way,has%20seamless%20integration%20with%20Browserbase))。Browserbaseはステルスモード（自動化検知の回避）やCAPTCHA突破、コンテキスト永続化（ログイン状態の保持）など高度な機能を提供しており、Stagehandと組み合わせることで**ボット検知やCAPTCHAを回避**しながら自動操作を行うことも可能です ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=These%20automations%20can%20be%20built,minor%20changes%20in%20the%20UI)) ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Browserbase))。このように、Stagehandは単体でも強力ですが、サービス連携によりさらに実践的なWebエージェントの構築を支援します。

## 2. Playwrightとの比較

Stagehandは「Playwrightの後継（natural successor）」とも称されるように、Playwrightと密接な関係にあります ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=What%20is%20Stagehand%3F))。そこで、従来のPlaywrightとStagehandの**違い**や**長所・短所**を比較します。

### StagehandとPlaywrightの主要な違い

- **操作手法:** Playwrightが**コードによる明示的操作**（DOMセレクタ指定やメソッド呼び出し）を必要とするのに対し、Stagehandは**自然言語による操作指示**が可能です ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20is%20the%20easiest%20way,web%20automation%20via%20natural%20language))。開発者は「○○をクリック」「△△を抽出して」と書くだけでよく、Stagehand内部でLLMが適切なPlaywrightコードに翻訳してくれます ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=will%20help%20you%20execute%20steps,click%20the%20order%20button))。  
- **AI活用:** Stagehandは内部にLLM（GPT-4やClaudeなど）を用いる点でPlaywrightと大きく異なります。これによりUI変化への適応力（ロバスト性）が高く、固定のXPathやCSSセレクタに頼るPlaywright単独より**小さなUI変更に強い（自己修復的）**と期待されています ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20adds%20determinism%20to%20otherwise,unpredictable%20agents))。一方で、LLMに依存するため**応答速度**や**コスト（API利用料）**の面ではトレードオフがあります。  
- **対象ユーザと用途:** Playwrightは元々**Webアプリのテスト自動化**向けに設計されており、高速かつ再現性重視のシナリオ（自社サイトの回帰テストなど）に適しています。一方Stagehandは**汎用的なWebエージェント開発**を意図しており、変化の多い他社サイトのスクレイピングや自動操作、あるいはチャットボットにブラウザ操作能力を与えるといった用途に向いています ([Interesting, thanks for the feedback! By "taking the place of Playwright," we do... | Hacker News](https://news.ycombinator.com/item?id=42640303#:~:text=Rather%2C%20we%20want%20Stagehand%20to,hard%20to%20deterministically%20code%20against))。開発者の声としても、「安定したQA用途ならPlaywrightのままの方が良いが、頻繁にDOM構造が変わったりポップアップが出るようなサイト相手ではStagehandが有効」という意見があります ([Interesting, thanks for the feedback! By "taking the place of Playwright," we do... | Hacker News](https://news.ycombinator.com/item?id=42640303#:~:text=Rather%2C%20we%20want%20Stagehand%20to,hard%20to%20deterministically%20code%20against))。  
- **プログラミング言語サポート:** Playwrightは公式にJavaScript/TypeScriptだけでなくPython、Java、.NETなど複数言語版が提供されています。一方Stagehandは2024年末時点で**Node.js（JavaScript/TypeScript）専用**のSDKです。つまり**Stagehandを使うにはNode.js環境が必須**であり（推奨Node v20+ ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Prerequisites))）、Pythonなど他言語から直接利用することはできません（※将来的な対応可能性はありますが未発表）。  
- **学習コスト:** StagehandはPlaywright互換のため基本的なブラウザ操作（遷移やクリック等）の概念は共通しています。しかし**自然言語プロンプトの質**がスクリプトの成否に影響する点が新たな学習要素です。適切に指示を細分化する、LLMが誤解しにくい表現を使う、といった**プロンプトエンジニアリング的な知見**が必要になる場合があります。一方Playwrightは純粋にプログラミング上の知識（DOM構造やCSSセレクタの理解）が求められます。  

### StagehandとPlaywrightの長所・短所

双方の特徴をまとめると以下のようになります。

| **項目**                     | **Stagehand**                                                                                 | **Playwright**                                                                     |
|----------------------------|----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| **操作方法**               | 自然言語による高レベル指示でブラウザを操作 ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20is%20the%20easiest%20way,web%20automation%20via%20natural%20language))。<br>（内部でLLMがPlaywrightコードを生成） | コードによる手動操作（DOMセレクタや明示的コマンドを記述）。                          |
| **UI変更への耐性**         | LLMの柔軟な認識により**UI変更に対して堅牢**。要素の文脈や意味から判断するため小さな変更ならスクリプトが壊れにくい ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20adds%20determinism%20to%20otherwise,unpredictable%20agents))。 | **UI変更に弱い**。ハードコーディングしたセレクタがページ改変で無効になると手直しが必要。 |
| **依存環境**               | **LLMへの依存**あり：OpenAIやAnthropicのAPIキーやモデル選択が必要 ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Large%20Language%20Models))。<br>Node.jsランタイム上で動作。 | **追加依存なし**：Playwright自体とブラウザバイナリだけで動作。<br>（Node/Pythonなど各対応言語のランタイム） |
| **実行速度**               | LLMへの問い合わせ時間が加算されるため**単純な操作でも遅延**が発生しうる。<br>キャッシュ機能で同一指示の繰返し時は応答短縮可能 ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=enableCaching))。 | コードを直接実行するため**高速**。待ち時間は主にネットワークやページロード時間のみ。 |
| **ユースケース適性**       | **第三者サイトの操作やスクレイピングに適性◎**：変化の多い環境や未知のサイト上で自律的に動作するWebエージェント開発に有用 ([Interesting, thanks for the feedback! By "taking the place of Playwright," we do... | Hacker News](https://news.ycombinator.com/item?id=42640303#:~:text=Rather%2C%20we%20want%20Stagehand%20to,hard%20to%20deterministically%20code%20against))。<br>CAPTCHA回避やログイン維持など高度機能（Browserbase連携）も利用可 ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Browserbase))。 | **自社サイトのテストや定型操作に適性◎**：安定した環境で決まった手順を繰り返すQA、自動テスト、RPA的シナリオに向く。<br>（外部サイトではbot検知等に引っかかる可能性） |
| **学習・実装の負担**       | **低コーディング**：操作内容の記述は平易だが、最適な指示の工夫やエラー時の例外対応など**プロンプト設計**の知見が必要。<br>早期リリース版につき変更もあり得る ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=,latest%20developments%20and%20provide%20feedback))。 | **コード記述量**は多めだが、従来のプログラミング知識で完結。フレームワークとして成熟しており安定。 |
| **その他の特徴**           | Browserbaseプラットフォーム上で実行すれば**ステルスモード**による自動検知回避や拡張機能の利用が可能 ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=These%20automations%20can%20be%20built,minor%20changes%20in%20the%20UI)) ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Browserbase))。<br>LLMモデルを差し替える柔軟性（カスタムモデルクライアントの実装）もあり ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Stagehand%20supports%20custom%20models%20by,interface))。 | Microsoftが開発し活発にメンテナンス。マルチブラウザ（Chromium/WebKit/Firefox）対応、豊富なAPI。<br>ヘッドレスブラウザ操作のデファクトスタンダードの一つ。 |

**Stagehandが適しているケース:** 上記の比較から、**不特定多数のWebサイトを横断的に操作したい場合**や、**UIの変更や動的コンテンツが多く人手でセレクタ管理しづらい場合**にStagehandは力を発揮します ([Interesting, thanks for the feedback! By "taking the place of Playwright," we do... | Hacker News](https://news.ycombinator.com/item?id=42640303#:~:text=Rather%2C%20we%20want%20Stagehand%20to,hard%20to%20deterministically%20code%20against))。たとえばスクレイピングクローラや、ユーザの質問に応じてWeb検索・操作を行うような**自律エージェント**の構築では、Stagehandの自然言語操作と柔軟性が大いに役立ちます。「多少時間がかかってもよいので、広範なサイトに対応できる汎用的なブラウザ操作ツールが欲しい」というケースにマッチすると言えるでしょう。

**Playwrightが適しているケース:** 対照的に、**操作対象や手順があらかじめ明確で安定している場合**や、**テスト自動化のように厳密な再現性と速度が重要な場合**は、従来どおりPlaywright単体を用いる方が適しています ([Interesting, thanks for the feedback! By "taking the place of Playwright," we do... | Hacker News](https://news.ycombinator.com/item?id=42640303#:~:text=deterministically%20code%20against))。自社運用のWebアプリを毎回決まったステップでテストする場合、LLMを介在させるメリットは小さく、むしろオーバーヘッドや予測不能な要素が増えるためです。また**日本語を含む特殊な操作**については、StagehandのLLMが正しく認識・処理できるか注意が必要です（LLMの言語対応状況に依存）。そのため、確実性を重視するシナリオではPlaywrightのように**人間が制御するコードベース**の方が安心と言えるでしょう。

## 3. 技術的詳細

ここでは、Stagehandの内部構造や技術的な仕組みについて概要から少し踏み込んで説明します。

**Playwright上に構築:**  
前述のとおり、Stagehandは内部でPlaywrightを利用しています。具体的には、Stagehandを初期化すると**Playwrightのブラウザコンテキストとページが生成**され、Stagehandインスタンスの`page`や`context`プロパティとして提供されます ([Playwright Interoperability -  Stagehand](https://docs.stagehand.dev/reference/playwright_interop#:~:text=,instance%20that%20Stagehand%20is%20using))。この`stagehand.page`は実質的にPlaywrightの`Page`オブジェクトそのもので、通常の`page.goto()`や`page.click()`といった**既存のPlaywrightメソッドもそのまま利用可能**です ([Playwright Interoperability -  Stagehand](https://docs.stagehand.dev/reference/playwright_interop#:~:text=Stagehand%20is%20built%20on%20top,directly%20through%20the%20Stagehand%20instance))。加えて、Stagehandはこの`Page`オブジェクトに対して`act()`や`extract()`等の拡張メソッドを差し込み、AI経由の操作を実現しています ([Playwright Interoperability -  Stagehand](https://docs.stagehand.dev/reference/playwright_interop#:~:text=%2F%2F%20Base%20Playwright%20methods%20work,https%3A%2F%2Fgithub.com%2Fbrowserbase%2Fstagehand))。したがって、Stagehandを導入しても**既存のPlaywrightコード資産は活かしつつ**、必要な部分だけAI操作に置き換えるといった統合的な使い方が可能です。

**LLMによる操作コード生成:**  
Stagehandの肝となるのが、ユーザから与えられた自然言語指示を**LLM（大規模言語モデル）で解析し、対応するブラウザ操作コードに変換するプロセス**です ([Introduction -  Stagehand](https://docs.stagehand.dev/get_started/introduction#:~:text=will%20help%20you%20execute%20steps,click%20the%20order%20button))。各`act`/`extract`/`observe`の呼び出し毎に、この変換プロセスが内部で行われます。例えば`act("ログインボタンをクリック")`と呼ぶと、Stagehandは現在のページ内容を分析しながら「どの要素に対するクリックか」をLLMに判断させ、その要素をクリックするPlaywrightコード（例: `page.click('xpath=...')`）を生成します ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=In%20the%20case%20of%20action%2C,APIs%2C%20possibly%20due%20to%20tokenization))。Stagehand開発チームの検証では、LLMに**「Playwrightのコードで答えさせる」**方が純粋なブラウザAPI操作をさせるより効果的であったと報告されています ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=In%20the%20case%20of%20action%2C,APIs%2C%20possibly%20due%20to%20tokenization))。生成されたコード（または選択された要素セレクタ）は、Stagehandによって実行され、実際のブラウザ操作が行われます。  

**DOMの前処理と要素特定:**  
LLMにページ操作を指示する際、入力（プロンプト）としてページのどの情報を渡すかが重要になります。Stagehandでは性能と信頼性を高めるため、**DOMツリーの前処理（加工）**を行ってからLLMに渡しています ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=1,current%20state%20of%20the%20DOM))。その大まかな手順は以下の通りです ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=The%20DOM%20Processing%20steps%20look,as%20follows)) ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=,be%20analyzed%20by%20the%20LLM))。

1. **スクリプト挿入:** Playwright経由でページ内に補助スクリプトを挿入し、DOM解析ができる環境を用意。  
2. **候補要素の収集:** ページDOMを走査し、「候補要素」のリストを作成。候補要素とは、人間の目に触れる**コンテンツを含むリーフ要素**（テキストノード等）か、**クリックや入力が可能なインタラクティブ要素**です ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=run%20processing,faithfully%20act%20on%20on%20behalf))。例えばボタンやリンク、入力フィールド、および見出しや段落テキストなどが含まれます。  
3. **不要要素の除外:** 候補要素のうち、**非活性・非表示**なものや現在表示領域にないものは除去します ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=,able%20to%20reliably%20target%20it))。これによってLLMが操作不能な要素に惑わされないようにします。  
4. **一意なセレクタの割当て:** 残った各候補要素に対し、一意にその要素を指し示す**XPathセレクタ**を生成します ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=,be%20analyzed%20by%20the%20LLM))。このXPathは後でLLMが特定の要素を選んだ際に、確実にその要素をPlaywrightで操作するために使用されます。  
5. **LLMへの入力準備:** 最終的に、候補要素のリスト（要素のテキスト内容や属性の簡易記述と対応XPathのマッピング）を作成し、それをもって**LLMへのプロンプト入力**とします ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=4,be%20analyzed%20by%20the%20LLM))。例えば「候補1: 『ログイン』ボタン (xpath=...); 候補2: パスワード入力欄 (xpath=...); ...」のような形で、ページ上の要素一覧をLLMに提示します。

このように要素をあらかじめ絞り込むことで、**LLMが検討すべき選択肢の数を減らし、応答の精度と速度を向上**させています。特に近年のLLMは長大な入力に耐えうるとはいえ、無関係な情報が多いよりは絞った方が安定するため、Stagehandは**DOM情報の抽出と要約**に注力しています ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=Chunking))。

**チャンク分割 (Chunking):**  
上記のDOM前処理では、ページ全体を一度に処理せず**表示領域ごとに複数のチャンク（塊）に分割**して要素候補を集める工夫も行われます ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=Chunking))。これはLLMに渡すテキスト量を抑え、文脈を局所化することで判断を誤りにくくするためです ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=While%20LLMs%20will%20continue%20to,diagram%20for%20how%20it%20looks))。たとえばページが縦長の場合、スクロール位置ごとに区切って候補要素リストを作成し、それぞれ順にLLMに処理させるといった動作をします（この際、次チャンクに進むべき指示をLLM自身に書かせて管理する仕組みも組み込まれています ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=tokenization))）。将来的にはチャンク間の関連情報を保管する「前後の文脈パディング」も検討されているとのことです ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=reliable,diagram%20for%20how%20it%20looks))。

**Vision（画像解析）機能:**  
StagehandはデフォルトではテキストベースでDOM解析・要素特定を試みますが、LLMが正しく要素を特定できなかった場合に備えて**画像ベースの解析（Vision）**もサポートしています。`act()`や`observe()`のオプションで`useVision: true`を指定すると、その時点のページスクリーンショットに要素位置の注釈を付けた画像をLLMに入力として与えます ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=Vision))。このVision機能は、DOM構造が複雑でテキストだけでは要素間の関係を把握しにくい場合に有効です。デフォルト設定では`useVision: "fallback"`となっており、**通常はまずテキストで試行し、失敗した場合に自動で画像モードに切り替えて再実行**するようになっています ([How Stagehand Works -  Stagehand](https://docs.stagehand.dev/get_started/walkthrough#:~:text=The%20,retry%20the%20attempt%20using%20vision))。このようにテキスト＋画像の両面からアプローチすることで、LLMによる誤判断のリスクを下げ、より確実に指示を遂行できるよう工夫されています。

**対応モデルとカスタマイズ性:**  
Stagehandは内部で利用するLLMとして、**OpenAI社やAnthropic社の最新モデル**をサポートしています ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Stagehand%20currently%20supports%20the%20latest,models%20from%20OpenAI%20and%20Anthropic)) ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Anthropic%20Models))。例えばデフォルトではOpenAIの「GPT-4o」（GPT-4ベースのStagehand推奨モデル）やAnthropicの「Claude 3.5 Sonnet」シリーズが利用可能です ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=OpenAI%20Models)) ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Anthropic%20Models))。利用するモデルは設定で自由に選択でき、`act()`等を呼ぶ際に都度モデルを指定することもできます。さらに拡張性として、独自のLLMクライアントを実装してStagehandに組み込むこともできます ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Stagehand%20supports%20custom%20models%20by,interface))。`LLMClient`というインタフェースを自前で実装し、それをStagehand初期化時に渡すことで、社内の特殊モデルやオープンソースのローカルモデル（例: Llama系）をStagehandの思考エンジンとして利用できます ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Stagehand%20supports%20custom%20models%20by,interface))。この設計により、Stagehand自体は**特定のモデルやプロバイダにロックインされず**、将来的な新モデルにも対応しやすい柔軟なアーキテクチャとなっています ([Model Support -  Stagehand](https://docs.stagehand.dev/reference/model_support#:~:text=Stagehand%20leverages%20a%20generic%20LLM,that%20best%20suits%20your%20needs))。

**ブラウザ環境とステルス性:**  
デフォルトでは、Stagehandはローカル環境でPlaywrightのブラウザ（Chromium等）をヘッドレス起動して操作します。ただしオプションで**Browserbase上のクラウドブラウザ**を利用することも可能です ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=Stagehand%20constructor)) ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=env%3A%20,logLine.message%7D%60%29%3B%20%7D%2C))。初期化パラメータ`env`を`"BROWSERBASE"`にすると、Browserbaseのサービス経由でブラウザ操作が行われ、**高度なステルス対策**や**CAPTCHA自動処理**などが利用できます ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Browserbase))。Browserbase環境ではヘッドレス設定は無視され（常にサーバ上で実行）、ローカルとは異なるセッション管理が行われます ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=headless))。このように、**用途に応じてローカル実行とクラウド実行を切り替え**られる点も技術的な特徴です。クラウド実行時はBrowserbaseのAPIキーやプロジェクトIDが必要ですが、一定の無料枠が提供されており試用も可能です ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Lastly%2C%20if%20you%20want%20access,Key%20from%20the%20Browserbase%20dashboard))。

最後に付け加えると、Stagehandはまだ**初期リリース段階**のプロジェクトであり、GitHub上で積極的に改良が加えられています（※GitHubリポジトリ「browserbase/stagehand」はすでに7000以上のStarを獲得しています）。開発チームも「コミュニティからのフィードバックを募りつつ機能追加中」であると述べており ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=,latest%20developments%20and%20provide%20feedback))、今後さらに安定性向上や機能拡充（例えばVision機能の高速化 ([stagehand/ROADMAP.md at main · browserbase/stagehand · GitHub](https://github.com/browserbase/stagehand/blob/main/ROADMAP.md#:~:text=We%20have%20a%20baseline%20implementation,of%20the%20vision%20mechanism%20done))など）が進められる見込みです。

## 4. Stagehandの具体的な使用方法

**インストールとセットアップ:**  
StagehandはNode.js製のツールであるため、まず**Node.js (v20以上推奨)とnpm**を用意します ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Prerequisites))。環境が整ったら、公式提供のセットアップ方法として**create-browser-app**というCLIテンプレートを使う方法があります。ターミナルで以下のように実行すると、Stagehandのひな型プロジェクトが1分程度で作成されます ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=,yarn))。

```bash
npx create-browser-app --example quickstart
```

上記を実行すると対話的にいくつか質問が表示されます。例えば「使用するAIモデルを選択（OpenAI GPT-4o など）」「ローカル実行 or Browserbase上で実行」「DOMデバッグ機能を有効にするか」「プロンプト結果のキャッシュを有効にするか」等です ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=%E2%9C%94%20Select%20AI%20model%20to,%E2%9C%94%20Enable%20prompt%20caching%3F%20Yes)) ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Browserbase))。回答に応じてプロジェクトの設定が調整され、`my-app`というディレクトリにテンプレート一式が生成されます ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=npx%20create))。  

次に、そのディレクトリに移動して依存パッケージをインストールします（npmやyarnなど任意のパッケージマネージャを使用可能） ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=,yarn))。

```bash
cd my-app
npm install
```

Stagehandのnpmパッケージ（`@browserbasehq/stagehand`）およびPlaywrightがインストールされ、Playwrightのブラウザ（Chromium など）も自動的にセットアップされます ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Use%20the%20package%20manager%20of,playwright%20install))。最後に以下を実行してサンプルスクリプトを動かします。

```bash
npm run start
```

Quickstartテンプレートでは、Stagehandを使った簡単なブラウザ自動操作の例が用意されています。実行するとHeadlessブラウザが起動し、指定された操作を順次行って結果を出力するはずです。

**OpenAI/Anthropic APIキーの設定:**  
StagehandでAI機能を使うためには、OpenAIまたはAnthropicのAPIキーを環境変数や設定ファイルで指定する必要があります ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Large%20Language%20Models))。たとえばOpenAIのGPT-4を使う場合、OpenAIの管理画面から取得したAPIキーを環境変数`OPENAI_API_KEY`にセットします（Anthropicの場合は`ANTHROPIC_API_KEY`）。また、Browserbase経由で実行する場合は別途`BROWSERBASE_API_KEY`と`BROWSERBASE_PROJECT_ID`を設定します ([Stagehand Toolkit | ️ Langchain](https://js.langchain.com/docs/integrations/tools/stagehand/#:~:text=You%20need%20to%20set%20the,to%20your%20Browserbase%20API%20key))。create-browser-appでプロジェクト作成時に「Browserbaseで実行」を選んだ場合、これらを`.env`ファイルなどに記入する手順がドキュメントに案内されています。

**基本的なコードの構造:**  
Stagehandを用いたスクリプトは、概ね以下のような流れになります。

1. **Stagehandの初期化:** Stagehandクラスをインスタンス化し、必要に応じ設定を渡します（例: ローカル/Browserbase環境や使用モデルの指定など）。その後`stagehand.init()`を呼び出し、内部でブラウザやLLMクライアントを初期化します。  
2. **ブラウザページ取得:** `stagehand.page`プロパティからPlaywrightのページオブジェクトを取得し、`page.goto(URL)`で目的のサイトにナビゲーションします。  
3. **操作の実行:** ページ読み込み後、必要な操作を`page.act()`や`page.extract()`で順次実行します。状況に応じて`page.observe()`でページ内の要素情報を確認することも可能です。  
4. **結果の処理:** `extract()`の戻り値（抽出データ）を利用したり、`act()`の結果メッセージをログに記録したりします。最後に必要ならブラウザを閉じる（`stagehand.close()`）等の後処理を行います。

以下は、Stagehandを使った簡単なスクリプトの例です。

```typescript
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

// 1. Stagehandの初期化（ローカル環境, デフォルト設定を使用）
const stagehand = new Stagehand();
await stagehand.init();

// 2. ブラウザページに移動
const { page } = stagehand;  // PlaywrightのPageオブジェクト
await page.goto("https://docs.stagehand.dev");

// 3. ページ上での操作と情報抽出
await page.act("左上の『Quickstart』リンクをクリック");  // Quickstartページへ遷移 ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=%2F%2F%20Keep%20your%20existing%20Playwright,https%3A%2F%2Fdocs.stagehand.dev))

const result = await page.extract({
  instruction: "このページの説明文を抽出して",
  schema: z.object({ description: z.string() })
});
console.log(result.description);  // 抽出した説明文をコンソール出力 ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=%2F%2F%20Stagehand%20AI%3A%20Extract%20data,description%3A%20z.string%28%29%2C%20%7D%29%2C))

// （必要に応じて）ブラウザとStagehandの終了処理
await stagehand.close();
```

上記のコードでは、まずStagehandを初期化した後、公式ドキュメントサイトに移動しています。次に`page.act()`で「Quickstartリンクをクリックする」という指示を出し、続いて`page.extract()`で現在のページから説明文を抽出しています。抽出には[`zod`](https://github.com/colinhacks/zod)ライブラリを用いてスキーマを定義しており、結果オブジェクトから`description`プロパティでテキストを取り出しています ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=%2F%2F%20Stagehand%20AI%3A%20Extract%20data,description%3A%20z.string%28%29%2C%20%7D%29%2C))。`act()`や`extract()`にはPromiseが返ってくるため、`await`で完了を待つ点は通常のPlaywright操作と同様です。

**設定とカスタマイズ:**  
Stagehandのコンストラクタでは様々な設定を渡すことができます。例えば`{ headless: true, enableCaching: true, modelName: "claude-3-5-sonnet-latest" }`のように指定すれば、**ヘッドレスモードで実行し、LLM応答のキャッシュを有効にし、Anthropic Claude 3.5を使用**するといった挙動にできます ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=%2F%2F%20Custom%20configuration%20const%20stagehand,logLine.message%7D%60%29%3B%20%7D%2C)) ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=enableCaching))。デフォルトでは`headless`は`false`（有効にしない）ですが、Browserbase環境時にはこの設定は無視されます ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=headless))。また`verbose`レベルを上げてログ出力を詳細化したり、`logger`関数を差し込んで独自のログ処理を行うことも可能です ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=env%3A%20,logLine.message%7D%60%29%3B%20%7D%2C)) ([Configuration -  Stagehand](https://docs.stagehand.dev/reference/initialization_config#:~:text=headless%3A%20true%2C%20enableCaching%3A%20true%2C%20logger%3A,logLine.message%7D%60%29%3B))。  

**サンプルとテンプレート活用:**  
公式が提供するGitHubリポジトリ「Browserbase Playbook」には、Stagehandの様々な用途別サンプルが公開されています ([Quickstart -  Stagehand](https://docs.stagehand.dev/get_started/quickstart#:~:text=Check%20out%20the%20Playbook)) ([Examples and Guides -  Stagehand](https://docs.stagehand.dev/get_started/guides#:~:text=Ready))。例えば**永続コンテキスト**（ログイン状態を保持して複数回の実行に利用）や、**Vercelデプロイ**のテンプレート、**カスタムLLMクライアント**を使用する例などが用意されています ([Examples and Guides -  Stagehand](https://docs.stagehand.dev/get_started/guides#:~:text=Custom%20LLM%20Clients)) ([Examples and Guides -  Stagehand](https://docs.stagehand.dev/get_started/guides#:~:text=Persistent%20Contexts))。これらは`npx create-browser-app --example ＜例名＞`でプロジェクト作成時に選択できるようになっており、実践的な設定があらかじめ組み込まれているため非常に参考になります。

**まとめ:**  
Stagehandはそのシンプルなインタフェースに反して高度な処理を内部で行っており、エンジニアは最低限「何をしたいか」を指示するだけでブラウザ操作を自動化できます。特に、これまでスクレイピングやWeb操作ボットの開発で課題となっていた「サイトごとのマニュアルな調整」や「UI変更への脆さ」といった点を、AIの力で克服しようという意欲的な設計になっています。 ([@browserbasehq/stagehand - npm](https://www.npmjs.com/package/@browserbasehq/stagehand?activeTab=readme#:~:text=Stagehand%20adds%20determinism%20to%20otherwise,unpredictable%20agents))で述べられているように、Stagehandを使えば**耐久性が高く自己修復可能なワークフロー**を実現できると期待されています。一方で、性能チューニング（キャッシュ活用やチャンク設計）やプロンプトの工夫など、従来と異なる新たな最適化ポイントも存在します。Stagehandはまだ発展途上のプロジェクトではありますが、将来のWeb自動化のあり方に一石を投じる先進的なツールと言えるでしょう。今後の機能拡張やコミュニティ主導の改善にも注目が集まっています。