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-5", 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();
// 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!");
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())
Next Steps
