Skip to main content

​
Overview

Stagehand v3 can work alongside Selenium WebDriver, allowing both tools to operate on the same browser session simultaneously. This enables you to combine Stagehand’s AI-powered automation with Selenium’s precise element interactions.
Browserbase Only: This integration requires Browserbase. It does not work with env: "LOCAL" because Selenium needs a remote WebDriver endpoint.

​
Installation

Install Stagehand, Selenium, and the Browserbase SDK: 
npm install @browserbasehq/stagehand selenium-webdriver @browserbasehq/sdk

​
Quickstart

​
Create Shared Session

Use the Browserbase SDK to create a session that both tools can connect to: 
import http from "http";
import { Builder, Key } from "selenium-webdriver";
import Browserbase from "@browserbasehq/sdk";
import { Stagehand } from "@browserbasehq/stagehand";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY,
});

// Create shared session
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
});

console.log("Session created:", session.id);

​
Connect Stagehand

Initialize Stagehand with the session ID: 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionID: session.id,
  model: "openai/gpt-4o",
  verbose: 2,
});

await stagehand.init();

​
Connect Selenium

Use a custom HTTP agent with the session’s signing key: 
// Create custom HTTP agent with signing key
const customHttpAgent = new http.Agent({});
(customHttpAgent as any).addRequest = (req: any, options: any) => {
  req.setHeader("x-bb-signing-key", session.signingKey);
  (http.Agent.prototype as any).addRequest.call(customHttpAgent, req, options);
};

// Connect Selenium WebDriver
const driver = new Builder()
  .forBrowser("chrome")
  .usingHttpAgent(customHttpAgent)
  .usingServer(session.seleniumRemoteUrl)
  .build();

​
Use Both Tools Together

Now both Stagehand and Selenium operate on the same browser: 
// Navigate with Stagehand
const page = stagehand.context.pages()[0];
await page.goto("https://www.google.com");

// Extract page content with Stagehand AI
const pageContent = await stagehand.extract();
console.log("Page content:", pageContent);

// Use Selenium for precise element interaction
const searchBox = await driver.findElement({ name: "q" });
await searchBox.sendKeys("Browserbase automation");
await searchBox.sendKeys(Key.RETURN);

// Wait for results
await driver.sleep(2000);

console.log("Search completed!");

​
Complete Example

import http from "http";
import { Builder, Key } from "selenium-webdriver";
import Browserbase from "@browserbasehq/sdk";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  // Initialize Browserbase
  const bb = new Browserbase({
    apiKey: process.env.BROWSERBASE_API_KEY,
  });

  // Create shared session
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID,
  });

  // Connect Stagehand
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    browserbaseSessionID: session.id,
    model: "openai/gpt-4o",
  });

  await stagehand.init();

  // Connect Selenium
  const customHttpAgent = new http.Agent({});
  (customHttpAgent as any).addRequest = (req: any, options: any) => {
    req.setHeader("x-bb-signing-key", session.signingKey);
    (http.Agent.prototype as any).addRequest.call(customHttpAgent, req, options);
  };

  const driver = new Builder()
    .forBrowser("chrome")
    .usingHttpAgent(customHttpAgent)
    .usingServer(session.seleniumRemoteUrl)
    .build();

  try {
    // Navigate with Stagehand
    const page = stagehand.context.pages()[0];
    await page.goto("https://example.com");

    // Use AI to extract data
    const data = await stagehand.extract(
      "extract the heading",
      z.object({ heading: z.string() }),
      { page }
    );

    console.log("Extracted:", data);

    // Use Selenium for precise interactions
    const link = await driver.findElement({ linkText: "More information" });
    await link.click();

    console.log("Navigation completed");
  } finally {
    // Cleanup
    await driver.quit();
    await stagehand.close();
  }
}

main();

​
Key Points

  • Shared Session: Both tools connect to the same Browserbase session
  • Signing Key: Selenium requires the session’s signingKey in HTTP headers
  • Remote URL: Use session.seleniumRemoteUrl for Selenium’s server endpoint
  • Concurrent Usage: Both tools can operate on the browser simultaneously
  • Cleanup: Close both Stagehand (await stagehand.close()) and Selenium (await driver.quit())

​
Environment Variables

BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
OPENAI_API_KEY=your_openai_key

​
Next Steps

Agent

Automate entire workflows

Act

Execute actions on web pages

Extract

Extract structured data from pages

Observe

Observe and find elements on pages

Build docs developers (and LLMs) love

Get started for freeTalk to us