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

# Stagehand

> Complete API reference for the Stagehand class

export const V3Banner = () => null;

<V3Banner />

<CardGroup cols={1}>
  <Card title="Getting Started" icon="rocket" href="/v3/first-steps/quickstart">
    The fastest way to start using Stagehand
  </Card>
</CardGroup>

## Overview

The `Stagehand` class is the main entry point for Stagehand v3. It manages browser lifecycle, provides AI-powered automation methods, and handles both local and remote browser environments.

```typescript theme={null}
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand(options);
await stagehand.init();
```

## Constructor

### new Stagehand()

Create a new Stagehand instance.

```typescript theme={null}
const stagehand = new Stagehand(options: V3Options);
```

**V3Options Interface:**

```typescript theme={null}
interface V3Options {
  env: "LOCAL" | "BROWSERBASE";

  // Browserbase options (required when env = "BROWSERBASE")
  apiKey?: string;
  browserbaseSessionID?: string;
  browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;

  // Local browser options
  localBrowserLaunchOptions?: LocalBrowserLaunchOptions;

  // AI/LLM configuration
  model?: ModelConfiguration;
  llmClient?: LLMClient;
  systemPrompt?: string;

  // Behavior options
  selfHeal?: boolean;
  experimental?: boolean;
  domSettleTimeout?: number;
  cacheDir?: string;
  keepAlive?: boolean;
  serverCache?: boolean;

  // Logging options
  verbose?: 0 | 1 | 2;
  logInferenceToFile?: boolean;
  disablePino?: boolean;
  logger?: (line: LogLine) => void;
}
```

### Configuration Parameters

<ParamField path="env" type="&#x22;LOCAL&#x22; | &#x22;BROWSERBASE&#x22;" required>
  Environment to run the browser in.

  * **`"LOCAL"`** - Run browser locally using Chrome/Chromium
  * **`"BROWSERBASE"`** - Run browser on Browserbase cloud platform
</ParamField>

#### Browserbase Options

<ParamField path="apiKey" type="string" optional>
  Browserbase API key. Required when `env` is `"BROWSERBASE"`.

  Can also be set via `BROWSERBASE_API_KEY` environment variable.
</ParamField>

<ParamField path="browserbaseSessionID" type="string" optional>
  Resume an existing Browserbase session by ID instead of creating a new one.
</ParamField>

