Skip to content

Run Stagehand on Steel

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

Stagehand is a library for browser automation in natural language. Its act and extract calls take an instruction such as "click the sign-in button" instead of a selector, and a model finds the element. With Steel, Stagehand drives a Steel session over the Chrome DevTools Protocol (CDP). You start Stagehand in its local mode and give it the session's CDP URL, so Stagehand does not launch a browser of its own. Proxies, CAPTCHA solving and the live view come from the session.

Stagehand has TypeScript and Python SDKs, and their APIs differ. In Python, Stagehand runs a local server, and act and extract return a stream of events.

Before you begin

  • For TypeScript, Node.js 20.19+ or 22.12+. For Python, Python 3.10 or later.
  • A Steel API key in the STEEL_API_KEY environment variable. See API keys.
  • A key for Stagehand's model. The programs on this page use OpenAI, with the key in OPENAI_API_KEY.

Install Stagehand 3 and the Steel SDK. The programs on this page do not work with Stagehand 4. When Stagehand 4 connects, it loads a browser extension from a folder on your machine, and a Steel session refuses that request.

npm install @browserbasehq/stagehand@3 steel-sdk zod

Set up the integration

Connect Stagehand to a session

This program creates a session, connects Stagehand to the session's CDP URL, opens Hacker News and extracts the first five stories. It closes Stagehand and releases the session in finally. CDP explains the URL.

stagehand.mts
import { Stagehand } from "@browserbasehq/stagehand";
import Steel from "steel-sdk";
import { z } from "zod";

const client = new Steel();
const session = await client.sessions.create();
console.log("Session viewer:", session.sessionViewerUrl);

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    cdpUrl: session.websocketUrl,
  },
  model: { modelName: "openai/gpt-6.1-sol", apiKey: process.env.OPENAI_API_KEY },
});

try {
  await stagehand.init();
  const page = await stagehand.context.awaitActivePage();
  await page.goto("https://news.ycombinator.com");

  const { stories } = await stagehand.extract(
    "extract the titles and ranks of the first 5 stories on the page",
    z.object({
      stories: z.array(z.object({ title: z.string(), rank: z.number() })),
    }),
  );
  for (const story of stories) {
    console.log(`${story.rank}. ${story.title}`);
  }
} finally {
  await stagehand.close();
  await client.sessions.release(session.id);
}

The Python file is not named stagehand.py, because that name would hide the stagehand package from the import. In Python, Stagehand has its own session ID, stagehand_id. It is not the Steel session's ID.

Run the program

npx tsx stagehand.mts

The program prints the session viewer URL, then the rank and title of the first five stories on Hacker News. The stories change from run to run.

Session viewer: https://app.steel.dev/sessions/f6630a88-fbfd-422e-8f9f-b2a90cdc9d0e

Act on the page

act takes an instruction and clicks, types or scrolls. Add it after extract:

await stagehand.act("click the 'new' link in the top navigation");

Add Steel features to the session

Pass session options to client.sessions.create(). Stagehand does not see them. For example, this session uses a Steel proxy and solves CAPTCHAs:

const session = await client.sessions.create({
  useProxy: true,
  solveCaptcha: true,
});

On Launch, Steel proxies and CAPTCHA solving need a verified account, as Verify a Launch account explains. Session configuration lists every option.

Next steps