Quickstart (TS/Node)

Build AI agents that navigate the web using natural language instructions

link icon Try in Playground

This guide shows you how to use Stagehand with Steel browsers to create AI agents that can interact with websites using natural language commands. We'll build a simple automation that extracts data from Hacker News and demonstrates search functionality.

Prerequisites

Ensure you have the following:

Step 1: Set up your project

First, create a project directory and initialize your Node.js project:

# Create a project directory
mkdir steel-stagehand-starter
cd steel-stagehand-starter

# Initialize npm project
npm init -y

# Install required packages
npm install @browserbasehq/stagehand dotenv steel-sdk typescript zod

# Install dev dependencies
npm install --save-dev @types/node ts-node

Create a .env file with your API keys:

# .env
STEEL_API_KEY=your_steel_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

Step 2: Create your data schemas

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

// Load environment variables
dotenv.config();

const STEEL_API_KEY = process.env.STEEL_API_KEY;
const OPENAI_API_KEY = process.env.OPENAI_API_KEY;

// Define data schemas for structured extraction
const StorySchema = z.object({
  title: z.string(),
  rank: z.number()
});

const StoriesSchema = z.object({
  stories: z.array(StorySchema)
});

These schemas will help Stagehand extract structured data from web pages using Zod validation.

Step 3: Create a Steel browser session

async function main() {
  console.log("๐Ÿš€ Steel + Stagehand Automation");
  console.log("=".repeat(50));
  
  // Initialize Steel client
  const client = new Steel({
    steelAPIKey: STEEL_API_KEY,
  });
  
  // Create a new browser session
  const session = await client.sessions.create();
  
  console.log("โœ… Steel browser session created!");
  console.log(`View live session at: ${session.sessionViewerUrl}`);
}

When you run this, you'll see a URL where you can watch your browser session live.