<ParamField path="browserbaseSessionCreateParams" type="object" optional>
  Additional parameters for Browserbase session creation. See [Browserbase documentation](https://docs.browserbase.com) for details.
</ParamField>

#### Local Browser Options

<ParamField path="localBrowserLaunchOptions" type="LocalBrowserLaunchOptions" optional>
  Configuration for local Chrome/Chromium browser.

  <Expandable title="LocalBrowserLaunchOptions">
    <ParamField path="headless" type="boolean" optional>
      Run browser in headless mode.

      **Default:** `true`
    </ParamField>

    <ParamField path="executablePath" type="string" optional>
      Path to Chrome/Chromium executable.
    </ParamField>

    <ParamField path="port" type="number" optional>
      Fixed Chrome DevTools Protocol (CDP) debugging port for external tool connections.

      **Default:** Randomly assigned
    </ParamField>

    <ParamField path="args" type="string[]" optional>
      Additional Chrome launch arguments.
    </ParamField>

    <ParamField path="userDataDir" type="string" optional>
      Path to user data directory for browser profile.
    </ParamField>

    <ParamField path="viewport" type="{ width: number; height: number }" optional>
      Default viewport size.
    </ParamField>

    <ParamField path="devtools" type="boolean" optional>
      Auto-open DevTools for each tab.

      **Default:** `false`
    </ParamField>

    <ParamField path="proxy" type="object" optional>
      Proxy configuration.

      **Properties:** `server`, `bypass`, `username`, `password`
    </ParamField>

    <ParamField path="ignoreHTTPSErrors" type="boolean" optional>
      Ignore HTTPS certificate errors.

      **Default:** `false`
    </ParamField>

    <ParamField path="cdpUrl" type="string" optional>
      Attach to existing Chrome instance via CDP WebSocket URL.
    </ParamField>
  </Expandable>
</ParamField>

#### AI/LLM Configuration

<ParamField path="model" type="ModelConfiguration" optional>
  Configure the AI model to use for automation. Can be either:

  * A string in the format `"provider/model"` (e.g., `"openai/gpt-4o"`, `"anthropic/claude-sonnet-4-6"`)
  * An object with detailed configuration

  <Expandable title="Model Configuration Object">
    <ParamField path="modelName" type="string" required>
      The model name (e.g., "gpt-4o", "claude-sonnet-4-6", "gemini-2.5-flash")
    </ParamField>

    <ParamField path="apiKey" type="string" optional>
      API key for the model provider (overrides environment variables)
    </ParamField>

    <ParamField path="baseURL" type="string" optional>
      Base URL for the API endpoint (for custom endpoints or proxies)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="llmClient" type="LLMClient" optional>
  Provide a custom LLM client implementation instead of using the default.
</ParamField>

<ParamField path="systemPrompt" type="string" optional>
  Custom system prompt to guide AI behavior across all operations.
</ParamField>

#### Behavior Options

<ParamField path="selfHeal" type="boolean" optional>
  Enable self-healing mode where actions can recover from failures.

  **Default:** `true`
</ParamField>

<ParamField path="experimental" type="boolean" optional>
  Enable experimental features (may change between versions).

  **Default:** `false`
  <Warning>**Use with caution in production**. Experimental features may break or change between versions without notice.</Warning>
</ParamField>

<ParamField path="domSettleTimeout" type="number" optional>
  Default timeout for waiting for DOM to stabilize (in milliseconds).

  **Default:** `30000`
</ParamField>

<ParamField path="cacheDir" type="string" optional>
  Directory path for caching action observations to improve performance.
</ParamField>

<ParamField path="keepAlive" type="boolean" optional>
  Controls whether the browser remains running after `stagehand.close()` is called or the parent process exits unexpectedly.

  * **`true`** - Browser continues running independently. On Browserbase, the session stays active. Locally, the Chrome process is kept alive.
  * **`false`** - Browser is terminated and resources are cleaned up on close or crash.

  When set, this overrides any value in `browserbaseSessionCreateParams.keepAlive`.

  **Default:** `false`
</ParamField>

<ParamField path="serverCache" type="boolean" optional>
  Enable or disable server-side caching for `act()`, `extract()`, and `observe()` requests. When enabled, repeated calls with the same inputs return instantly without consuming LLM tokens.

  <Note>Only applies when `env` is `"BROWSERBASE"`. Has no effect in local environments.</Note>

  Can be overridden per-call via the `serverCache` option on `act()`, `extract()`, and `observe()`.

  **Default:** `true`
</ParamField>

#### Logging Options

<ParamField path="verbose" type="0 | 1 | 2" optional>
  Logging verbosity level.

  * **`0`** - Minimal logging
  * **`1`** - Standard logging (default)
  * **`2`** - Detailed debug logging

  **Default:** `1`
</ParamField>

<ParamField path="logInferenceToFile" type="boolean" optional>
  Log AI inference details to files for debugging.

  **Default:** `false`
</ParamField>

<ParamField path="disablePino" type="boolean" optional>
  Disable the Pino logging backend (useful for custom logging integrations).

  **Default:** `false`
</ParamField>

<ParamField path="logger" type="(line: LogLine) => void" optional>
  Custom logger function to receive log events.
</ParamField>

## Methods

### init()

Initialize the Stagehand instance and launch the browser.

```typescript theme={null}
await stagehand.init(): Promise<void>
```

**Must be called before using any other methods.**

### close()

Close the browser and clean up resources.

```typescript theme={null}
await stagehand.close(options?: { force?: boolean }): Promise<void>
```

<ParamField path="force" type="boolean" optional>
  Force close even if already closing.

  **Default:** `false`
</ParamField>

<Note>
  When `keepAlive` is `true`, calling `close()` disconnects Stagehand from the browser without terminating it. The browser session continues running independently and can be reconnected to later using `browserbaseSessionID`. When `keepAlive` is `false` (the default), `close()` fully terminates the browser and cleans up all resources.
</Note>

### agent()

Create an AI agent instance for autonomous multi-step workflows.

```typescript theme={null}
stagehand.agent(config?: AgentConfig): AgentInstance
```

See the [agent() reference](/v3/references/agent) for detailed documentation.

## Properties

### page

Access pages for browser automation. Pages are accessed through the context.

```typescript theme={null}
// Get the first page (created automatically on init)
const page = stagehand.context.pages()[0];

// Or get the active page
const activePage = stagehand.context.activePage();

// Create a new page
const newPage = await stagehand.context.newPage();
```

**Type:** [`Page`](/v3/references/page)

The page object provides methods for:

* Navigation (`goto()`, `reload()`, `goBack()`, `goForward()`)
* Interaction (`click()`, `type()`, `keyPress()`, `locator()`, `deepLocator()`)
* Inspection (`url()`, `title()`, `screenshot()`)
* JavaScript evaluation (`evaluate()`)

<Note>
  **Important:** AI-powered methods ([`act()`](/v3/references/act), [`extract()`](/v3/references/extract), [`observe()`](/v3/references/observe)) are called on the stagehand instance, not on the page object.
</Note>

### context

Access the browser context for managing multiple pages.

```typescript theme={null}
const context = stagehand.context;
```

**Type:** `V3Context`

The context object provides:

* `newPage()` - Create a new page/tab
* `pages()` - Get all open pages
* `setActivePage(page)` - Switch active page

### metrics

Get usage metrics for AI operations.

```typescript theme={null}
const metrics = await stagehand.metrics;
```

**Returns:** `Promise<StagehandMetrics>`

**StagehandMetrics Interface:**

```typescript theme={null}
interface StagehandMetrics {
  // Act metrics
  actPromptTokens: number;
  actCompletionTokens: number;
  actReasoningTokens: number;
  actCachedInputTokens: number;
  actInferenceTimeMs: number;

  // Extract metrics
  extractPromptTokens: number;
  extractCompletionTokens: number;
  extractReasoningTokens: number;
  extractCachedInputTokens: number;
  extractInferenceTimeMs: number;

  // Observe metrics
  observePromptTokens: number;
  observeCompletionTokens: number;
  observeReasoningTokens: number;
  observeCachedInputTokens: number;
  observeInferenceTimeMs: number;

  // Agent metrics
  agentPromptTokens: number;
  agentCompletionTokens: number;
  agentReasoningTokens: number;
  agentCachedInputTokens: number;
  agentInferenceTimeMs: number;

  // Totals
  totalPromptTokens: number;
  totalCompletionTokens: number;
  totalReasoningTokens: number;
  totalCachedInputTokens: number;
  totalInferenceTimeMs: number;
}
```

### history

Get the history of all operations performed.

```typescript theme={null}
const history = await stagehand.history;
```

**Returns:** `Promise<ReadonlyArray<HistoryEntry>>`

**HistoryEntry Interface:**

```typescript theme={null}
interface HistoryEntry {
  method: "act" | "extract" | "observe" | "navigate";
  parameters: unknown;
  result: unknown;
  timestamp: string;
}
```

### browserbaseSessionID

Browserbase session identifier for the active Browserbase run.

```typescript theme={null}
const sessionId = stagehand.browserbaseSessionID;
```

**Type:** `string | undefined` — undefined for LOCAL runs or before `init()`.

### browserbaseSessionURL

Shareable link to the active Browserbase session dashboard.

```typescript theme={null}
const sessionUrl = stagehand.browserbaseSessionURL;
```

**Type:** `string | undefined` — undefined until a Browserbase session is active.

### browserbaseDebugURL

Debugger URL returned by Browserbase for direct CDP inspection.

```typescript theme={null}
const debugUrl = stagehand.browserbaseDebugURL;
```

**Type:** `string | undefined` — undefined for LOCAL runs or if Browserbase doesn’t provide one.

## Code Examples

<Tabs>
  <Tab title="Browserbase">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    // Remote browser on Browserbase
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      apiKey: process.env.BROWSERBASE_API_KEY,
      model: "anthropic/claude-sonnet-4-6"
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");
    const data = await stagehand.extract("get page title", z.object({
      title: z.string()
    }));

    await stagehand.close();
    ```
  </Tab>

  <Tab title="Local">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    // Local browser
    const stagehand = new Stagehand({
      env: "LOCAL",
      model: "openai/gpt-4o"
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    // Use the page
    await page.goto("https://example.com");
    await stagehand.act("click the login button");

    // Cleanup
    await stagehand.close();
    ```
  </Tab>

  <Tab title="Custom Model Config">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    const stagehand = new Stagehand({
      env: "LOCAL",
      model: {
        modelName: "gpt-4o",
        apiKey: process.env.OPENAI_API_KEY,
        baseURL: "https://custom-proxy.com/v1"
      },
      systemPrompt: "You are a helpful automation assistant.",
      verbose: 2,
      selfHeal: true
    });

    await stagehand.init();
    ```
  </Tab>

  <Tab title="Multi-Page">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

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

    // Get the first page
    const page1 = stagehand.context.pages()[0];
    await page1.goto("https://example.com");

    // Create second page
    const page2 = await stagehand.context.newPage();
    await page2.goto("https://another-site.com");

    // Switch active page
    stagehand.context.setActivePage(page2);

    // Now context.activePage() returns page2
    await stagehand.act("click the button");

    await stagehand.close();
    ```
  </Tab>

  <Tab title="With Metrics">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    const stagehand = new Stagehand({
      env: "LOCAL",
      model: "openai/gpt-4o"
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");
    await stagehand.act("fill out the form");
    await stagehand.extract("get form data", schema);

    // Get usage metrics
    const metrics = await stagehand.metrics;
    console.log("Total tokens used:", metrics.totalPromptTokens + metrics.totalCompletionTokens);
    console.log("Act operations:", {
      tokens: metrics.actPromptTokens + metrics.actCompletionTokens,
      time: metrics.actInferenceTimeMs
    });

    await stagehand.close();
    ```
  </Tab>

  <Tab title="With Custom Logger">
    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    const stagehand = new Stagehand({
      env: "LOCAL",
      verbose: 2,
      logger: (logLine) => {
        console.log(`[${logLine.category}] ${logLine.message}`);
        if (logLine.auxiliary) {
          console.log("Details:", logLine.auxiliary);
        }
      }
    });

    await stagehand.init();
    // All operations will now log through your custom logger
    ```
  </Tab>
</Tabs>

## Error Handling

Stagehand methods may throw the following errors:

* **StagehandInitError** - Failed to initialize Stagehand
* **StagehandNotInitializedError** - Methods called before `init()`
* **BrowserbaseSessionNotFoundError** - Browserbase session not found
* **MissingLLMConfigurationError** - No LLM API key or client configured
* **MissingEnvironmentVariableError** - Required environment variable not set
* **StagehandEnvironmentError** - Invalid environment configuration

Always handle errors appropriately:

```typescript theme={null}
try {
  const stagehand = new Stagehand({ env: "LOCAL" });
  await stagehand.init();
  // ... use stagehand
} catch (error) {
  console.error("Stagehand error:", error.message);
} finally {
  await stagehand?.close();
}
```

## Best Practices

1. **Always call `init()`** before using any other methods
2. **Always call `close()`** when done to clean up resources
3. **Use try-finally** to ensure cleanup even on errors
4. **Set appropriate timeouts** based on your use case
5. **Enable `selfHeal`** for more robust automation
6. **Use metrics** to monitor token usage and costs
7. **Configure custom logger** for production debugging
8. **Cache directory** can significantly improve performance for repeated actions

## Environment Variables

Stagehand recognizes the following environment variables:

* `BROWSERBASE_API_KEY` - Browserbase API key
* `OPENAI_API_KEY` - OpenAI API key
* `ANTHROPIC_API_KEY` - Anthropic API key
* `GOOGLE_API_KEY` - Google AI API key

These can be overridden by passing values in the constructor options.