Stagehand

Stagehand ↗ は、オープンソースの AI 駆動ブラウザー自動化ライブラリです。コードと、AI による自然言語の指示を組み合わせられるため、正確な手順やセレクターを指定する必要がありません。Stagehand を使うと、サイト変更への耐性が上がり、保守しやすくなるため、より確実で柔軟な構築ができます。

このガイドでは、Worker をデプロイし、Stagehand、Browser Run、Workers AI で Web タスクを自動化します。

この例では、Stagehand でこの 映画ディレクトリのデモ ↗ から映画を検索し、詳細（タイトル、公開年、評価、上映時間、ジャンル）を抽出して、情報とウェブページのスクリーンショットを返します。

この例の動画を見る

出力:

手順を省略してすぐに始める場合は、下の Deploy to Cloudflare を選びます。

デプロイ後は、次の URL パターンで Worker にアクセスできます。

https://<your-worker>.workers.dev

必要な依存関係をインストールします。

npm ci

Wrangler 設定ファイルを更新し、Browser Run と Workers AI のバインディングを追加します。

{
	"name": "stagehand-example",
	"main": "src/index.ts",
	"compatibility_flags": ["nodejs_compat"],
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"observability": {
		"enabled": true
	},
	"browser": {
		"binding": "BROWSER"
	},
	"ai": {
		"binding": "AI"
	}
}

name = "stagehand-example"
main = "src/index.ts"
compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-09-20"

[observability]
enabled = true

[browser]
binding = "BROWSER"

[ai]
binding = "AI"

Cloudflare Vite plugin ↗ を使う場合は、vite.config.ts に次の alias ↗ を追加します。

export default defineConfig({
	// ...
	resolve: {
		alias: {
			playwright: "@cloudflare/playwright",
		},
	},
});

Cloudflare Vite plugin を使わない場合は、Wrangler 設定に次の モジュールエイリアス ↗ を追加します。

{
	// ...
	"alias": {
		"playwright": "@cloudflare/playwright",
	},
}

workersAIClient.ts ↗ をプロジェクトにコピーします。

次に、Worker のコードで workersAIClient.ts をインポートし、新しい Stagehand インスタンスの設定に使います。

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";
import { endpointURLString } from "@cloudflare/playwright";
import { WorkersAIClient } from "./workersAIClient";

export default {
	async fetch(request: Request, env: Env) {
		if (new URL(request.url).pathname !== "/")
			return new Response("Not found", { status: 404 });

		const stagehand = new Stagehand({
			env: "LOCAL",
			localBrowserLaunchOptions: { cdpUrl: endpointURLString(env.BROWSER) },
			llmClient: new WorkersAIClient(env.AI),
			verbose: 1,
		});

		await stagehand.init();
		const page = stagehand.page;

		await page.goto("https://demo.playwright.dev/movies");

		// if search is a multi-step action, stagehand will return an array of actions it needs to act on
		const actions = await page.observe('Search for "Furiosa"');
		for (const action of actions) await page.act(action);

		await page.act("Click the search result");

		// normal playwright functions work as expected
		await page.waitForSelector(".info-wrapper .cast");

		let movieInfo = await page.extract({
			instruction: "Extract movie information",
			schema: z.object({
				title: z.string(),
				year: z.number(),
				rating: z.number(),
				genres: z.array(z.string()),
				duration: z.number().describe("Duration in minutes"),
			}),
		});

		await stagehand.close();

		return Response.json(movieInfo);
	},
};

npm run build

デプロイ後は、次の URL パターンで Worker にアクセスできます。

https://<your-worker>.workers.dev

npm run deploy

AI Gateway は、AI アプリケーションに可観測性を追加するサービスです。リクエストを AI Gateway 経由にすると、監視とデバッグができます。

サードパーティモデルで AI Gateway を使うには、まず Cloudflare ダッシュボードの AI Gateway ページでゲートウェイを作成します。

この例では、ゲートウェイ名を stagehand-example-gateway にしています。

const stagehand = new Stagehand({
	env: "LOCAL",
	localBrowserLaunchOptions: { cdpUrl },
	llmClient: new WorkersAIClient(env.AI, {
		gateway: {
			id: "stagehand-example-gateway",
		},
	}),
});

Workers AI 以外のモデルを使う場合は、OpenAI や Anthropic など、対応する サードパーティプロバイダー ↗ の認証情報を渡して、Stagehand を設定できます。

この例では、Stagehand を OpenAI ↗ 向けに設定します。OpenAI API キーが必要です。API キーは シークレット として保存することを推奨します。

npx wrangler secret put OPENAI_API_KEY

次に、プロバイダー、モデル、API キーを指定して Stagehand を設定します。

const stagehand = new Stagehand({
	env: "LOCAL",
	localBrowserLaunchOptions: { cdpUrl: endpointURLString(env.BROWSER) },
	modelName: "openai/gpt-4.1",
	modelClientOptions: {
		apiKey: env.OPENAI_API_KEY,
	},
});

AI Gateway は、AI アプリケーションに可観測性を追加するサービスです。リクエストを AI Gateway 経由にすると、監視とデバッグができます。

サードパーティモデルで AI Gateway を使うには、まず Cloudflare ダッシュボードの AI Gateway ページでゲートウェイを作成します。

この例では、AI Gateway 経由の OpenAI を使います。次のとおり、自分の Account ID と Gateway ID を入れた baseURL を指定します。

modelClientOptions に apiKey を指定する必要があります。

const stagehand = new Stagehand({
	env: "LOCAL",
	localBrowserLaunchOptions: { cdpUrl: endpointURLString(env.BROWSER) },
	modelName: "openai/gpt-4.1",
	modelClientOptions: {
		apiKey: env.OPENAI_API_KEY,
		baseURL: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai`,
	},
});

認証付き AI Gateway を使う場合は、AI Gateway の認証 の手順に従い、ヘッダーに cf-aig-authorization を含めます。

Stagehand のメソッドと機能の一覧は、公式の Stagehand API ドキュメント ↗ を参照してください。