Documentation Index
Fetch the complete documentation index at: https://mintlify.com/browserbase/stagehand/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Stagehand makes web navigation simple by allowing you to describe actions in natural language. This example shows how to navigate through a multi-step apartment search workflow.
Multi-Step Navigation Example
This example demonstrates navigating through filters and options on an apartment search site:
import { Action, Stagehand } from "@stagehand/core";
async function example() {
const stagehand = new Stagehand({
env: "BROWSERBASE",
verbose: 1,
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://www.apartments.com/san-francisco-ca/");
let observation: Action;
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe("find the 'all filters' button");
await stagehand.act(observation);
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe(
"find the '1+' button in the 'beds' section",
);
await stagehand.act(observation);
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe(
"find the 'apartments' button in the 'home type' section",
);
await stagehand.act(observation);
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe(
"find the pet policy dropdown to click on.",
);
await stagehand.act(observation);
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe(
"find the 'Dog Friendly' option to click on",
);
await stagehand.act(observation);
await new Promise((resolve) => setTimeout(resolve, 3000));
[observation] = await stagehand.observe("find the 'see results' section");
await stagehand.act(observation);
const currentUrl = page.url();
await stagehand.close();
if (
currentUrl.includes(
"https://www.apartments.com/apartments/san-francisco-ca/min-1-bedrooms-pet-friendly-dog/",
)
) {
console.log("✅ Success! we made it to the correct page");
} else {
console.log("❌ Whoops, looks like we didn't make it to the correct page.");
}
}
(async () => {
await example();
})();
Using Custom System Prompts
You can customize Stagehand’s behavior with system prompts:
import { Stagehand } from "@stagehand/core";
async function example() {
const stagehand = new Stagehand({
env: "BROWSERBASE",
verbose: 1,
systemPrompt:
"if the users says `secret12345`, click on the 'getting started' tab. additionally, if the user says to type something, translate their input into french and type it.",
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://docs.browserbase.com/");
await stagehand.act("secret12345");
await stagehand.act("search for 'how to use browserbase'");
await stagehand.close();
}
(async () => {
await example();
})();
Direct Page Navigation
For simpler navigation tasks, you can use direct act() calls:
import { Stagehand } from "@stagehand/core";
async function example() {
const stagehand = new Stagehand({
env: "BROWSERBASE",
verbose: 1,
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://google.com");
await stagehand.act("type in 'Browserbase'");
await stagehand.act("press enter");
await stagehand.close();
}
(async () => {
await example();
})();
Working with Multiple Pages
Stagehand supports working with multiple browser pages simultaneously:
import { Stagehand } from "@stagehand/core";
async function example(stagehand: Stagehand) {
const page = stagehand.context.pages()[0];
await page.goto("https://example.com");
// Create a new page
const page2 = await stagehand.context.newPage();
await page2.goto("https://another-site.com");
// Perform actions on specific pages
await stagehand.act("fill the your name field with the text 'John Doe'", {
page: page2,
});
const action2 = await stagehand.observe(
"select blue as the favorite color on the dropdown",
{ page: page2 },
);
for (const action of action2) {
await stagehand.act(action, { page: page2, timeout: 30_000 });
}
}
(async () => {
const stagehand = new Stagehand({
env: "BROWSERBASE",
verbose: 2,
});
try {
await stagehand.init();
await example(stagehand);
} finally {
await stagehand.close();
}
})();
Key Concepts
observe() and act()
The observe() method lets you preview actions before executing them with act(). This is useful for:
- Caching element locations
- Debugging navigation flows
- Building more robust automation
Waiting for UI Updates
Always add appropriate delays between actions to allow UI elements to load and respond:
await new Promise((resolve) => setTimeout(resolve, 3000));
System Prompts
Customize Stagehand’s behavior with system prompts to:
- Add special command shortcuts
- Transform user inputs
- Implement custom navigation logic
Page Context
When working with multiple pages, specify the target page using the page option in act() and observe().
Best Practices
- Wait for navigation - Always ensure pages have loaded before interacting
- Use observe() for complex flows - Preview and cache actions for reliability
- Verify results - Check URLs or page content to confirm successful navigation
- Handle errors gracefully - Navigation can fail due to network issues or UI changes
Next Steps