Stagehand Crash Course

The essentials of web automation by prompting with Stagehand

Stagehand is a browser automation framework to control browsers with natural language + code. It combines the flexibility of AI with the precision and reliability of traditional code. Built directly on CDP for speed.

Stagehand Primitives

Stagehand is built on 4 primitives. You use these like building blocks, adding step by step to your automation script:

agent()

Autonomous multi-step execution. “Find the cheapest flight and book it”.

observe()

See the current page state.

act()

Perform a single action. “Click login”.

extract()

Pull structured data.

Act vs Agent

act() → Best for an atomic action. Like, “type ‘hello’ in the search box”

agent() → Best for a multi-step workflow or unknown page structure. Like, “log in and download my latest invoice”

Example — all four primitives in one script (TypeScript)

Install and set your environment variables (get your keys here):

pnpm add @browserbasehq/stagehand
npm pkg set type=module

This example uses a Google model:

export BROWSERBASE_API_KEY="your-api-key"
export BROWSERBASE_PROJECT_ID="your-project-id"
export MODEL_API_KEY="your-llm-api-key"

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    modelName: "google/gemini-3-flash-preview",
    apiKey: process.env.MODEL_API_KEY,
  }
});
await stagehand.init();

const page = stagehand.context.pages()[0];
await page.goto("https://news.ycombinator.com");

// observe() — preview what's actionable on the page
const actions = await stagehand.observe("find the link to the top story");
console.log(actions[0]);

// act() — perform a single action
await stagehand.act("click on the comments link for the top story");

// extract() — pull structured data
const data = await stagehand.extract("extract the title and points of the story");
console.log(data);

// agent() — autonomous multi-step execution
const agent = stagehand.agent({
  mode: "hybrid",
  model: "google/gemini-3-flash-preview",
});
await agent.execute("go back to the homepage and find the post with the most comments");

await stagehand.close();

Save as script.ts, then run:

pnpm dlx tsx script.ts

Model Choice

The brain of your automation. Check the Stagehand Evals for current leaders in accuracy, speed, and cost. We support all major model providers.

Browserbase with Stagehand

Pass any Browserbase option (proxies, advanced stealth, etc.) right through to Stagehand.

TypeScript

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    modelName: "google/gemini-3-flash-preview",
    apiKey: process.env.MODEL_API_KEY,
  },
  browserbaseSessionCreateParams: {
    proxies: true,
    browserSettings: {
      blockAds: true,
    }
  }
});

See all Browserbase session parameters →

Python

session = client.sessions.start(
    model_name="google/gemini-3-flash-preview",
    browserbase_session_create_params={
        "proxies": True,
        "browserSettings": {
            "blockAds": True,
        }
    }
)

See all Browserbase session parameters →

More Languages

See the Stagehand SDK docs →

Developer Resources

Build

Playground

Build and test in your browser

Quickstart

Get up and running in 5 minutes

create-browser-app

Scaffold a project in one command

Learn

Templates

Ready-to-use examples

Docs

More documentation

Evals

Model benchmarks

Support

Discord

Community help and showcase

Contact Us

Talk to an engineer