Step 4: Configure and connect Stagehand

  // Configure Stagehand to use Steel session
  const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
      cdpUrl: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`,
    },
    enableCaching: false,
    modelClientOptions: {
      apiKey: OPENAI_API_KEY,
    },
  });
  
  // Initialize Stagehand
  console.log("๐Ÿค– Initializing Stagehand...");
  await stagehand.init();
  
  console.log("Connected to Steel browser via Stagehand");

This connects Stagehand to your Steel browser session via Chrome DevTools Protocol.

Step 5: Navigate and extract data

Add the automation logic to navigate to a website and extract information:

  try {
    // Navigate to Hacker News
    console.log("๐Ÿ“ฐ Navigating to Hacker News...");
    await stagehand.page.goto("https://news.ycombinator.com");
    
    // Extract top stories using AI
    console.log("๐Ÿ” Extracting top stories...");
    const stories = await stagehand.page.extract({
      instruction: "extract the titles and ranks of the first 5 stories on the page",
      schema: StoriesSchema,
    });
    
    // Display results
    console.log("\n๐Ÿ“‹ Top 5 Hacker News Stories:");
    stories.stories.forEach((story, index) => {
      console.log(`${story.rank}. ${story.title}`);
    });
    
    console.log("\nโœ… Automation completed successfully!");
    
  } catch (error) {
    console.error("โŒ Error during automation:", error);
  }

You'll see the extracted story titles and rankings printed to your console.

Step 6: Add proper cleanup

Always clean up your resources when finished:

  finally {
    // Close Stagehand
    if (stagehand) {
      await stagehand.close();
    }
    
    // Release Steel session
    if (session && client) {
      await client.sessions.release(session.id);
      console.log("๐Ÿงน Resources cleaned up");
    }
  }

// Run the automation
main().catch((error) => {
  console.error("Unhandled error:", error);
  process.exit(1);
});

Step 7: Run your automation

Execute your script:

npm start

You should see output like this:

๐Ÿš€ Steel + Stagehand Automation
==================================================
โœ… Steel browser session created!
View live session at: https://api.steel.dev/v1/sessions/[session-id]/player
๐Ÿค– Initializing Stagehand...
Connected to Steel browser via Stagehand
๐Ÿ“ฐ Navigating to Hacker News...
๐Ÿ” Extracting top stories...

๐Ÿ“‹ Top 5 Hacker News Stories:
1. Ask HN: What are you working on this week?
2. Show HN: I built a tool to analyze my GitHub contributions
3. The future of web development
4. Why I switched from React to Vue
5. Building scalable microservices with Go

โœ… Automation completed successfully!
๐Ÿงน Resources cleaned up

Complete Example

Here's the complete script that puts all steps together:

/*
 * AI-powered browser automation using Stagehand with Steel browsers.
 */

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

// Load environment variables
dotenv.config();

const STEEL_API_KEY = process.env.STEEL_API_KEY;
const OPENAI_API_KEY = process.env.OPENAI_API_KEY;

// Define data schemas for structured extraction
const StorySchema = z.object({
  title: z.string(),
  rank: z.number()
});

const StoriesSchema = z.object({
  stories: z.array(StorySchema)
});

async function main() {
  console.log("๐Ÿš€ Steel + Stagehand Automation");
  console.log("=".repeat(50));
  
  let session: any = null;
  let stagehand: Stagehand | null = null;
  
  try {
    // Initialize Steel client and create session
    const client = new Steel({
      steelAPIKey: STEEL_API_KEY,
    });
    
    session = await client.sessions.create();
    
    console.log("โœ… Steel browser session created!");
    console.log(`View live session at: ${session.sessionViewerUrl}`);
    
    // Configure and initialize Stagehand
    stagehand = new Stagehand({
      env: "LOCAL",
      localBrowserLaunchOptions: {
        cdpUrl: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`,
      },
      enableCaching: false,
      modelClientOptions: {
        apiKey: OPENAI_API_KEY,
      },
    });
    
    console.log("๐Ÿค– Initializing Stagehand...");
    await stagehand.init();
    console.log("Connected to Steel browser via Stagehand");
    
    // Navigate and extract data
    console.log("๐Ÿ“ฐ Navigating to Hacker News...");
    await stagehand.page.goto("https://news.ycombinator.com");
    
    console.log("๐Ÿ” Extracting top stories...");
    const stories = await stagehand.page.extract({
      instruction: "extract the titles and ranks of the first 5 stories on the page",
      schema: StoriesSchema,
    });
    
    console.log("\n๐Ÿ“‹ Top 5 Hacker News Stories:");
    stories.stories.forEach((story, index) => {
      console.log(`${story.rank}. ${story.title}`);
    });
    
    console.log("\nโœ… Automation completed successfully!");
    
  } catch (error) {
    console.error("โŒ Error during automation:", error);
    
  } finally {
    // Clean up resources
    if (stagehand) {
      await stagehand.close();
    }
    if (session) {
      const client = new Steel({ steelAPIKey: STEEL_API_KEY });
      await client.sessions.release(session.id);
    }
    console.log("๐Ÿงน Resources cleaned up");
  }
}

// Run the automation
main().catch((error) => {
  console.error("Unhandled error:", error);
  process.exit(1);
});

Advanced Usage Examples

Custom Data Extraction Schema

const ProductSchema = z.object({
  products: z.array(
    z.object({
      name: z.string(),
      price: z.string(),
      rating: z.number().optional(),
      inStock: z.boolean(),
    })
  ),
});

const productData = await stagehand.page.extract({
  instruction: "extract product information from this e-commerce page",
  schema: ProductSchema,
});

Complex Actions with Natural Language

// Fill out a form using natural language
await stagehand.page.act(
  "fill out the contact form with name 'John Doe', email 'john@example.com', and message 'Hello!'"
);

// Navigate through multi-step processes
await stagehand.page.act(
  "click on the 'Sign Up' button and then fill out the registration form"
);

// Handle dynamic content
await stagehand.page.act(
  "wait for the page to load completely, then click on the first product"
);

Next Steps

Now that you have a working Stagehand + Steel automation, try these enhancements:

  • Custom data extraction: Create your own Zod schemas for different websites

  • Complex interactions: Use stagehand.page.act() for clicking, typing, and navigation

  • Multiple pages: Navigate through multi-step workflows

  • Error handling: Add retry logic and better error management

For more advanced features, check out: