← Browser Run / browser-run

Stagehand

Stagehand ↗ это open source библиотека автоматизации браузера на основе AI. Stagehand позволяет сочетать код с инструкциями на естественном языке на основе AI, избавляя от необходимости прописывать точные шаги или указывать селекторы. Благодаря Stagehand ваши агенты становятся более устойчивыми к изменениям сайтов и проще в поддержке, что помогает разрабатывать более надёжно и гибко.

В этом руководстве показано, как развернуть Worker который использует Stagehand, Browser Run и Workers AI чтобы автоматизировать веб-задачу.

В этом примере вы используете Stagehand для поиска фильма на этом пример каталога фильмов ↗, извлеките его данные (название, год, рейтинг, продолжительность и жанр) и верните эту информацию вместе со снимком страницы.

Посмотреть видео этого примера

Результат:

Если вы хотите пропустить эти шаги и начать сразу, выберите Deploy to Cloudflare ниже.

После развёртывания вы можете обращаться к Worker по следующему шаблону URL:

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-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"

Если вы используете Cloudflare Vite plugin ↗, вам нужно включить следующий алиас ↗ в vite.config.ts:

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

Если вы не используете плагин Cloudflare Vite, необходимо добавить следующий псевдоним модуля ↗ в конфигурацию 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

После развёртывания вы можете обращаться к Worker по следующему шаблону URL:

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

npm run deploy

AI Gateway это сервис, который добавляет наблюдаемость вашим AI-приложениям. Направляя запросы через AI Gateway, вы можете отслеживать и отлаживать свои AI-приложения.

Чтобы использовать AI Gateway со сторонней моделью, сначала создайте шлюз в AI Gateway странице дашборда Cloudflare.

В этом примере шлюз назван stagehand-example-gateway.

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

Если вы хотите использовать модель за пределами Workers AI, можно настроить Stagehand на использование моделей из поддерживаемых сторонние поставщики ↗, включая OpenAI и Anthropic, указав собственные учётные данные.

В этом примере вы настроите Stagehand на использование OpenAI ↗. Вам потребуется ключ API OpenAI. Cloudflare рекомендует хранить ключ API как secret.

npx wrangler secret put OPENAI_API_KEY

Затем настройте Stagehand, указав провайдера, модель и ключ 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 это сервис, который добавляет наблюдаемость вашим AI-приложениям. Направляя запросы через AI Gateway, вы можете отслеживать и отлаживать свои AI-приложения.

Чтобы использовать AI Gateway со сторонней моделью, сначала создайте шлюз в AI Gateway странице дашборда Cloudflare.

В этом примере используется OpenAI через AI Gateway. Обязательно добавьте baseURL как показано ниже, используя собственные Account ID и Gateway ID.

Необходимо задать apiKey в 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`,
	},
});

Если вы используете AI Gateway с авторизацией, следуйте инструкциям в Аутентификация AI Gateway и включить cf-aig-authorization в качестве заголовка.

Полный список методов и возможностей Stagehand см. в официальной Документация Stagehand API ↗.