Skip to main content

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

The Agent provides autonomous, multi-step task execution using AI. It can navigate websites, interact with elements, extract data, and complete complex workflows.

​
Creating an Agent

Create an agent using stagehand.agent(): 
const agent = stagehand.agent(config?);
​
config
AgentConfig
​
returns
NonStreamingAgentInstance | StreamingAgentInstance
Agent instance with execute() method

​
execute()

Execute a task with the agent.

​
Non-streaming Mode

const result = await agent.execute(instructionOrOptions);
​
instructionOrOptions
string | AgentExecuteOptions
required
Task instruction or options object
​
returns
Promise<AgentResult>

​
Streaming Mode

When stream: true is set in AgentConfig: 
const streamResult = await agent.execute(options);

// Access the text stream
for await (const chunk of streamResult.textStream) {
  console.log(chunk);
}

// Get final result
const result = await streamResult.result;
​
options.callbacks
AgentStreamCallbacks
​
returns
Promise<AgentStreamResult>
Stream result with textStream and result properties

​
Examples

​
Basic Agent

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();

const page = await stagehand.context.newPage();
await page.goto("https://github.com");

// Create and execute agent
const agent = stagehand.agent();
const result = await agent.execute(
  "Find the most starred TypeScript repository"
);

console.log(result.message);
console.log(`Steps taken: ${result.actions.length}`);

await stagehand.close();

​
Agent with Structured Output

import { z } from "zod";

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Find flight information from NYC to LA",
  output: z.object({
    price: z.string().describe("Flight price"),
    airline: z.string().describe("Airline name"),
    departureTime: z.string(),
  }),
});

console.log(result.output);
// { price: "$299", airline: "Delta", departureTime: "8:00 AM" }

​
Agent with Variables

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Fill out the login form and submit",
  variables: {
    username: {
      value: "user@example.com",
      description: "Login email",
    },
    password: {
      value: "secret123",
      description: "Account password",
    },
  },
});

​
Streaming Agent

const agent = stagehand.agent({ stream: true });

const streamResult = await agent.execute({
  instruction: "Search for restaurants near me",
  callbacks: {
    onChunk: async (chunk) => {
      process.stdout.write(chunk.text);
    },
    onStepFinish: async (step) => {
      console.log("\nStep completed:", step.toolCalls);
    },
  },
});

const result = await streamResult.result;
console.log("\nFinal result:", result.message);

​
Agent with Abort Signal

const controller = new AbortController();

// Abort after 30 seconds
setTimeout(() => controller.abort(), 30000);

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Complete this long task",
  signal: controller.signal,
});

if (!result.completed) {
  console.log("Task was aborted");
}

​
CUA Mode Agent

// Computer Use Agent mode with screenshot-based interaction
const agent = stagehand.agent({
  mode: "cua",
  model: "anthropic/claude-opus-4-5",
});

const result = await agent.execute({
  instruction: "Navigate to settings and enable dark mode",
  callbacks: {
    onSafetyConfirmation: async (checks) => {
      console.log("Safety checks:", checks);
      // Return { acknowledged: true } to proceed
      return { acknowledged: true };
    },
  },
});