导航|地址|刷新
Stagehand

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/browser-run/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Browser Run

/

Overview

Get started

Examples

Features

Live ViewBeta

Human in the LoopBeta

Session recordingBeta

WebMCPBeta

Custom fonts

Reuse sessions

Quick Actions

Overview

/content - Fetch HTML

/screenshot - Capture screenshot

/pdf - Render PDF

/markdown - Extract Markdown from a webpage

/snapshot - Capture multiple page formats

/accessibilityTree - Capture accessibility tree

/scrape - Scrape HTML elements

/json - Capture structured data using AI

/links - Retrieve links from a webpage

/crawl - Crawl web contentBeta

Reference ↗API

Chrome DevTools Protocol (CDP)Beta

Overview

Session management (HTTP)

Using with Puppeteer (CDP)

Using with Playwright (CDP)

Using with MCP clients (CDP)

Playwright

Overview

Playwright MCPBeta

Puppeteer

StagehandBeta

Tutorials

Deploy a Browser Run Worker

Generate PDFs Using HTML and CSS

Build a web crawler with Queues and Browser Run ↗

Deploy a Browser Run Worker with Durable Objects

Generate OG images for Astro sites

Pre-render pages for crawlers

Reference

Automatic request headers

Supported fonts

Quick Actions timeouts

robots.txt and sitemaps

Browser close reasons

Wrangler

Wrangler commands

FAQ

Limits

Pricing

Changelog

MCP serverMCP

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Browser Run llms.txt ↗

Browser Run llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Browser Run

/Stagehand

Stagehand

Last updated Apr 21, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewUse Stagehand in a Worker with Workers AI 1. Set up your project 2. Configure your Worker 3. Write the Worker code 4. Build the project 5. Deploy to Cloudflare WorkersUse Cloudflare AI Gateway with Workers AIUse a third-party modelUse Cloudflare AI Gateway with a third-party modelStagehand API

Stagehand ↗ is an open-source, AI-powered browser automation library. Stagehand lets you combine code with natural-language instructions powered by AI, eliminating the need to dictate exact steps or specify selectors. With Stagehand, your agents are more resilient to website changes and easier to maintain, helping you build more reliably and flexibly.

This guide shows you how to deploy a Worker that uses Stagehand, Browser Run, and Workers AI to automate a web task.

Note

Browser Run currently supports @browserbasehq/stagehandv2.5.x only. Stagehand v3 and later are not supported because they are not Playwright-based.

Use Stagehand in a Worker with Workers AI

In this example, you will use Stagehand to search for a movie on this example movie directory ↗, extract its details (title, year, rating, duration, and genre), and return the information along with a screenshot of the webpage.

See a video of this example

Output:

If instead you want to skip the steps and get started right away, select Deploy to Cloudflare below.

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:
npm ci

2. Configure your Worker

Update your Wrangler configuration file to include the bindings for Browser Run and Workers AI:

Note

Your Worker configuration must include the nodejs_compat compatibility flag and a compatibility_date of 2025-09-15 or later.

{ "name": "stagehand-example", "main": "src/index.ts", "compatibility_flags": ["nodejs_compat"], // Set this to today's date "compatibility_date": "2026-07-31", "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 datecompatibility_date = "2026-07-31"[observability]enabled = true[browser]binding = "BROWSER"[ai]binding = "AI"

If you are using the Cloudflare Vite plugin ↗, you need to include the following alias ↗ in vite.config.ts:
export default defineConfig({ // ... resolve: { alias: { playwright: "@cloudflare/playwright", }, },});
If you are not using the Cloudflare Vite plugin, you need to include the following module alias ↗ to the wrangler configuration:
{ // ... "alias": { "playwright": "@cloudflare/playwright", },}

3. Write the Worker code

Copy workersAIClient.ts ↗ to your project.

Then, in your Worker code, import the workersAIClient.ts file and use it to configure a new Stagehand instance:
src/index.tstsimport { 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); },};

Note

The snippet above requires Zod v3 ↗ and is currently not compatible with Zod v4.

Ensure your package.json has the following dependencies:
{ // ... "dependencies": { "@browserbasehq/stagehand": "2.5.x", "@cloudflare/playwright": "^1.0.0", "zod": "^3.25.76", "zod-to-json-schema": "^3.24.6" // ... }}

4. Build the project

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.devnpm run deploy

Use Cloudflare AI Gateway with Workers AI

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.

To use AI Gateway with a third-party model, first create a gateway in the AI Gateway page of the Cloudflare dashboard.
Go to AI Gateway ↗
In this example, we've named the gateway stagehand-example-gateway.
const stagehand = new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl }, llmClient: new WorkersAIClient(env.AI, { gateway: { id: "stagehand-example-gateway", }, }),});

Use a third-party model

If you want to use a model outside of Workers AI, you can configure Stagehand to use models from supported third-party providers ↗, including OpenAI and Anthropic, by providing your own credentials.

In this example, you will configure Stagehand to use OpenAI ↗. You will need an OpenAI API key. Cloudflare recommends storing your API key as a secret.
npx wrangler secret put OPENAI_API_KEY
Then, configure Stagehand with your provider, model, and API key.
const stagehand = new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: endpointURLString(env.BROWSER) }, modelName: "openai/gpt-4.1", modelClientOptions: { apiKey: env.OPENAI_API_KEY, },});

Use Cloudflare AI Gateway with a third-party model

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.

To use AI Gateway with a third-party model, first create a gateway in the AI Gateway page of the Cloudflare dashboard.
Go to AI Gateway ↗
In this example, we are using OpenAI with AI Gateway. Make sure to add the baseURL as shown below, with your own Account ID and Gateway ID.

You must specify the apiKey in the 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`, },});
If you are using an authenticated AI Gateway, follow the instructions in AI Gateway authentication and include cf-aig-authorization as a header.

Stagehand API

For the full list of Stagehand methods and capabilities, refer to the official Stagehand API documentation ↗.

PreviousPuppeteerNextDeploy a Browser Run Worker

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Use Stagehand in a Worker with Workers AI

1. Set up your project

2. Configure your Worker

3. Write the Worker code

4. Build the project

5. Deploy to Cloudflare Workers

Use Cloudflare AI Gateway with Workers AI

Use a third-party model

Use Cloudflare AI Gateway with a third-party model

Stagehand API

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs

------
导航页打开网址