browser-use-to-stagehand

browser-use → Browserbase 上の Stagehand（/browser-use-to-stagehand）

browser-use（Python）スクリプトを、各ステップで適切な決定性のレベルを選びながら、Browserbase 上で実行する慣用的な Stagehand v3（TypeScript） スクリプトに変換します。単純な一対一のエージェント型コピーは作成しません。

基本原則： browser-use はデフォルトでエージェント型です（LLM がすべてのアクションを決定します）。Stagehand では、AI の使用量を選べます。優れた移行では、不透明なエージェントループを、検査可能で、ほぼ決定論的なパイプラインに置き換えます。AI を使うのは、ページが本当に予測できない場合だけです。これは判断を伴うリファクタリングであり、トランスパイルではありません。

信頼できる情報源とバージョン。 このスキルの継続的な価値は、API の詳細（リリースごとに変わります）ではなく、判断（決定性のスペクトラムと、分解するかエージェントを使うかの判断）にあります。 ここに記載されているコードの対応関係は、@browserbasehq/stagehand 3.6.x および browser-use 0.13.x（2026-06）に対して検証されたスナップショットです。矛盾がある場合は、最新のドキュメントを優先してください。コードを出力する前に、必ずインストール済みのパッケージと以下の情報源で確認してください。

• Stagehand v3：https://docs.stagehand.dev/v3 · インストール済みの型定義：node_modules/@browserbasehq/stagehand
• Browserbase：https://docs.browserbase.com
• browser-use：https://docs.browser-use.com

インストール済みの Stagehand のメジャーバージョンが 3 以外の場合、このスキルは概念的なガイドとしてのみ扱い、すべてのシグネチャについて最新のドキュメントに従ってください。

リファレンスファイル（必要に応じて参照）

• references/api-mapping.md — browser-use → Stagehand の機械的な対応関係：バリアントの判定、機能全般の対応表、変換前後のコード、Browserbase のプラットフォームオプション、v3 のバージョンに関する注意点。複雑な構文を扱う場合は参照してください。
• references/determinism.md — agent() と act／extract／observe、およびキャッシュ済みの observe→act の選び方。判断ツリー。Agent(task=…) の翻訳方法を決める際に参照してください。
• references/trace-assisted.md — 不透明または不安定なスクリプトについて、「Browserbase で実行し、ログを確認してから書き換える」任意のワークフロー。
• references/guide.md — 人間向けの移行ガイド：考え方の転換、機能の対応関係、決定性のスペクトラム、推奨される移行手順。
• references/prompt.md — このスキルを、ツールに依存しない自己完結型の形式にしたもの。browser-use スクリプトとともに、任意の AI アシスタントに貼り付けて使用できます。
• EXAMPLES.md — 変換前後のスクリプトの組み合わせ。

ワークフロー

1. ソースを入手する

browser-use スクリプトを入手します。ユーザーがスクリプトの内容だけを説明した場合は、ファイルを依頼してください。別途指定がない限り、対象は Browserbase 上の TypeScript Stagehand です。

最初に対象範囲を確認してください。そもそも移行可能ですか？ browser-use のファイルがすべて Agent(task=…) スクリプトとは限りません。ソースが MCP サーバーとして動作する browser-use（uvx browser-use --mcp、mcpServers 設定）の場合、Stagehand に相当するものはありません。対象範囲外であることを伝え、代替をでっち上げないでください（api-mapping §3.7b を参照）。browser-use の呼び出しがより大きなアプリに組み込まれている場合（クラス／ツールのラッパー、Web ルート、キュータスクなど）は、browser-use の部分だけを変換し、周囲のアプリの連携コードは維持してください（api-mapping §3.8 を参照）。

2. browser-use のバリアントを判定する

レガシー版（0.12 より前）、安定版、または Rust ベータ版（インポート元が browser_use.beta の場合のみ）を判定します（api-mapping §1 を参照）。注：従来のトップレベルの from browser_use import Agent, ChatBrowserUse というインターフェースは 0.13.x でも引き続き利用できます。ChatBrowserUse だけではベータ版とは判断できません。browser_use.beta からのインポートがある場合にのみ、ベータ版と判断してください。どのバリアントも同じ方法で翻訳できるため、判断に迷った場合は安定版の対応関係を使用してください。翻訳前にレガシー版の名前を標準化します。見つかったバリアントを明記してください。

3. スクリプトの内容を棚卸しする

TypeScript を書き始める前に、構造化された棚卸しを作成します。

• タスク — task= の文字列。それぞれに含まれる順序付きの手順を分解します。
• モデル — Chat* プロバイダーとモデル ID。
• ブラウザー設定 — ローカルか、cdp_url／Browserbase か、ヘッドレスか、プロキシ、user_data_dir／storage_state。
• 構造化出力 — output_model_schema の Pydantic モデル。
• シークレット — sensitive_data、環境変数の使用、ログインフロー。
• ガードレール — allowed_domains、max_steps。
• カスタムアクション — @tools.action／Controller 関数と、それぞれが決定論的な副作用かエージェントの機能か。
• セットアップ — initial_actions、セカンダリモデル（page_extraction_llm、planner_llm）。

4. 手順ごとに決定性のレベルを判断する

棚卸しで洗い出した各手順に対して、determinism.md の判断フローを適用します。

• 既知の URL に移動する → Stagehand のページで page.goto(url) を使用します（AI は使いません）。
• ページ上の操作 → act("…") を使用します。繰り返す場合は、observe() を一度実行してから act(action) を再生します（LLM 呼び出しなし）。
• データの読み取り → extract("…", zodSchema) を使用します。
• 真に自由度の高い処理 → stagehand.agent().execute(...) を維持します（maxSteps／systemPrompt で制約を強化します）。

