Skip to main content
Stagehand is an AI-powered web browsing framework that enables intelligent browser automation through natural language. By integrating Cerebras models, you can leverage ultra-fast inference for web scraping, form filling, automated testing, and complex multi-step workflows that feel responsive and natural.

​
Prerequisites

Before you begin, ensure you have:
  • Cerebras API Key - Get a free API key here
  • Browserbase Account - Visit Browserbase and create an account to get your API key and Project ID
  • Node.js 20 or higher - Stagehand requires a modern Node.js environment
Stagehand works best with fast inference providers like Cerebras. The ultra-low latency of Cerebras models (llama-3.3-70b, qwen-3-32b, llama3.1-8b) enables near-instantaneous browser control decisions, making your automation agents significantly more responsive than traditional approaches.

​
Configure Stagehand with Cerebras

1

Create a new Stagehand project

The fastest way to get started is using the official Stagehand project creator, which sets up everything you need including dependencies:
npx create-browser-app@latest
Then follow the setup instructions:
cd my-stagehand-app
npm install
cp .env.example .env
The project template already includes zod and dotenv as dependencies—no need to install them separately.
2

Configure environment variables

Edit your .env file with your API credentials. You’ll need both Cerebras and Browserbase credentials to enable AI-powered browser automation:
BROWSERBASE_PROJECT_ID=your-browserbase-project-id-here
BROWSERBASE_API_KEY=your-browserbase-api-key-here
CEREBRAS_API_KEY=your-cerebras-api-key-here
You can find your Browserbase API Key and Project ID in the Browserbase Dashboard under the Overview section.
3

Extract structured data from Hacker News

Let’s start with a practical example—extracting the top stories from Hacker News. This demonstrates how Stagehand can intelligently parse and structure real web content:
import 'dotenv/config';
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

