← Browser Run / browser-run

Stagehand

Stagehand ↗ je open-source knihovna pro automatizaci prohlížeče poháněná umělou inteligencí. Stagehand umožňuje kombinovat kód s instrukcemi v přirozeném jazyce poháněnými AI, takže není nutné diktovat přesné kroky ani určovat selektory. Díky Stagehandu jsou vaši agenti odolnější vůči změnám webu a snadněji se udržují, což vám pomáhá vytvářet řešení spolehlivěji a flexibilněji.

Tento návod vám ukazuje, jak nasadit Worker který využívá Stagehand, Browser Run a Workers AI k automatizaci webové úlohy.

V tomto příkladu použijete Stagehand k vyhledání filmu na tomto ukázkový adresář filmů ↗, extrahujte její podrobnosti (název, rok, hodnocení, délku a žánr) a vraťte tyto informace spolu se snímkem obrazovky webové stránky.

Prohlédněte si video k tomuto příkladu

Výstup:

Pokud místo toho chcete kroky přeskočit a začít rovnou, vyberte Deploy to Cloudflare níže.

Po nasazení můžete s Workerem komunikovat pomocí následujícího vzoru URL adresy:

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

Nainstalujte potřebné závislosti:

npm ci

Aktualizujte konfigurační soubor Wrangler tak, aby obsahoval vazby pro Browser Run a Workers AI:

{
	"name": "stagehand-example",
	"main": "src/index.ts",
	"compatibility_flags": ["nodejs_compat"],
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"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-08-28"

[observability]
enabled = true

[browser]
binding = "BROWSER"

[ai]
binding = "AI"

Pokud používáte Cloudflare Vite plugin ↗, musíte zahrnout následující alias ↗ v vite.config.ts:

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

Pokud nepoužíváte Cloudflare Vite plugin, musíte zahrnout následující alias modulu ↗ do konfigurace wrangler:

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

Kopírovat workersAIClient.ts ↗ do vašeho projektu.

Poté ve svém kódu Workeru naimportujte workersAIClient.ts soubor a použijte jej k nakonfigurování nového Stagehand instance:

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

Po nasazení můžete s Workerem komunikovat pomocí následujícího vzoru URL adresy:

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

npm run deploy

AI Gateway je služba, která přidává pozorovatelnost (observabilitu) vašim AI aplikacím. Směrováním požadavků přes AI Gateway můžete své AI aplikace monitorovat a ladit.

Chcete-li AI Gateway použít s modelem od třetí strany, nejprve vytvořte gateway v AI Gateway stránce v Cloudflare dashboard.

V tomto příkladu jsme bránu pojmenovali stagehand-example-gateway.

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

Pokud chcete použít model mimo Workers AI, můžete Stagehand nakonfigurovat tak, aby používal modely z podporovaných poskytovatelé třetích stran ↗, včetně OpenAI a Anthropic, pomocí vlastních přihlašovacích údajů.

V tomto příkladu nakonfigurujete Stagehand tak, aby používal OpenAI ↗. Budete potřebovat klíč OpenAI API. Cloudflare doporučuje ukládat tento klíč API jako secret.

npx wrangler secret put OPENAI_API_KEY

Poté nakonfigurujte Stagehand se svým poskytovatelem, modelem a klíčem API.

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

AI Gateway je služba, která přidává pozorovatelnost (observabilitu) vašim AI aplikacím. Směrováním požadavků přes AI Gateway můžete své AI aplikace monitorovat a ladit.

Chcete-li AI Gateway použít s modelem od třetí strany, nejprve vytvořte gateway v AI Gateway stránce v Cloudflare dashboard.

V tomto příkladu používáme OpenAI s AI Gateway. Nezapomeňte přidat baseURL jak je uvedeno níže, s vlastním Account ID a Gateway ID.

Musíte zadat apiKey v modelClientOptions:

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`,
	},
});

Pokud používáte ověřenou AI Gateway, postupujte podle pokynů v Ověřování AI Gateway a zahrnout cf-aig-authorization jako hlavičku.

Úplný seznam metod a možností Stagehand najdete v oficiální Dokumentace Stagehand API ↗.