What is Stagehand v4: the SDK that rewrote browser agents from the ground up

Stagehand is an open source SDK from Browserbase that lets an AI agent drive a web browser with plain English steps, like "click the sign in button," mixed with normal code. Unlike Playwright or Puppeteer, which were built for automated testing and need exact selectors, Stagehand was built for agents, so its AI steps keep working when a page's layout shifts. It's a library for developers, available for TypeScript, Python, and Go.

The current major version, v4, shipped on August 10, 2026. It moved most of the engine into a browser extension that runs next to the page. It also gave Python and Go the same SDK as TypeScript and dropped the old built in agent() loop. As of October 7, 2026, the latest stable release on npm and PyPI is 4.1.0, published September 9, 2026.

How Stagehand works: act, observe, extract

Think about how you'd ask a coworker to buy something online. You'd say "search for the blue mug and add it to the cart." You wouldn't read them the button's CSS class. Stagehand lets your code give instructions the same way.

It does that with three methods, each backed by a large language model (LLM):

• act() performs one action you describe in words. Stagehand reads the page's accessibility tree (the structured outline of a page that screen readers use), asks the model which element matches, and clicks or types there. If the button's class name changes tomorrow, your instruction still reads the same.
• observe() tells you what you can act on right now. It returns candidate elements with selectors, so you can check what the model sees before it acts, or grab a selector once and reuse it without another model call.
• extract() pulls structured data that matches a schema you define (Zod in TypeScript, Pydantic in Python). You get typed data back instead of raw HTML to parse.

You don't have to use AI for every step. Stagehand also gives you familiar page methods like goto, click, locator, and screenshot. The usual pattern is simple: plain code where the page is stable, a model call only where the page needs judgment.

Here's what that looks like in TypeScript:

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
 
const browser = await localBrowser.launch();
const stagehand = await Stagehand.create({
  browser,
  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});
 
const [page] = await browser.context.pages();
await page.goto("https://github.com/browserbase");
await stagehand.act("click on the stagehand repo");

In v4, every AI method returns { data, metadata }. Your result sits on data. The metadata tells you whether the step hit the cache and how many tokens it used.

What changed in Stagehand v4

The big change is where Stagehand runs. Older versions kept a copy of the browser's state inside your script. Every command traveled over the Chrome DevTools Protocol (CDP), the channel tools use to remote control Chrome. On your laptop, that copy stays accurate. When the browser lives in the cloud, the copy drifts, and a click can land on a page that already closed.

v4 moves tab management, frame tracking, and command dispatch into an extension that starts and stops with the browser. Your code asks the browser what's true instead of trusting a stale copy. Browserbase says that's also what let it ship TypeScript, Python, and Go together: each SDK is now a thin client over the same core.

Other changes worth knowing:

• Security moved inside the browser. You can set a domain policy, and v4 blocks a forbidden request before it leaves the browser. That matters when an agent reads a page that tries to trick it into sending your data somewhere.
• Hard pages got easier. Nested iframes, iframes that run in a separate process, and closed Shadow DOM are addressable like normal content. v4 also adds real clipboard support and WebMCP, so pages that expose tools to agents can be driven through those tools.
• agent() is gone. It was a built in loop that let the model pick one action per step. Browserbase's migration guide now recommends "code mode": a coding assistant writes a Stagehand script once, and you run that script. The other option is your own tool calling loop that hands the model Stagehand's methods as tools.

What about speed? Browserbase markets v4 as 2x faster than Playwright and 80% more token efficient. The token chart on stagehand.dev shows about 7.4k tokens for Stagehand against 35.7k for Playwright. In its launch post, Browserbase published one measured run: a 50 action Wikipedia crawl finished in 14.2 seconds versus 22.7 seconds for Playwright. That's a 1.59x difference, and Browserbase itself calls it one run rather than a benchmark. Treat both numbers as vendor claims until you measure your own pages.

Stagehand vs. Playwright and Puppeteer

Browserbase sums it up in one line: "Playwright was built for testing, Stagehand is built for agents." Here's what that means in practice.

One thing people miss: Stagehand v4 doesn't sit on top of Playwright anymore. It launches or connects to Chrome on its own and gives you page methods that feel like Playwright. You don't need Playwright installed to use it.

Playwright and Puppeteer still win when you know the page and need the same steps a thousand times, fast and identical. Stagehand wins when the page changes often, or when keeping selectors alive costs more engineering time than paying for model calls. The real question isn't which tool is faster. It's where you'd rather spend: on selector upkeep or on tokens.

