cloudflare · kathayl · Sep 25, 2025 · Sep 22, 2025 · Sep 22, 2025 · Sep 23, 2025
@@ -0,0 +1,208 @@
+---
+pcx_content_type: concept
+title: Stagehand
+description: Deploy a Stagehand server that uses Browser Rendering to provide browser automation capabilities to your agents.
+sidebar:
+  order: 7
+  badge: Beta
+---
+
+import {
+	Render,
+	WranglerConfig,
+	TabItem,
+	Tabs,
+	PackageManagers,
+} from "~/components";
+
+[Stagehand](https://www.stagehand.dev/) is an open-source, AI-powered browser automation library. Rather than dictating exact steps or specifying selectors, Stagehand enables developers to build more reliably and flexibly by combining code with natural-language instructions powered by AI. This makes your agents more resilient to website changes and easier to maintain. 
+
+This guide shows you how to deploy a Worker that uses Stagehand, Browser Rendering, and [Workers AI](/workers-ai/) to automate a web task.
+
+## Use Stagehand in a Worker
+
+In this example, you will use Stagehand to search for a movie on [The Movie Database](https://www.themoviedb.org/), extract its details (title, year, and director), and return the information along with a screenshot of the webpage.
+
+If you want to skip the steps and get started quickly, select **Deploy to Cloudflare** below.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/playwright-mcp/tree/main/cloudflare/example)
+
+After you deploy, you can interact with the Worker using this URL pattern:
+```
+https://<your-worker>.workers.dev
+```
+
+#### 1. Set up your project
+
+Install the necessary dependencies:
+	```bash
+	npm ci
+	```
+
+#### 2. Configure your Worker
+
+Update your wrangler configuration file to include the bindings for Browser Rendering and [Workers AI](/workers-ai/):
+	<WranglerConfig>
+		```jsonc
+			{
+				"name": "cloudflare-stagehand-example",
+				"main": "src/index.ts",
+				"compatibility_flags": ["nodejs_compat", "enable_nodejs_fs_module"],
+				"compatibility_date": "2025-09-01",
+				"workers_dev": true,
+				"upload_source_maps": true,
+				"alias": {
+					"playwright": "@cloudflare/playwright"
+				},
+				"observability": {
+					"enabled": true
+				},
+				"browser": {
+					"binding": "BROWSER",
+					"experimental_remote": true
+				},
+				"ai": {
+					"binding": "AI"
+				}
+			}
+		```
+	</WranglerConfig>
+
+#### 3. Write the Worker code
+
+	```ts title="src/index.ts"
+
+	import { Stagehand } from "@browserbasehq/stagehand";
+	import { z } from "zod";
+	import { endpointURLString } from "@cloudflare/playwright";
+	import { createWorkersAI } from "workers-ai-provider";
+	import { AISdkClient } from "./aidsk";
+
+	export default {
+		async fetch(request: Request, env: Env) {
+			const url = new URL(request.url);
+			if (url.pathname !== "/")
+				return new Response("Not found", { status: 404 });
+
+			const workersai = createWorkersAI({ binding: env.AI });
+			// @ts-ignore
+			const model = workersai("@cf/meta/llama-3.3-70b-instruct-fp8-fast");
+
+			const stagehand = new Stagehand({
+				env: "LOCAL",
+				localBrowserLaunchOptions: { cdpUrl: endpointURLString("BROWSER") },
+				llmClient: new AISdkClient({ model }),
+				verbose: 1,
+			});
+
+			await stagehand.init();
+			const page = stagehand.page;
+
+			await page.goto('https://www.themoviedb.org/');
+			// for multi-step actions, use observe
+			const actions = await page.observe('Search for "The Iron Giant" and click the Search button');
+			for (const action of actions)
+				await page.act(action);
+			await page.act('Click the first search result');
+			let movieInfo = await page.extract({
+				instruction: 'Extract movie information',
+				schema: z.object({
+					title: z.string(),
+					year: z.number(),
+					director: z.string(),
+				}),
+			});
+
+			const screenshot = await page.screenshot();
+			await stagehand.close();
+
+			return new Response(`
+				<html>
+					<head>
+						<title>Cloudflare Stagehand Example</title>
+						<style>
+							body {
+								font-family: system-ui, -apple-system, sans-serif;
+							}
+						</style>
+					</head>
+					<body>
+						<h1>Stagehand Example</h1>
+						<p>This example shows how to use <a href="https://www.stagehand.dev/">stagehand</a> to extract information from a web page.</p>
+						<h2>Movie Information</h2>
+						<div>
+							<p><b>Title:</b> ${movieInfo.title}</p>
+							<p><b>Release Year:</b> ${movieInfo.year}</p>
+							<p><b>Director:</b> ${movieInfo.director}</p>
+						</div>
+						<img src="data:image/png;base64,${screenshot.toString('base64')}" />
+					</body>
+				</html>
+			`, {
+				headers: {
+					"Content-Type": "text/html; charset=utf-8",
+				},
+			});
+		},
+	};
+	```
+#### 4. Build the project
+
+	```bash
+	npm run build
+	```
+#### 5. Deploy to Cloudflare Workers
+
+After you deploy, you can interact with the Worker using this URL pattern:
+```
+https://<your-worker>.workers.dev
+```
+
+	```bash
+	npm run deploy
+	```
+
+## Use Cloudflare AI Gateway
+
+[AI Gateway](/ai-gateway/) is a service that adds observability to your AI applications. By routing your requests through AI Gateway, you can monitor and debug your AI applications.
+
+You can use AI Gateway with both Workers AI and third-party models. 
+
+To use AI Gateway, first create a gateway in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/ai-gateway), then add the `baseURL` as shown below. 
+
+```typescript
+const stagehand = new Stagehand({
+  env: "LOCAL",
+  localBrowserLaunchOptions: { cdpUrl: endpointURLString("BROWSER") },
+  modelName: "openai/gpt-4.1",
+  modelClientOptions: {
+    baseURL: `https://gateway.ai.cloudflare.com/v1/${env.CLOUDFLARE_ACCOUNT_ID}/${env.AI_GATEWAY_ID}/openai`,
+  },
+});
+```
+
+## Use a custom model
+
+You can configure Stagehand to use models from third-party providers, including OpenAI or Anthropic, by providing your own credentials.
+
+In this example, you will configure Stagehand to use [OpenAI](https://openai.com/). You will need an OpenAI API key. Cloudflare recommends storing your API key as a [secret](/workers/configuration/secrets/).
+
+```bash
+	npx wrangler secret put OPENAI_API_KEY
+	```
+
+Then, configure Stagehand with your provider, model, and API key.
+
+```typescript
+const stagehand = new Stagehand({
+  env: "LOCAL",
+  localBrowserLaunchOptions: { cdpUrl: endpointURLString("BROWSER") },
+  modelName: "openai/gpt-4.1",
+  modelClientOptions: {
+    apiKey: env.OPENAI_API_KEY,
+  },
+});
+```
+
+## Stagehand API
+For the full list of Stagehand methods and capabilities, refer to the official [Stagehand API documentation](https://docs.stagehand.dev/first-steps/introduction).