Stagehand v4 is Browserbase's SDK for building browser agents, launched in 2026 as a complete rewrite that moves the core execution into a native browser extension, promising twice the speed of Playwright and an 80% token saving. Unlike traditional headless browsers such as Puppeteer or Playwright, which were built for automated testing, Stagehand was built specifically for AI agents to interact with the web semantically, using natural-language commands instead of fragile CSS selectors. In version 4, the project removed the integrated agent() orchestrator to return control to the programmer, doubled performance, and drastically reduced the LLM cost per operation.
The architectural shift is significant: instead of controlling the browser from an external process via CDP (Chrome DevTools Protocol), Stagehand v4 runs its state management, frame tracking, and command dispatch inside an extension of the browser itself. This removes the network round-trip between the SDK and the browser, enables asynchronous access to pages and contexts, and opens the door to a more robust security model where enforcement runs inside the browser process.
How does Stagehand v4 work?
Stagehand v4 operates on three natural-language primitives that form its core API: act(), observe(), and extract(). Each one solves a different piece of the agent-web interaction.
act(action) runs an action described in free text on the page. Instead of writing page.click('#submit-button') and crossing your fingers that the selector did not change, you describe what you want: \"click the buy button\". Stagehand uses a language model to interpret the intent, locate the relevant element in the DOM (or in Chrome's accessibility tree), and execute the action. If the page changes tomorrow and the button now has class .purchase-btn instead of #submit-button, your script still works.
observe() inspects the page and returns a list of detected interactive elements, with metadata about their type, position, and context. It is useful for debugging what the agent sees before acting, or for building pipelines where the agent first "looks" and then decides.
extract(schema) extracts structured data from the page, validating it against a schema you define. If you need prices, product names, and availability from an online store, you describe the expected structure and Stagehand returns typed JSON, not raw HTML that you then have to parse with cheerio.
Version 4 introduces important changes to the SDK lifecycle. In v3 you created a Stagehand instance and it launched the browser for you. In v4 the order is inverted: you launch or connect the browser first, then create Stagehand by passing that instance to it. This reflects the new architecture: Stagehand no longer "owns" the browser; it runs "alongside it" as an extension that the SDK communicates with.
Another significant change: agent() has been removed. In previous versions, Stagehand included an autonomous orchestrator that could run sequences of actions without programmer intervention. Version 4 drops that idea. The control flow is once again your responsibility; Stagehand provides the low-level primitives, but you decide when to act, when to observe, and when to extract. It is an explicit bet on transparency and control over opaque magic.
How does Stagehand v4 differ from Playwright and Puppeteer?
The most honest comparison comes from Browserbase's own documentation: "Playwright was built for testing; Stagehand was built for agents." This distinction is not marketing; it translates into concrete technical decisions.
| Feature | Stagehand v4 | Playwright | Puppeteer |
|---|---|---|---|
| Primary purpose | Autonomous AI agents | End-to-end testing | Chrome automation |
| Control API | Natural language (act, extract) + code | Deterministic selectors | Deterministic selectors |
| Resilience to UI changes | High (self-healing) | Low (fragile selectors) | Low (fragile selectors) |
| Performance (v4 claim) | 2x vs Playwright | Baseline | Similar to Playwright |
| Token efficiency | 80% more efficient | N/A (does not use LLM) | N/A (does not use LLM) |
| v4 architecture | Native browser extension | External CDP process | External CDP process |
| Orchestration | Manual (removed agent()) | Manual | Manual |
| iframes / Shadow DOM support | Yes (nested, out-of-process) | Yes | Partial |
Playwright and Puppeteer shine when you know the structure of the page and need to repeat the same sequence a thousand times deterministically. They are testing tools: fast, predictable, but fragile when things change. When the CSS changes, broken tests pile up in the QA team's inbox.
Stagehand bets on the opposite case: pages that change constantly, flows where the structure is not known ahead of time, or tasks where the cost of keeping selectors updated exceeds the cost of using a language model. The design question is not "which is faster?" but "where do you want to spend your engineering hours: keeping selectors alive or paying LLM tokens?"
A concrete data point: Browserbase reports that Stagehand v4 is approximately 2x faster than Playwright in its internal benchmarks, and 80% more token-efficient than earlier versions of Stagehand. These figures come from the vendor itself, so take them as product claims, not as independently verified neutral truth. What is verifiable without trusting Browserbase: the native extension architecture, the removal of the agent() method, and the existence of the three-primitive API documented in open source.
When does Stagehand v4 make sense?
Use Stagehand v4 when you are building agents that need to navigate the web without anyone having written a detailed map of every page. Web scraping of structured but not static sites, automation of login flows that change every month, extraction from enterprise dashboards with unpredictable DOMs, or any task where "understanding the page the way a human would" is worth more than "executing the exact sequence you programmed six months ago."
Do not use Stagehand v4 when you need absolute determinism, raw execution speed above all else, or you operate in an environment where LLM token cost is prohibitive. If your use case is "fill this identical form 10,000 times a day," Playwright will be cheaper and faster. If you work in financial regulation where every action must be audited and reproducible to the millimeter, Stagehand's interpretation layer adds complexity you may not want.
Version 4, by removing the agent() orchestrator, also stops being the tool for whoever wanted "a bot that does complex tasks on its own." Now you have to build the decision loop, the state memory, and the retry logic yourself. Stagehand gives you sharp low-level tools; the full agent is something you assemble, or you use another framework (such as CrewAI, LangGraph, or your own code) that orchestrates Stagehand as one of its tools.
What changes in the migration from v3 to v4?
If you come from Stagehand v3, there are three breaking changes that will break your existing code.
First: the browser lifecycle. In v3 you did const stagehand = new Stagehand({...}); await stagehand.init(); and Stagehand launched the browser for you. In v4 you launch the browser with Playwright or Puppeteer first, then pass that instance to Stagehand. The SDK no longer manages the browser process; it only connects to it.
Second: serverCache is renamed to cache, and the client-side cache disappears. Version 4 centralizes all caching on the server (the browser extension), removing the duplication of state between client and server that existed in v3.
Third: agent() no longer exists. If your code used stagehand.agent({...}) for multi-step autonomous tasks, you will need to rewrite that flow using the act/observe/extract primitives inside your own orchestration logic. The official migration docs suggest this change was intentional, to give developers more control over agent behavior.
Additionally, access to pages and contexts becomes asynchronous because it now travels through the browser extension instead of holding local references in the SDK process.
Who is Stagehand v4 for?
Stagehand v4 targets developers who build data pipelines, enterprise automation tools, or software agents that need to interact with the modern web as it is: changing, inconsistent, designed for humans, not for bots.
If you are a data engineer tired of fixing broken selectors every time a frontend team redesigns its dashboard, Stagehand offers a viable alternative. If you are an AI agent developer looking for a navigation layer that understands pages semantically rather than doing blind pattern matching on the DOM, Stagehand is a serious option alongside alternatives like Browser Use or Skyvern.
The learning curve is gentle if you already know Playwright: the traditional methods (goto, click, type, screenshot) remain available and you can mix them with the AI primitives. But the real promise of Stagehand is not "Playwright but easier"; it is "Playwright but it does not break when the web changes." That resilience comes at a price in tokens and latency; the question is whether that price is lower than the maintenance cost of the alternative.
What release of Stagehand is current right now?
The most recent and verifiable release of Stagehand today is v3.7.5, tagged as stagehand-server-v3/v3.7.5 on GitHub and published on August 20, 2026, alongside browse@0.9.6. That version includes the following changes documented in the diff compared with browse@0.9.6:
fix(v3): normalize CUA coordinates to actual viewport(#2767): before this, CUA (Chrome UA) coordinates were not normalized to the actual viewport, which could drift click or move actions on pages where the element's position depends on the current viewport. This fix makes the coordinates the action receives match what the browser shows.fix(v3): preserve provider for structured output(#2775): in structured output operations, the configured provider is preserved instead of being lost when the call is redirected; this affects the stability of structured extractions in production.fix(server-v3): release useTouch parameter(#2711): theuseTouchparameter is removed from the release and no longer forms part of the documented contract.chore(release): retarget release automation from main to v3(#2660) andchore(release)(#2384): release infrastructure adapted to the v3 branch flow.
Watch out for version confusion: a Stagehand v4.0.2 released in August 2026 does not exist. The tag circulating without verification returns a 404 on GitHub; what you actually have today is v3.7.5 as the last verifiable tag. This matters because the SDK is still evolving on the v3 branch; if you start from an article that cited v4.0.2, today that number does not hold up.
What is verifiable today without trusting Browserbase's documentation: the latest Stagehand release version, the four changes listed above, and the existence of the associated diff on GitHub. The performance figures (2x, 80%) remain vendor claims and are still not an independently reproducible benchmark; this section does not move those figures, it only adds the actual release state.
For AI tools for developers and to place Stagehand in the context of the rest of the ecosystem, see AI tools for developers.
FAQ
Is Stagehand v4 free? The SDK is open source under the MIT license and you can use it locally at no cost. However, for production scale with remote browsing, Browserbase offers cloud browser infrastructure as a complementary service, with usage-based pricing.
Does Stagehand v4 replace Playwright? No. It is complementary. You can use Stagehand for the parts of your flow where you need semantic resilience, and fall back to traditional Playwright methods when you need determinism and speed. In fact, Stagehand v4 requires you to launch the browser with Playwright (or Puppeteer) before connecting Stagehand.
What language models does Stagehand v4 support? Stagehand is designed to be provider-agnostic. It works with OpenAI, Anthropic, and any provider compatible with the chat completions interface. The model choice directly affects cost and action accuracy.
Is Stagehand v4 suitable for automated testing? It is not its primary use case. If you need deterministic testing with precise assertions, Playwright remains the standard tool. Stagehand shines in agent automation where flexibility matters more than exact reproducibility.
How does it compare to Browser Use or Skyvern?
All three target the same space: AI-assisted web navigation. Browser Use and Skyvern tend to offer more complete agent orchestration "out of the box," while Stagehand v4, after removing agent(), positions itself as a more primitive navigation layer that you orchestrate. The choice depends on how much control you want over the agent flow.
Can I use Stagehand v4 with Python?
Yes. Although the project started in TypeScript, there is an official Python SDK (browserbase/stagehand-python) that exposes the same act, extract, and observe primitives.
Does Stagehand v4 work with iframes and Shadow DOM? Yes, and it is one of its documented strengths. It supports nested iframes, out-of-process iframes, and closed Shadow DOM. This makes it viable for automating complex modern web applications that use these technologies extensively.
What is the relationship between Stagehand and Browserbase? Stagehand is developed by Browserbase, a browser infrastructure platform for automation. The SDK is open source and usable independently, but Browserbase offers cloud browser hosting, integrated proxies, and scaling as a complementary service.