Stagehand Integration

View as markdown

Stagehand is an AI-powered browser automation framework that combines natural language instructions with code-based precision. Connect it to Scrapfly Cloud Browser for intelligent, self-healing automation with built-in proxies and fingerprinting.

Beta Feature: Cloud Browser is currently in beta.

What is Stagehand?

Stagehand is a browser automation framework that uses AI to understand and interact with web pages using natural language. Built on Playwright, it offers:

Natural Language Control - Describe actions in plain English instead of writing complex selectors
Self-Healing Automation - AI adapts when website structures change
Smart Caching - Reduces AI costs by caching repeated actions
Hybrid Approach - Mix AI actions with traditional code for reliability

Installation

Install Stagehand via npm:

npm install @browserbase/stagehand

Stagehand requires an LLM API key (OpenAI, Anthropic, etc.) for AI-powered actions. Set OPENAI_API_KEY or configure your preferred provider.

Quick Start with AI Actions

Connect Stagehand to Cloud Browser and use AI to interact with pages:

import { Stagehand } from "@browserbase/stagehand";

const API_KEY = '';
const BROWSER_WS = `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&proxy_pool=datacenter&os=linux`;

async function run() {
    // Initialize Stagehand with Cloud Browser
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: BROWSER_WS,
    });

    await stagehand.init();

    // Navigate to a page
    await stagehand.page.goto('https://web-scraping.dev');

    // Use AI to perform actions with natural language
    await stagehand.act("click on the products link");

    // Extract data using AI
    const products = await stagehand.extract({
        instruction: "extract all product names and prices",
        schema: {
            products: [{
                name: "string",
                price: "string"
            }]
        }
    });

    console.log('Products:', products);

    await stagehand.close();
}

run();

AI-Powered Scraping

Use Stagehand's AI capabilities to scrape complex, dynamic websites without writing selectors:

import { Stagehand } from "@browserbase/stagehand";
import { z } from "zod";

const API_KEY = '';
const BROWSER_WS = `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&proxy_pool=datacenter`;

async function scrapeWithAI() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: BROWSER_WS,
    });

    await stagehand.init();
    await stagehand.page.goto('https://web-scraping.dev/products');

    // Define extraction schema with Zod
    const ProductSchema = z.object({
        products: z.array(z.object({
            title: z.string(),
            price: z.string(),
            rating: z.number().optional(),
        }))
    });

    // AI extracts data matching the schema
    const result = await stagehand.extract({
        instruction: "extract all products with their title, price, and rating",
        schema: ProductSchema,
    });

    console.log('Extracted products:', result.products);

    await stagehand.close();
    return result;
}

scrapeWithAI();

Natural Language Interactions

Handle complex workflows like login flows using natural language instead of brittle selectors:

import { Stagehand } from "@browserbase/stagehand";

const API_KEY = '';
const BROWSER_WS = `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&proxy_pool=datacenter`;

async function login() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: BROWSER_WS,
    });

    await stagehand.init();
    await stagehand.page.goto('https://web-scraping.dev/login');

    // Use natural language to interact with the login form
    await stagehand.act("fill in the email field with user@example.com");
    await stagehand.act("fill in the password field with mypassword");
    await stagehand.act("click the login button");

    // Wait for login to complete
    await stagehand.page.waitForURL('**/dashboard');

    // Verify login success with AI
    const isLoggedIn = await stagehand.extract({
        instruction: "check if the user is logged in",
        schema: z.object({
            loggedIn: z.boolean(),
            username: z.string().optional()
        })
    });

    console.log('Login successful:', isLoggedIn);

    await stagehand.close();
}

login();

Multi-Step AI Agent

Use Stagehand's autonomous agent mode to complete complex, multi-step tasks:

import { Stagehand } from "@browserbase/stagehand";

const API_KEY = '';
const BROWSER_WS = `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&proxy_pool=residential`;

async function autonomousAgent() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: BROWSER_WS,
    });

    await stagehand.init();
    await stagehand.page.goto('https://web-scraping.dev');

    // Agent autonomously completes the task
    const result = await stagehand.agent({
        instruction: `
            1. Find all product categories
            2. Click on the first category
            3. Extract the top 5 products with prices
            4. Return the results
        `
    });

    console.log('Agent result:', result);

    await stagehand.close();
}

autonomousAgent();

Hybrid: AI + Traditional Code

Combine AI actions with traditional Playwright code for the best of both worlds:

import { Stagehand } from "@browserbase/stagehand";

const API_KEY = '';
const BROWSER_WS = `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&proxy_pool=datacenter`;

async function hybridAutomation() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: BROWSER_WS,
    });

    await stagehand.init();

    // Traditional Playwright code for known, predictable steps
    await stagehand.page.goto('https://web-scraping.dev/products');
    await stagehand.page.waitForSelector('.product');

    // Switch to AI for complex or changing UI
    await stagehand.act("sort products by price from high to low");
    await stagehand.act("click on the most expensive product");

    // Back to traditional code for data extraction
    const title = await stagehand.page.locator('h1').textContent();
    const price = await stagehand.page.locator('.price').textContent();

    console.log(`Product: ${title}, Price: ${price}`);

    await stagehand.close();
}

hybridAutomation();

Session Persistence

Maintain browser state across Stagehand connections using the session parameter:

import { Stagehand } from "@browserbase/stagehand";

const API_KEY = '';
const SESSION_ID = 'my-ai-session';

// First connection: Login with AI
async function firstConnection() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&session=${SESSION_ID}`,
    });

    await stagehand.init();
    await stagehand.page.goto('https://web-scraping.dev/login');

    await stagehand.act("log in with email user@example.com and password mypassword");

    await stagehand.close();  // Session is preserved
}

// Second connection: Reuse the session
async function secondConnection() {
    const stagehand = new Stagehand({
        env: "BROWSERBASE",
        browserbaseConnectURL: `wss://' ~ public_cloud_browser_endpoint ~ '?api_key=${API_KEY}&session=${SESSION_ID}`,
    });

    await stagehand.init();
    await stagehand.page.goto('https://web-scraping.dev/dashboard');
    // Already logged in from previous session!

    const data = await stagehand.extract({
        instruction: "get user account information"
    });

    console.log('User data:', data);

    await stagehand.close();
}

Proxy Options

Proxy Pool	Use Case	Cost
`datacenter`	General scraping, high speed, lower cost	1 credits/30s + 2 credits/MB
`residential`	Protected sites, geo-targeting, AI-powered bypass	1 credits/30s + 10 credits/MB

Best Practices

Set LLM API key - Configure OPENAI_API_KEY or your preferred AI provider
Use caching - Stagehand automatically caches AI actions to reduce costs
Mix AI and code - Use AI for complex/changing UI, code for predictable steps
Close browsers - Always call stagehand.close() to stop billing
Preview actions - Use Stagehand's preview mode in development to verify AI actions
Handle errors - Wrap AI actions in try/catch for robust automation

Cost Optimization

Stagehand automation combines Cloud Browser costs with LLM API costs:

Cloud Browser - Billed per time + bandwidth (see table above)
LLM API - Billed by your AI provider (OpenAI, Anthropic, etc.)
Caching - Stagehand caches actions automatically to minimize LLM calls
Hybrid approach - Use traditional code where possible to reduce AI costs

Tip: Stagehand's smart caching can reduce LLM costs by up to 90% for repeated workflows.