> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driver.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stagehand

> Build AI-native browser automations with Stagehand

[Stagehand](https://github.com/browserbase/stagehand) is an AI-native browser automation framework that uses natural language to interact with web pages.

## Installation

```bash theme={null}
npm install @browserbasehq/stagehand @browsercash/sdk zod
```

<Note>
  CDP URL attachment requires Stagehand 2.0 or newer. In `LOCAL` mode, Stagehand also needs an API key for your chosen model provider.
</Note>

```bash theme={null}
DRIVER_API_KEY=your-driver-key
OPENAI_API_KEY=your-openai-key
```

## Quick Start

```typescript TypeScript theme={null}
import { Stagehand } from '@browserbasehq/stagehand';
import BrowsercashSDK from '@browsercash/sdk';
import { z } from 'zod';

async function run() {
  const client = new BrowsercashSDK({
    apiKey: process.env.DRIVER_API_KEY!,
    baseURL: "https://api.driver.dev",
  });

  // Create Driver session
  const session = await client.browser.session.create({ type: 'hosted' });

  // Initialize Stagehand with Driver CDP URL
  const stagehand = new Stagehand({
    env: 'LOCAL',
    model: 'openai/gpt-5',
    localBrowserLaunchOptions: {
      cdpUrl: session.cdpUrl,
    },
  });

  await stagehand.init();

  const page = stagehand.context.pages()[0] || await stagehand.context.newPage();
  await page.goto('https://example.com');

  // Extract data using natural language
  const data = await stagehand.extract(
    'Extract the page title and main heading',
    z.object({
      title: z.string(),
      heading: z.string(),
    })
  );

  console.log(data);

  // Cleanup
  await stagehand.close();
  await client.browser.session.stop({ sessionId: session.sessionId });
}

run().catch(console.error);
```

## Key Features

### Natural Language Actions

```typescript TypeScript theme={null}
// Click elements
await stagehand.act('click the sign up button');

// Fill forms
await stagehand.act('enter "John Doe" in the name field');

// Navigate
await stagehand.act('scroll down to the pricing section');
```

### Structured Data Extraction

```typescript TypeScript theme={null}
const products = await stagehand.extract(
  'Extract all products with their prices',
  z.array(z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  }))
);
```

### Observe Page State

```typescript TypeScript theme={null}
const observations = await stagehand.observe('What actions can I take on this page?');
```

## With Session Options

```typescript TypeScript theme={null}
const session = await client.browser.session.create({
  country: 'US',
  type: 'hosted',
  windowSize: '1920x1080',
  profile: { name: 'stagehand-session', persist: true },
});
```

## Complex Workflows

```typescript TypeScript theme={null}
// Multi-step workflow with error handling
async function checkoutFlow(stagehand: Stagehand) {
  const page = stagehand.context.pages()[0] || await stagehand.context.newPage();
  await page.goto('https://shop.example.com');

  await stagehand.act('search for "laptop"');
  await stagehand.act('click on the first product');
  await stagehand.act('add to cart');
  await stagehand.act('go to checkout');

  const cartSummary = await stagehand.extract(
    'Extract the cart total and item count',
    z.object({
      total: z.string(),
      itemCount: z.number(),
    })
  );

  return cartSummary;
}
```

## Why Stagehand + Driver?

* **AI-native** — Use natural language instead of brittle selectors
* **Self-healing** — Adapts to UI changes automatically
* **Hosted browsers** — Run Stagehand on managed Chrome sessions
* **Scalable** — No local browser management needed