フローが既知の場合は、デフォルトで分解します。不明な箇所に限り agent() を維持します。最初のリフト＆シフトでは、忠実な agent() への変換も許容されます。その旨を明記し、最適化の方法も示してください。

5. Stagehand v3 への書き換えを作成する

まず、API を確認してください。 コードを書く前に、インストール済みパッケージ（node_modules/@browserbasehq/stagehand の型定義）または https://docs.stagehand.dev/v3 を参照し、使用する API の正確なシグネチャを確認します。以下の対応付けは 3.6.x 時点のものです。インストール済みバージョンと異なる場合は、インストール済みバージョンを優先します。その後、実行可能な TypeScript を出力します。必ず次の点を守ってください。

• 抽出を行う場合は、import { Stagehand } from "@browserbasehq/stagehand"; と import { z } from "zod"; を使用します。
• const page = stagehand.context.pages()[0]; でページを取得します。
• AI メソッドはインスタンスで呼び出します。stagehand.act(...)、stagehand.extract(...)、stagehand.observe(...) を使用し、page.act(...) は決して使用しません。
• モデルは "provider/model" 形式の文字列で指定します。
• デフォルトは env: "BROWSERBASE" とし、開発用の選択肢として env: "LOCAL" を示します。
• シークレットは variables と process.env で渡し、ハードコードはしません。
• 最初に await stagehand.init() を呼び出し、finally で await stagehand.close() を呼び出します。

実行できるように、プロジェクトのセットアップも含めてください（以下のテンプレートを参照）。

6. 移行の概要を記述する

コードとあわせて、簡潔な概要を作成します。

• 検出したバリアントと、決定性に関する判断（どの手順を決定論的処理、AI、エージェントにしたか）、およびその理由。
• 人による確認が必要な点 — 1 対 1 で対応できなかった事項：失われた allowed_domains のガードレール、カスタムアクションのロジック、セカンダリモデルの意図、曖昧なタスク文字列。
• 推奨する次のステップ — 認証の再利用には Browserbase Context、本番環境にはキャッシュ、フローが不明瞭な場合にはトレースを利用した方法。

7. トレースを利用した方法を提示する（必要な場合のみ）

ソースが大きく不明瞭な agent(task=…) ひとつだけの場合、動作が不安定な場合、または確信を持って書き換えられない場合は、トレースを利用したワークフロー（trace-assisted.md）を提示します。元のコードを Browserbase で実行し、sessions.logs.list を取得して、観測した挙動に基づいて書き換える方法です。ユーザーの承認なしに実行しないでください。

出力テンプレート

package.json

{
  "name": "stagehand-migration",
  "type": "module",
  "scripts": { "start": "tsx index.ts" },
  "dependencies": {
    "@browserbasehq/stagehand": "^3.0.0",
    "dotenv": "^16.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": { "tsx": "^4.0.0", "typescript": "^5.0.0" }
}

カスタムのブラウザー操作アクションをエージェントの tool に対応付ける場合に限り、"ai": "^5.0.0"（Vercel AI SDK）を追加します。v4 ではなく v5 に固定してください — Stagehand 3.6.x には ai v5 がバンドルされており、agent({ tools }) は v5 の ToolSet として型付けされています。ツールのスキーマフィールドは inputSchema です。v4 の tool() ヘルパーは代わりに parameters を生成するため、Stagehand の v5 ToolSet に対する型チェックに失敗します。依存関係の巻き上げられた ai のバージョンを制御できない場合は、 tool() ヘルパーを使わず、プレーンオブジェクト { description, inputSchema: zodSchema, execute } を渡してください。どのメジャーバージョンの ai が解決されても、v5 の ToolSet を満たします。

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # or the provider matching your model string

index.ts のひな形（分割された、推奨される構成）

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    model: "anthropic/claude-sonnet-4-6",
  });
  await stagehand.init();
  try {
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");          // deterministic skeleton
    await stagehand.act("…");                          // AI where the page varies
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // structured reads

    console.log(data);
  } finally {
    await stagehand.close();
  }
}

main().catch((err) => { console.error(err); process.exit(1); });

検証チェックリスト（完了とする前に）

• AI メソッドはページではなく、インスタンス（stagehand.act/extract/observe）にあります。
• ページは stagehand.context.pages()[0] で取得しています。
• モデルは "provider/model" 形式の文字列で、対応するプロバイダーキーは .env にあります。
• extract は zod スキーマを使用しており、依存関係に zod が含まれています。
• シークレットには variables と process.env を使用し、ハードコードしていません。
• init() / close() があり、close() は finally 内にあります。
• ブラウザー操作の各ステップを考慮し、決定性の度合いを意図的に選んでいます。
• 移行の概要に、決定性に関する選択と「人による確認が必要」な項目を記載しています。

よくある避けるべき間違い

• 古いブログ記事の v2 構文（page.act()、stagehand.page、modelName/modelClientOptions、 enableCaching）をコピーすること。v3 を使用してください — api-mapping の「Version notes」を参照してください。
• すべてのステップを act() に置き換えること — page.goto で移動し、繰り返し可能なステップは observe→act でキャッシュしてください。すべての操作で LLM の呼び出しを行う必要はありません。
• 何もかも agent() に任せること — それでは、ブラウザー操作の非決定性を新しいフレームワークで再現するだけです。フローが既知の箇所は分割してください。
• allowed_domains を黙って削除すること — Stagehand にはドメインファイアウォールがありません。確認事項として挙げてください。
• Browserbase/Stagehand のオプションをでっち上げること — フィールドが不明な場合は推測せず、 https://docs.stagehand.dev/v3 / https://docs.browserbase.com を確認してください。