Quickstart (TS/Node)
Build AI agents that navigate the web using natural language instructions

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:
-
Node.js 20 or higher
-
A Steel API key (sign up here)
-
An OpenAI API key (get one here)
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:
-
Stagehand documentation for natural language automation
-
Steel API documentation for session management options
-
Steel GitHub examples for more integration patterns