# Stagehand: An SDK for Building Browser Agents in TypeScript, Python, and Go

> Stagehand is a browser automation SDK that bridges low-level Playwright-style control and high-level AI agent actions, offering act, observe, and extract as first-class primitives across three languages. It targets teams that need reliable browser automation in production rather than fragile one-off scripts.

**browserbase/stagehand** — Project brief: The SDK For Browser Agents. Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production.

- Repository: https://github.com/browserbase/stagehand
- Website: https://stagehand.dev
- Stars: 25,387 · Forks: 1,735
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/browserbase-stagehand

## The problem Stagehand addresses

Browser automation has two common failure modes. Low-level tools like Playwright and Selenium give precise control but require explicit CSS selectors or XPath expressions that break when a site updates its DOM. High-level AI agents that interpret natural language instructions are flexible but unpredictable: they can take unexpected paths and produce inconsistent results across runs.

Stagehand sits between those two positions. It exposes Playwright's familiar navigation and interaction methods alongside three AI-backed primitives: act (perform an action on the page), observe (inspect the page state), and extract (pull structured data out). The act and observe primitives return or consume real DOM selectors, so the LLM never receives raw credentials and the selectors can be reused on subsequent calls. When the site changes, Stagehand refreshes the selector automatically rather than crashing.

## How Stagehand processes a page

Stagehand runs as a browser extension alongside the browser, keeping it in the same process as the page rather than in a separate driver process. The README describes this as cutting round-trip latency on every action compared to an out-of-process driver.

For page understanding, Stagehand uses hybrid accessibility-tree trimming. It sends a compressed representation of the page's accessibility tree to the LLM rather than the full HTML, reducing token consumption. The README calls this "token efficiency" and describes it as giving agents exactly the page context they need.

The three core methods work across all three supported languages. In TypeScript:

```typescript
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
const stagehand = await Stagehand.create({
  browser,
  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});
```

The userDataDir option persists cookies between runs, so authentication is handled once and subsequent runs start already signed in. The README highlights this as a primary workflow for accessing apps that require login.

## Installing Stagehand and running a first script

For TypeScript, install with pnpm:

```bash
pnpm add @browserbasehq/stagehand 'zod@~4.4.3'
```

For Python:

```bash
pip install stagehand
```

For Go:

```bash
go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0
```

Local runs require Chrome to be installed and available. The .env.example file in the repository shows the minimal configuration: OPENAI_API_KEY for the model and BROWSERBASE_API_KEY for running against the Browserbase cloud service. The CHROME_PATH variable can be set if Chrome cannot be detected automatically.

The justfile in the repository provides convenience commands. Running `just install` sets up all three language environments together. The `just example` command runs a named example from the packages directory.

## Running on Browserbase versus locally

Stagehand can run against a local Chrome instance or against the Browserbase cloud service. The README documents that Browserbase runs give 2x faster execution than equivalent Playwright cloud browsers.

The cloud path adds two features that the local path lacks. The Model Gateway selects the cheapest model for each action automatically, removing the need to wire up a provider key. Server-side caching stores the results of identical actions so repeated calls return cached responses without spending additional tokens.

In TypeScript, switching from local to Browserbase is a one-line change:

```typescript
import { browserbase, Stagehand } from "@browserbasehq/stagehand";

const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY! });
const stagehand = await Stagehand.create({ browser, cache: true });
```

The same script logic runs unchanged; only the browser launch method differs.

## Limitations and when Stagehand is the wrong choice

Every AI-driven action (act, observe, extract) calls an LLM. That introduces latency on each step and accumulates token costs over a long session. For deterministic automation of a stable site that never changes its DOM, a plain Playwright script with hardcoded selectors will be faster and cheaper than Stagehand.

Stagehand is also a TypeScript-first project. The Python and Go SDKs are generated from a shared protocol layer, as documented in the justfile's generate commands. This means Python and Go users depend on the TypeScript package's release cycle and may see features arrive later. The Python SDK is built with uv and the Go SDK with a code generator; neither is a hand-authored independent implementation.

The project is at v4.0.0 in the workspace package.json, with the latest stagehand releases at the 3.7.x range. The last push was on 2026-09-25. The MIT licence permits use in commercial products without restriction.

## Integration ecosystem: OpenTelemetry, WebMCP, and iframes

The README lists several integration-focused features beyond the core act/observe/extract loop. OTel traces are built in: the .env.example file shows configuration for LangSmith and Braintrust trace sinks via the EVAL_TRACE_TRANSPORT environment variable, with native and otel as the two options. This makes Stagehand sessions observable with standard tracing infrastructure.

WebMCP support is mentioned in the README's feature table, enabling agents to interact with pages that expose a Model Context Protocol endpoint directly. Clipboard support, batch commands, and deep locators for nested iframes and closed Shadow DOMs are also listed, addressing DOM structures that standard Playwright selectors handle poorly.

Compared to plain Playwright, which is a mature, well-documented, standalone automation library, Stagehand adds the LLM layer but requires an LLM provider key and accepts the associated latency and cost. Teams that need the self-healing selector behavior specifically will find Stagehand's act/observe pattern useful; teams that do not need AI-driven adaptability should stay with Playwright or Puppeteer.

## Conclusion

Stagehand is well-suited for teams that need AI-assisted browser automation that must survive page changes without constant maintenance. The three-language support (TypeScript, Python, Go) means it fits most backend stacks. The dependency on an external LLM provider for the act/observe/extract primitives is a real cost: every AI-driven action calls a model, and that adds latency and token spending. Before adopting it, check whether the Model Gateway and server-side caching cover your target sites, since those two features are the main paths to reducing that per-action cost.

## FAQ

### What is Stagehand for browser automation?

Stagehand is an SDK that extends browser automation with AI-backed act, observe, and extract primitives. It works alongside Playwright-style methods and supports TypeScript, Python, and Go. When a page changes, the act and observe methods refresh their selectors automatically.

### What is Stagehand AI?

Stagehand AI refers to the LLM-backed layer of the Stagehand SDK. The act, observe, and extract methods send a compressed accessibility-tree representation of the page to an LLM (such as an OpenAI model), which returns real DOM selectors or structured data. The model is configurable via the modelName and apiKey fields in the Stagehand.create options.

### What is Stagehand automation?

Stagehand automation is a browser automation approach where high-level AI primitives (act, observe, extract) are combined with Playwright-style navigation methods. The AI layer handles selector discovery and self-healing, while the developer controls the flow explicitly. It runs locally with Chrome or remotely on the Browserbase cloud service.

## Sources

- [Official documentation](https://stagehand.dev)
- [Official README](https://github.com/browserbase/stagehand#readme)
- [Project repository](https://github.com/browserbase/stagehand)
- [Release notes](https://github.com/browserbase/stagehand/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/browserbase-stagehand