(async () => {
  try {
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      model: {
        modelName: "cerebras/qwen-3-32b",
        apiKey: process.env.CEREBRAS_API_KEY,
      }
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://news.ycombinator.com");

    const result = await stagehand.extract(
      "Extract the top 5 stories with their titles and points",
      z.object({
        stories: z.array(z.object({
          title: z.string(),
          points: z.number(),
        })),
      })
    );

    console.log("Top Hacker News stories:", result.stories);
    await stagehand.close();
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
})();
We’re using Cerebras’s qwen-3-32b model here, which excels at structured data extraction tasks due to its strong reasoning capabilities and fast inference speed.
4

Perform actions with natural language

Now let’s use Stagehand’s act() method to interact with a website. This example searches GitHub for “stagehand browserbase” and extracts results:
import 'dotenv/config';
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

(async () => {
  try {
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      model: {
        modelName: "cerebras/llama-3.3-70b",
        apiKey: process.env.CEREBRAS_API_KEY,
      }
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://github.com");

    // Use atomic instructions (best practice for reliable automation)
    await stagehand.act("Click the search button");
    await stagehand.act("Type 'stagehand browserbase' into the search input");
    await stagehand.act("Press Enter to submit the search");

    // Wait for results to load
    await new Promise(resolve => setTimeout(resolve, 2000));

    // Extract search results
    const result = await stagehand.extract(
      "Extract the repository names from the search results",
      z.object({
        repositories: z.array(z.string()),
      })
    );

    console.log("Found repositories:", result.repositories);
    await stagehand.close();
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
})();
This example demonstrates Stagehand’s act() method—you describe what you want to do in plain English, and Stagehand figures out how to interact with the page. With Cerebras’s llama-3.3-70b model, these decisions happen in milliseconds.
Best Practice: Use atomic, single-step instructions for reliable automation. Instead of “Click the search box and search for X”, break it into: “Click the search button”, “Type X into the input”, “Press Enter”.
5

Observe and analyze page content

Before taking action, you can use observe() to understand what’s available on a page. This is useful for dynamic decision-making in your automation workflows:
import 'dotenv/config';
import { Stagehand } from "@browserbasehq/stagehand";

(async () => {
  try {
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      model: {
        modelName: "cerebras/llama-3.3-70b",
        apiKey: process.env.CEREBRAS_API_KEY,
      }
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://www.producthunt.com");

    // Observe what actions are possible on the page
    const observations = await stagehand.observe(
      "What are the main interactive elements on this page?"
    );

    console.log("Available actions:", observations);

    // You can now decide which action to take based on observations
    if (observations.length > 0) {
      await stagehand.act(observations[0]);
    }

    await stagehand.close();
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
})();
The observe() method analyzes the page and returns suggestions without taking action. Use this when you want to preview options before committing, or when building adaptive automation that responds to different page states.
6

Build multi-step workflows

Combine all three methods—extract(), act(), and observe()—to create sophisticated automation workflows. This example navigates multiple sites and gathers comparative data:
import 'dotenv/config';
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

(async () => {
  try {
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      model: {
        modelName: "cerebras/llama-3.3-70b",
        apiKey: process.env.CEREBRAS_API_KEY,
      }
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    // Step 1: Search on GitHub
    console.log("Step 1: Searching GitHub...");
    await page.goto("https://github.com/search?q=browser+automation&type=repositories");

    const githubResult = await stagehand.extract(
      "Extract the name and description of the first repository",
      z.object({
        name: z.string(),
        description: z.string(),
      })
    );
    console.log("GitHub top repo:", githubResult);

    // Step 2: Search on npm
    console.log("Step 2: Searching npm...");
    await page.goto("https://www.npmjs.com/search?q=browser%20automation");

    const npmResult = await stagehand.extract(
      "Extract the name and description of the first npm package",
      z.object({
        name: z.string(),
        description: z.string(),
      })
    );
    console.log("npm top package:", npmResult);

    console.log("\nComparative research results:");
    console.log("- GitHub:", githubResult.name);
    console.log("- npm:", npmResult.name);

    await stagehand.close();
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
})();
Cerebras’s fast inference enables multi-step workflows to complete quickly, making it practical to build efficient browser automation that navigates multiple sites and makes intelligent decisions at each step.

​
Why Use Cerebras with Stagehand?

Cerebras’s ultra-fast inference provides several key advantages for browser automation:
  • Real-time responsiveness - Sub-second inference enables agents to react instantly to page changes and dynamic content, making automation feel natural
  • Complex reasoning - Models like llama-3.3-70b handle sophisticated multi-step workflows and make intelligent decisions about ambiguous page elements
  • Cost-effective scaling - Fast inference means lower costs for long-running automation tasks and dramatically reduced API usage compared to slower providers
  • Reliable execution - Low latency reduces timeouts and improves task completion rates, especially for time-sensitive operations and dynamic web applications
  • Better developer experience - Near-instantaneous responses during development make debugging and iteration significantly faster

​
Key Features

​
Four Powerful Primitives

Stagehand provides four complementary approaches to browser automation:
  • act() - Execute actions using natural language instructions (click, type, navigate, scroll)
  • extract() - Pull structured data from pages using AI, with Zod schema validation
  • observe() - Discover available actions on any page without executing them
  • agent() - Automate entire workflows autonomously for complex multi-step tasks

​
Natural Language Control

Describe what you want to do in plain English, and Stagehand’s AI will figure out how to interact with the page. No need for brittle CSS selectors or XPath queries.

​
Structured Data Extraction

Use Zod schemas to define exactly what data you want to extract, and Stagehand will find and structure it for you with built-in validation.

​
Works Everywhere

Stagehand v3 is compatible with all Chromium-based browsers. It also offers integrations with Playwright, Puppeteer, and Selenium for developers who want to combine AI-powered automation with traditional browser control.

​
Choosing the Right Cerebras Model

Different tasks benefit from different models. Here’s a guide:
ModelBest ForSpeedReasoning
llama-3.3-70bComplex multi-step workflows, ambiguous elementsFastExcellent
qwen-3-32bStructured data extraction, form analysisVery FastStrong
llama3.1-8bSimple navigation, repetitive tasksUltra FastGood

​
Next Steps

​
Troubleshooting

If Stagehand struggles to locate page elements:
  1. Use atomic instructions - Break complex actions into single steps. Instead of “Click the search box and search for ‘query’”, use three separate calls: “Click the search button”, “Type ‘query’ into the search input”, “Press Enter”
  2. Be more specific in your instructions - Instead of “click the button”, try “click the blue submit button in the bottom right corner”
  3. Wait for dynamic content - Some elements load via JavaScript. Add explicit waits: await new Promise(r => setTimeout(r, 2000));
  4. Verify the element exists - Use observe() first to see what Stagehand detects on the page
  5. Try a different model - llama-3.3-70b generally has better reasoning for complex pages than faster models
Example with explicit waiting:
await page.goto("https://example.com");
await new Promise(r => setTimeout(r, 2000)); // Wait for dynamic content
await stagehand.act("Click the load more button");
Stagehand can handle authenticated sessions through Browserbase’s session management. For sites that require authentication:Option 1: Let Stagehand handle the login flow
await page.goto("https://example.com/login");
await stagehand.act("Enter '[email protected]' in the email field");
await stagehand.act("Enter the password in the password field");
await stagehand.act("Click the login button");
await new Promise(r => setTimeout(r, 2000));
Option 2: Use Browserbase session persistenceCreate a session that persists authentication:
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  sessionId: "my-persistent-session", // Reuse this session ID
  model: {
    modelName: "cerebras/llama-3.3-70b",
    apiKey: process.env.CEREBRAS_API_KEY,
  }
});
The session will maintain cookies and authentication state across runs.
  • observe() analyzes the page and returns suggestions without taking action. Use this when you want to preview options before committing, or when building agents that need to dynamically decide their next step.
  • act() executes an action based on your natural language instruction. This performs the actual browser interaction (clicking, typing, scrolling, etc.).
Recommended pattern: Use observe + act for more reliable automation:
// Get candidate actions first
const actions = await stagehand.observe("Click the sign in button");

// Execute the first action
await stagehand.act(actions[0]);
Both methods leverage Cerebras’s fast inference to understand page context and determine the best course of action.
Traditional web scraping requires:
  • Writing brittle CSS selectors that break when the page layout changes
  • Manual handling of dynamic content and pagination
  • Complex parsing logic to structure data
Stagehand’s extract() method:
  • Uses AI to intelligently locate data regardless of page structure changes
  • Handles dynamic content automatically by understanding visual context
  • Structures data according to your Zod schema with built-in validation
  • Works across different websites with similar content types without code changes
Example comparison:Traditional scraping:
const titles = await page.$$eval('.story-title > a', els => 
  els.map(el => el.textContent)
);
Stagehand:
import { z } from "zod/v3";

const result = await stagehand.extract(
  "Get all story titles",
  z.object({ titles: z.array(z.string()) })
);
console.log(result.titles);
The Stagehand version will work even if the CSS classes change.
For rate limits:
  1. Add delays between operations using await new Promise(r => setTimeout(r, 1000))
  2. Use Browserbase’s session management to spread requests across multiple browser contexts
  3. Implement exponential backoff retry logic
  4. Consider using Cerebras’s faster models (llama3.1-8b) to reduce overall execution time
For CAPTCHAs and bot detection:Browserbase provides features specifically designed to avoid detection:
  • Residential proxies to appear as real users
  • Realistic browser fingerprints
  • Proper browser context management
Example with retry logic:
async function extractWithRetry(stagehand, instruction, schema, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await stagehand.extract(instruction, schema);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}
Choose your model based on the complexity of your automation task:llama-3.3-70b - Best for:
  • Complex, multi-step workflows with decision branching
  • Pages with ambiguous or hard-to-locate elements
  • Tasks requiring sophisticated reasoning about page content
  • When accuracy is more important than speed
qwen-3-32b - Best for:
  • Structured data extraction from well-formatted pages
  • Balanced performance between speed and reasoning
  • General-purpose automation tasks
  • Great middle-ground for most use cases
llama3.1-8b - Best for:
  • Simple, repetitive tasks with clear page structure
  • High-volume automation where speed is critical
  • Extracting data from consistent page layouts
  • When you need maximum throughput
Several strategies can help diagnose issues:
  1. Use observe() to see what Stagehand detects:
const observations = await stagehand.observe("What can I interact with?");
console.log("Stagehand sees:", observations);
  1. Enable verbose logging to see Stagehand’s decision-making:
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  verbose: 2, // Set to 1 or 2 for more detailed logs
  model: {
    modelName: "cerebras/llama-3.3-70b",
    apiKey: process.env.CEREBRAS_API_KEY,
  }
});
  1. Use Browserbase’s live view to watch the browser in real-time during development. The session URL is logged when you call stagehand.init().
  2. Start with simpler instructions and gradually add complexity to isolate where things break.

​
Additional Resources

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://inference-docs.cerebras.ai/llms.txt