Stagehand — AI Browser Automation Framework

What it is

Stagehand is an AI browser automation framework built by Browserbase. It exposes three primitives -- act(), extract(), and observe() -- that let you automate web interactions using natural language instead of CSS selectors or XPaths. Behind the scenes, Stagehand uses vision models to understand the page and execute actions.

Stagehand is designed for developers building web scrapers, testing frameworks, or automation workflows who want to write instructions in plain English rather than brittle selector-based scripts. It runs locally or on Browserbase's cloud infrastructure.

How it saves time or tokens

Traditional browser automation with Puppeteer or Playwright requires writing and maintaining CSS selectors that break when the page layout changes. Stagehand's natural language approach is resilient to UI changes because it uses visual understanding rather than DOM structure.

The three-primitive API keeps the learning curve minimal. Instead of learning a complex automation framework, you write act('click the login button') and Stagehand handles the rest.

How to use

1. Install Stagehand:

npm install @browserbasehq/stagehand

1. Create an automation script:

import { Stagehand } from '@browserbasehq/stagehand';

const stagehand = new Stagehand({
  env: 'LOCAL',
  modelName: 'gpt-4o',
  modelClientOptions: { apiKey: process.env.OPENAI_API_KEY }
});

await stagehand.init();
await stagehand.page.goto('https://example.com');
await stagehand.act({ action: 'click the sign up button' });

1. Run your script with Node.js.

Example

import { Stagehand } from '@browserbasehq/stagehand';

const stagehand = new Stagehand({ env: 'LOCAL' });
await stagehand.init();
await stagehand.page.goto('https://news.ycombinator.com');

// Extract structured data from the page
const stories = await stagehand.extract({
  instruction: 'Extract the title and URL of the top 5 stories',
  schema: {
    type: 'array',
    items: {
      type: 'object',
      properties: {
        title: { type: 'string' },
        url: { type: 'string' }
      }
    }
  }
});

console.log(stories);
await stagehand.close();

This extracts structured data from Hacker News using natural language instructions and a JSON schema for the output format.

Related on TokRepo

• Browser automation tools -- Compare other AI-powered browser automation frameworks
• Web scraping tools -- Explore tools for extracting data from websites

Common pitfalls

• Stagehand requires an LLM API key (OpenAI or Anthropic). Each action sends a screenshot to the vision model, which costs tokens. High-frequency automation scripts can accumulate significant API costs.
• The LOCAL env mode requires a Chromium browser installed on the machine. If Chromium is missing, Stagehand will fail to initialize. Use Browserbase's cloud mode to avoid local browser management.
• Natural language instructions must be specific. Vague instructions like 'fill out the form' may produce unexpected results. Write precise actions like 'type john@example.com into the email field'.