Stagehand Browser Agent

Stagehand is an AI-driven browser framework built on top of Playwright. This skill teaches the agent to drive web pages with three high-level primitives — act, extract, and observe — instead of hand-writing brittle CSS/XPath selectors. It's aimed at developers building scrapers, QA flows, or autonomous web agents who want LLM resilience where it helps and deterministic Playwright where it doesn't.

When to use it

• Scraping pages whose markup changes often, where fixed selectors break weekly.
• Pulling typed, validated data out of a page (tables, listings, search results) into a Zod schema.
• Multi-step tasks ("log in, filter to last 30 days, export the report") that you'd rather describe than script step by step.
• Running automation headless in the cloud on Browserbase, with session replay and stealth, instead of a local Chromium.

How it works

You construct a Stagehand instance, then call await stagehand.init() to get a page (a superset of Playwright's Page). The three core methods:

• page.act("click the login button") — performs a natural-language action. Pass cached observe() results instead of a string to make it deterministic.
• page.extract({ instruction, schema }) — returns data matching a Zod schema, so you get typed results, not raw strings.
• page.observe("find the submit button") — returns candidate actions/selectors without executing them. Preview, log, or cache these to make later act calls fast and repeatable.

For end-to-end autonomy, stagehand.agent() runs a plan/act loop that chains these primitives until a goal is met. Because page extends Playwright, you can drop to page.goto, page.locator, or page.keyboard whenever you need raw control. Set env: "BROWSERBASE" (plus BROWSERBASE_API_KEY / BROWSERBASE_PROJECT_ID) to run on the cloud, or env: "LOCAL" for local Chromium.

Example

curl -fsSL --create-dirs -o ~/.claude/skills/stagehand-browser-agent/SKILL.md https://claudeskil.com/skills/stagehand-browser-agent/SKILL.md
npm install @browserbasehq/stagehand zod

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

const sh = new Stagehand({ env: "LOCAL", modelName: "claude-sonnet-4-5" });
await sh.init();
const page = sh.page;

await page.goto("https://news.ycombinator.com");
const { stories } = await page.extract({
  instruction: "extract the top 5 story titles and points",
  schema: z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })),
  }),
});
console.log(stories);
await sh.close();

Tips & gotchas

• Cache observe() output and feed it to act() for production runs — pure NL act calls cost a model round-trip each time and are non-deterministic.
• Keep extract schemas tight; over-broad schemas make the model hallucinate fields. Use .describe() on Zod fields to guide it.
• Always await sh.close() — orphaned Browserbase sessions keep billing.
• Set modelName / modelClientOptions explicitly; default model choice affects both cost and accuracy.

FAQ

Do I still need Playwright knowledge? Helpful but not required. page is Playwright-compatible, so existing locator code keeps working alongside act/extract.

Does it run without Browserbase? Yes — env: "LOCAL" uses local Chromium. Browserbase adds cloud scaling, stealth, and session replay.

Which models work? Stagehand is model-agnostic; configure Anthropic, OpenAI, or others via modelName and modelClientOptions.