Stagehand

Build browser agents with Stagehand + Browserbase

There’s a new way to automate the web: by prompting.

But a single prompt fails on complicated scripts. Stagehand lets you prompt at multiple levels of granularity—from agents to single actions—and interweave Playwright or traditional frameworks when you need them.

Use any major model provider. 22k GitHub stars, 700k+ weekly downloads. Get started in 5 minutes.

This quickstart uses Model Gateway — LLM requests for Stagehand are routed through your Browserbase API key, so you don’t need a separate model provider account. You can also bring your own API key if you prefer.

Discord

Community support

Docs

Full documentation

Templates

Ready-to-use examples

Quickstart

1. Get your API key

   Your API key and Project ID are displayed in the Dashboard Navigation row:

   
2. Set environment variables

   export BROWSERBASE_API_KEY="your-api-key"
   
3. Install and run

   Node.js

   pnpm

   pnpm add @browserbasehq/stagehand
   npm pkg set type=module
   

   import { Stagehand } from "@browserbasehq/stagehand";
   
   const stagehand = new Stagehand({
     env: "BROWSERBASE",
     model: "google/gemini-3-flash-preview",
   });
   await stagehand.init();
   
   const page = stagehand.context.pages()[0];
   await page.goto("https://news.ycombinator.com");
   
   // Let AI click
   await stagehand.act("click on the comments link for the top story");
   
   // Extract structured data
   const data = await stagehand.extract("extract the title and points of the top story");
   console.log(data);
   
   await stagehand.close();
   

   Save as script.ts, then run:

   pnpm

   pnpm dlx tsx script.ts
   

   Python

   uv init
   uv add stagehand
   

   from stagehand import Stagehand
   
   def main():
     client = Stagehand()
   
     response = client.sessions.start(model_name="google/gemini-3-flash-preview")
     session_id = response.data.session_id
     print(f"Session started: {session_id}")
   
     client.sessions.navigate(id=session_id, url="https://news.ycombinator.com")
     print("Navigated to Hacker News")
   
     # Let AI click
     act_result = client.sessions.act(id=session_id, input="click on the comments link for the top story")
     print(f"Act result: {act_result}")
   
     # Extract structured data
     result = client.sessions.extract(
         id=session_id,
         instruction="extract the title and points of the top story"
     )
     print(f"Extracted: {result}")
   
     client.sessions.end(id=session_id)
   
   if __name__ == "__main__":
     main()
   

   Save as script.py, then run:

   uv run script.py
   

   Java

   See the Java SDK documentation →

   Go

   See the Go SDK documentation →

   Ruby

   See the Ruby SDK documentation →

4. Debug in Session Inspector

   See every AI decision in the Stagehand tab of your session at https://browserbase.com/sessions/{session_id}.

Next steps

Stagehand docs

Learn about Stagehand primitives, models, and Browserbase configurations

npx create-browser-app

Scaffold a Stagehand project in one command. TypeScript, zero-config.