When Stagehand makes sense (and when it doesn't)

Use Stagehand when your agent has to work on pages nobody mapped for it. Good fits include scraping sites that change their layout, login flows that move around every month, and dashboards with unpredictable markup. Any task where "read the page like a person would" beats "repeat the exact steps from six months ago" is a candidate.

Skip Stagehand when you need every run to be identical, raw speed above all, or zero model costs. If the job is "fill this same form 10,000 times a day," plain Playwright will be cheaper and faster. If every action must be audited and reproduced exactly, the model's interpretation adds a layer you may not want.

Since v4 removed agent(), Stagehand is also not a "give it a goal and walk away" bot. You write the loop, the memory, and the retries, or you let a coding assistant write the script for you. Stagehand gives you sharp tools for each step. The agent around them is yours to build.

Moving from v3 to v4

If you have v3 code, plan on a rewrite of the setup code rather than a find and replace. These are the changes you'll hit first:

1. Create the browser first. new Stagehand() and init() are gone. Launch or connect a browser with localBrowser.launch() or browserbase.launch(), then call Stagehand.create({ browser }). Close the browser yourself with browser.close().
2. Pages moved and became async. Use await browser.context.activePage() or await browser.context.pages() instead of stagehand.page.
3. The AI methods moved to the instance. page.act() becomes stagehand.act(), every call returns { data, metadata }, and extract() now takes the instruction and the schema as two arguments.
4. Caching changed. serverCache is now cache, and the local caching options are gone. v4 caches act(), observe(), and extract() results on Browserbase's servers, so caching needs a Browserbase browser.
5. agent() has no direct replacement. Use code mode or your own tool calling loop, as described above.

If you used the v3 Python or Go clients, those talked to a hosted API through session objects. In v4, all three languages share one shape: a browser from a factory, a Stagehand instance on top, and the same three methods. Browserbase's v3 to v4 migration guide has the full list.

Which Stagehand version is current?

As of October 7, 2026, npm lists @browserbasehq/stagehand 4.1.0 as the latest release, published September 9, 2026. The Python package (pip install stagehand) is also at 4.1.0. The v4 line so far:

What 4.1.0 added, according to the project's changelog:

• Search and Fetch without a browser. The browserbase helper can now run a web search or fetch a page as markdown in TypeScript, Python, and Go, without launching a browser.
• Clearer shutdown. browser.close() now always ends the browser, while stagehand.close() leaves it running so another Stagehand instance can attach later.
• WebMCP in more places. Stagehand can find and call WebMCP tools inside iframes that run in a separate process.
• Faster failures. Connecting to a Browserbase session without the extension, or with mismatched protocol versions, now fails right away instead of later.

The older v3 line still gets its own releases. npm keeps it under the v3-latest tag (3.7.3, published August 28, 2026), and the newest v3 server tag on GitHub is stagehand-server-v3/v3.7.6, from the same day.

Two things can confuse you here. First, v4 versions don't show up on the GitHub Releases page yet, so check npm, PyPI, or the repo's changelog instead. Second, npm publishes 4.2.0 alpha builds almost every day. Those are previews, not releases.

A correction: an earlier version of this article said v3.7.5 was the latest release and that v4.0.2 didn't exist. Both claims were wrong, and this section replaces them.

What it costs to run Stagehand

The SDK itself is free under the MIT license, and it runs against Chrome on your own machine by default. Your real costs come from two places:

• Model calls. Every act(), observe(), and extract() call spends LLM tokens. You can bring your own provider key, or, on Browserbase browsers, use Browserbase's Model Gateway, which picks a model for you and bills tokens at the provider's price.
• Cloud browsers (optional). Browserbase hosts browsers for you, with a free plan for prototyping and paid monthly plans after that. Server side caching and the Model Gateway only work on Browserbase browsers.

Want real numbers instead of list prices? We installed v4, measured what each method spent, and broke it on purpose in Stagehand v4: what actually happens when you run it.

Go deeper

• Stagehand v4: what actually happens when you run it, our hands on test of install, costs, and failure modes
• What an MCP server is, the protocol many agent tools use to plug into each other
• Web search APIs for AI agents, for when your agent needs search results, not a full browser
• How AI agent memory works, the piece you'll build yourself now that agent() is gone
• AI tools for developers and the full list of AI tool explainers

If you already call AI APIs and want a guided path to building agents like these, see how AI Flex works. It's self paced, with an AI tutor and mentors, and you can cancel anytime.