Skip to main content

Stagehand - AI Browser Automation Framework

Key Point: AI-powered browser automation that combines natural language with code precision. Built by Browserbase for production reliability.

🚀 Quick Start​

npm install @browserbasehq/stagehand
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();

// Natural language actions
await stagehand.act("click the login button");
await stagehand.act("type 'search query' into the search box");

// Multi-step workflows
const agent = stagehand.agent();
await agent.execute("Search for laptops, filter by price under $1000, add best rated to cart");

// Extract structured data
const data = await stagehand.extract(
  "extract product name and price",
  z.object({ name: z.string(), price: z.string() })
);

await stagehand.close();

🎯 Three Core Methods​

act() - Individual Actions​

await stagehand.act("click the submit button");
await stagehand.act("fill in email with 'user@example.com'");
await stagehand.act("scroll to the bottom");

agent() - Multi-Step Tasks​

const agent = stagehand.agent();
await agent.execute("Navigate to Amazon, search for headphones, filter by price under $50, add to cart");

extract() - Data Extraction​

const product = await stagehand.extract(
  "extract name, price, and rating",
  z.object({
    name: z.string(),
    price: z.string(),
    rating: z.number()
  })
);

🔑 Key Features​

  • Self-Healing: Automatically adapts when websites change
  • Auto-Caching: Remembers actions, reduces AI costs on repeat tasks
  • Hybrid Approach: Mix AI flexibility with code precision
  • Production Ready: Built by Browserbase with enterprise features

📊 Comparison with Alternatives​

ToolAI IntegrationSelf-HealingAuto-CachingLearning Curve
Stagehand✅ Native✅ Auto✅ YesLow
Playwright❌ Manual❌ Manual❌ NoMedium
Selenium❌ Manual❌ Manual❌ NoHigh
Puppeteer❌ Manual❌ Manual❌ NoMedium

Choose Stagehand when:

  • Websites change frequently (self-healing needed)
  • You want both AI flexibility and code control
  • Production reliability is critical
  • Cost optimization matters (auto-caching)

💡 Day-to-Day Usage Examples​

Web Scraping​

// E-commerce data collection
const products = await stagehand.extract(
  "extract all products with name, price, and availability",
  z.object({
    products: z.array(z.object({
      name: z.string(),
      price: z.string(),
      available: z.boolean()
    }))
  })
);

Form Automation​

// Automated data entry
await stagehand.act("fill in the contact form with name, email, and message");
await stagehand.act("click the submit button");

// Verify submission
const confirmation = await stagehand.extract(
  "extract the success message",
  z.string()
);

Social Media Tasks​

const agent = stagehand.agent();
await agent.execute(`
  Go to LinkedIn, search for 'software engineers',
  view first 5 profiles, send connection requests with personalized messages
`);

Content Monitoring​

// Monitor price changes
const price = await stagehand.extract(
  "extract current price of the product",
  z.string()
);

// Compare with previous price and alert if changed

Sports Data Scraping (Flashscore Example)​

// Extract live football scores from Flashscore
const liveMatches = await stagehand.extract(
  "extract all live football matches with teams, scores, and time",
  z.object({
    matches: z.array(z.object({
      homeTeam: z.string(),
      awayTeam: z.string(),
      homeScore: z.number(),
      awayScore: z.number(),
      time: z.string(),
      status: z.string() // "Live", "FT", "HT", etc.
    }))
  })
);

// Extract league standings
const standings = await stagehand.extract(
  "extract Premier League table with team positions, points, and goal difference",
  z.object({
    teams: z.array(z.object({
      position: z.number(),
      name: z.string(),
      played: z.number(),
      won: z.number(),
      drawn: z.number(),
      lost: z.number(),
      points: z.number(),
      goalDiff: z.string()
    }))
  })
);

⚙️ Setup Options​

Browserbase (Production)​

export BROWSERBASE_API_KEY="your-key"
export BROWSERBASE_PROJECT_ID="your-project-id"

Local Development​

const stagehand = new Stagehand({
  env: "LOCAL",
  localOptions: { headless: false }
});

🛠️ Best Practices​

  • Use act() for simple actions, agent() for complex workflows
  • Be specific in instructions: "click the blue submit button" vs "click submit"
  • Combine AI with code: Use AI for discovery, code for precision
  • Enable caching: Automatic cost savings on repeated tasks
  • Handle errors gracefully: Websites change, automation should adapt

🔗 Resources​

Bottom Line: Stagehand = AI flexibility + Code precision + Production reliability. Perfect for modern web automation where websites evolve and reliability matters.