StagehandBrowser class

The StagehandBrowser class provides AI-powered browser automation using Stagehand. It uses natural language instructions for interactions instead of element refs.

Use StagehandBrowser when you want AI to interpret and execute browser actions from natural language. For deterministic automation using element refs, see AgentBrowser.

Usage example

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: true,
  model: 'openai/gpt-5.4',
  selfHeal: true,
})

export const browserAgent = new Agent({
  name: 'browser-agent',
  instructions: `You can browse the web using natural language.
Use stagehand_act to perform actions like "click the login button".
Use stagehand_extract to get data from pages.`,
  model: 'openai/gpt-5.4',
  browser,
})

Constructor parameters

headless?:

boolean

= true

Whether to run the browser in headless mode.

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

Browser viewport dimensions.

env?:

'LOCAL' | 'BROWSERBASE'

= 'LOCAL'

Environment to run the browser in. Use 'BROWSERBASE' for cloud execution.

apiKey?:

string

Browserbase API key. Required when env is 'BROWSERBASE'.

projectId?:

string

Browserbase project ID. Required when env is 'BROWSERBASE'.

model?:

string | ModelConfiguration

= 'openai/gpt-5.4'

Model configuration for AI operations. Can be a string like 'openai/gpt-5.4' or an object with modelName, apiKey, and baseURL.

selfHeal?:

boolean

= true

Enable self-healing selectors. When enabled, Stagehand uses AI to find elements even when initial selectors fail.

domSettleTimeout?:

number

= 5000

Timeout in milliseconds for DOM to settle after actions.

verbose?:

0 | 1 | 2

= 1

Logging verbosity level. 0 = silent, 1 = errors only, 2 = verbose.

systemPrompt?:

string

Custom system prompt for AI operations.

cdpUrl?:

string | (() => string | Promise<string>)

CDP WebSocket URL or HTTP endpoint for connecting to an existing browser. HTTP endpoints are resolved to WebSocket internally.

scope?:

'shared' | 'thread'

= 'thread' (or 'shared' when cdpUrl is provided)

Browser instance scope across threads.

timeout?:

number

= 10000

Default timeout in milliseconds for browser operations.

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

Callback invoked after the browser is ready.

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

Callback invoked before the browser closes.

screencast?:

ScreencastOptions

Configuration for streaming browser frames to Studio.

Tools

StagehandBrowser provides 6 AI-powered tools for browser automation:

Tool	Description
stagehand_act	Perform actions using natural language instructions
stagehand_extract	Extract structured data from pages
stagehand_observe	Discover actionable elements on a page
stagehand_navigate	Navigate to a URL
stagehand_tabs	Manage browser tabs
stagehand_close	Close the browser

Tool reference

stagehand_act

Perform an action using natural language instructions. The AI interprets your instruction and executes the appropriate browser action.

// Tool input
{
  "instruction": "click the login button",
  "variables": { "username": "john" },
  "useVision": true,
  "timeout": 30000
}

// With variable substitution
{
  "instruction": "type %email% into the email field",
  "variables": { "email": "user@example.com" }
}

Parameter	Type	Description
instruction	string	Natural language instruction (required)
variables	Record<string, string>	Variables for %variableName% substitution (optional)
useVision	boolean	Enable vision capabilities (optional)
timeout	number	Timeout in ms (optional)

Returns:

interface ActResult {
  success: boolean
  message?: string
  action?: string
  url?: string
}

stagehand_extract

Extract structured data from a page using natural language instructions.

// Basic extraction
{
  "instruction": "extract all product names and prices"
}

// With schema for structured output
{
  "instruction": "extract the product information",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" }
    }
  }
}

Returns:

interface ExtractResult<T = unknown> {
  success: boolean
  data?: T
  hint?: string
  error?: string
  url?: string
}

stagehand_observe

Discover actionable elements on a page. Returns a list of elements with their selectors and descriptions.

// Find specific elements
{
  "instruction": "find all buttons related to checkout"
}

// Find all interactive elements
{
  "onlyVisible": true
}

Parameter	Type	Description
instruction	string	Natural language instruction (optional, omit to find all)
onlyVisible	boolean	Only include visible elements (optional)
timeout	number	Timeout in ms (optional)

Returns:

interface ObserveResult {
  success: boolean
  actions: StagehandAction[]
  url?: string
}

interface StagehandAction {
  selector: string
  description: string
  method?: string
  arguments?: string[]
}

stagehand_navigate

Navigate to a URL.

// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded"
}

Parameter	Type	Description
url	string	URL to navigate to (required)
waitUntil	"load" | "domcontentloaded" | "networkidle"	When to consider navigation complete (optional)

stagehand_tabs

Manage browser tabs.

// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index (or current if omitted)
{ "action": "close", "index": 1 }

stagehand_close

Close the browser and clean up resources.

// Tool input (no parameters required)
{}

Using Browserbase

Run Stagehand in the cloud using Browserbase:

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.4',
})

Model configuration

Configure the AI model for Stagehand operations:

// String format: "provider/model"
const browser = new StagehandBrowser({
  model: 'openai/gpt-5.4',
})

// Object format for custom configuration
const browser = new StagehandBrowser({
  model: {
    modelName: 'gpt-5.4',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1',
  },
})

Supported providers:

• OpenAI: "openai/gpt-5.4", "openai/gpt-5.4-mini"
• Anthropic: "anthropic/claude-3-5-sonnet-20241022"

AgentBrowser vs StagehandBrowser

Aspect	AgentBrowser	StagehandBrowser
Approach	Deterministic refs (@e5)	Natural language
Precision	Exact element targeting	AI interpretation
Flexibility	Requires a snapshot first	Direct instructions
Use case	Reproducible automation	Adaptive automation
Speed	Faster (no AI inference)	Slower (AI inference)

Choose AgentBrowser for precise, reproducible automation. Choose StagehandBrowser for flexible, natural language interactions.

Related

• MastraBrowser: Base class reference
• AgentBrowser: Deterministic alternative
• Browser overview: Conceptual guide
• Stagehand guide: Usage guide