---
name: stagehand-browser-agent
description: "Drive browsers with Stagehand's act/extract/observe — Zod-typed extraction, resilient selectors, Browserbase cloud runs. Production Stagehand (v3): page.act() for natural-language actions, page.extract() with Zod schemas for typed structured data, page.observe() to preview/cache actions before executing. Covers self-healing selectors over raw Playwright, the stagehand.agent() loop for multi-step tasks, Browserbase cloud sessions with live view and proxies, model config (Anthropic/OpenAI), caching observed actions for cost control, and dropping to the underlying Playwright Page when you need raw CDP control."
license: MIT
---

# 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

```bash
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
```

```ts
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`.