What is Stagehand?

TL;DR Stagehand is the open-source SDK for browser agents. It combines familiar Playwright-style APIs with AI methods for interpreting pages, with clients for TypeScript, Python, and Go. You choose how much AI each step uses.

What Stagehand does#

An order’s shipping status may be available in a supplier portal before it reaches your application’s database. An agent handling a support request needs a way to open that portal, find the order, and bring the answer back.

Stagehand gives you two layers of control. Playwright-style page APIs let your agent navigate, click, type, and take screenshots directly. AI primitives (act(), extract(), and observe()) handle natural-language steps. You can mix both in the same script.

That combination is useful when a workflow mixes predictable navigation with pages whose structure changes. A selector such as #order-status-cell depends on specific markup. An instruction such as "read the status next to the most recent order" describes the information you want. It can accommodate some page changes without a new selector, though changes can still break a workflow. You need to check the results.

A concrete workflow#

To check whether an order has shipped, your agent can follow these steps in an authenticated browser session.

1. Navigate to the portal's orders URL with page.goto().
2. Use act() to open the order’s details.
3. Use extract() to read the order number, shipping status, and expected delivery date.
4. Check that the returned order number matches the one you need.
5. Save the result in your application.

The navigation is ordinary browser code. Finding the right order and reading its details are steps Stagehand can interpret. Validation and storage stay in your application, where you already know which order you are tracking and what to do with its status.

AI primitives and browser APIs#

Stagehand’s AI primitives cover three jobs.

• act() performs actions such as clicking a button, filling a field, or choosing an option. You describe the action, and Stagehand uses the page to find its target.
• extract() reads structured data. You describe what you want and supply a schema, which defines the result's fields and types. For the supplier portal, that might mean an order number and shipping status. Check the values as well as their shape.
• observe() discovers possible actions without performing them. If the orders page has several similar links, you can inspect the suggested actions before choosing one to execute.

Alongside these, Stagehand provides page and locator methods for navigation, clicks, typing, and screenshots. When you know exactly what to target, use those methods without asking a model to interpret the step.

Where it fits in an application#

Stagehand sits inside a program you write. A scheduled job might check the supplier portal each morning; an agent might check it after a customer asks about an order. In either case, Stagehand operates the browser, while your application or agent controls the sequence of steps, handles errors, and decides when the task is complete.

For the order workflow, your code might retry a failed page load, stop when an order cannot be found, or ask someone to review an unexpected status. Those decisions belong alongside the rest of your application logic.

How Stagehand relates to Browserbase#

Stagehand is the open-source SDK built by Browserbase. Browserbase is the platform to build and deploy agents that browse and interact with the web like humans. It runs browser infrastructure and provides tools such as session replay and Model Gateway to help you operate and debug agents. You can also run Stagehand with a local browser.

Stagehand v4 uses a shared browser-extension core and targets Chromium-based browsers. It has its own browser APIs, with no Playwright or Puppeteer dependency. The browser and SDK have separate lifecycles. Launch or connect a browser, create Stagehand against it, and close both when your workflow is done.

The AI methods also need access to a language model. With a Browserbase browser, Model Gateway can supply that access. With a local browser, configure a model-provider API key or a custom inference callback. Browser hosting and model inference are separate choices; see the browser configuration guide for setup.

When to use it#

Use Stagehand when your agent needs to read a portal, fill a form, or gather information from a dashboard without a usable API. Combine exact browser operations with AI methods where interpreting the page helps.

If a service already exposes an API for the data you need, calling that API may be simpler. For a stable page with known selectors, direct browser methods may be enough. Account for model latency and cost when adding AI calls.

Follow the quickstart, then give your agent one browser task it cannot complete through an API. Opening a portal and returning an order status is enough to put the browser interface to work.

Frequently asked questions#