StagehandBrowser 类

StagehandBrowser 类使用 Stagehand 提供 AI 驱动的浏览器自动化。它使用自然语言指令进行交互，而不是元素 ref。

希望 AI 根据自然语言解释并执行浏览器操作时，请使用 StagehandBrowser。对于使用元素 ref 的确定性自动化，请参阅 AgentBrowser。

用法示例

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.6-sol',
  selfHeal: true,
})

export const browserAgent = new Agent({
  id: 'browser-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.6-sol',
  browser,
})

构造函数参数

headless?:

boolean

= true

是否以无头模式运行浏览器。

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

浏览器视口尺寸。'window' 会匹配真实浏览器窗口，并且仅在通过 CDP 连接时适用；本地启动的浏览器会回退到默认尺寸。

env?:

'LOCAL' | 'BROWSERBASE'

= 'LOCAL'

运行浏览器的环境。使用 'BROWSERBASE' 在云端执行。

apiKey?:

string

Browserbase API key。env 为 'BROWSERBASE' 时必需。

projectId?:

string

Browserbase project ID。env 为 'BROWSERBASE' 时必需。

model?:

string | ModelConfiguration

= 'openai/gpt-5.5'

AI 操作的模型配置。可以是类似 'openai/gpt-5.5' 的字符串，也可以是包含 modelName、apiKey 和 baseURL 的对象。

selfHeal?:

boolean

= true

启用自愈 selector。启用后，即使初始 selector 失败，Stagehand 也会使用 AI 查找元素。

domSettleTimeout?:

number

= 5000

操作后等待 DOM 稳定的超时时间（毫秒）。

verbose?:

0 | 1 | 2

= 1

日志详细程度。0 = 静默，1 = 仅错误，2 = 详细。

systemPrompt?:

string

用于 AI 操作的自定义 system prompt。

cdpUrl?:

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

用于连接现有浏览器的 CDP WebSocket URL 或 HTTP 端点。HTTP 端点会在内部解析为 WebSocket。

scope?:

'shared' | 'thread'

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

跨线程的浏览器实例作用域。

timeout?:

number

= 30000

Stagehand 操作的默认超时时间（毫秒）。

onLaunch?:

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

浏览器准备就绪后调用的回调。

onClose?:

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

浏览器关闭前调用的回调。

screencast?:

ScreencastOptions

将浏览器帧流式传输到 Studio 的配置。

recording?:

BrowserRecordingOptions

用于添加浏览器录制工具的 Alpha 选项。提供 outputDir 可将 browser_record 和 browser_record_caption 添加到工具集。还可以设置 maxDurationMs、maxWidth 和 maxHeight，作为每次录制的默认值。

excludeTools?:

StagehandToolName[]

要从浏览器工具集中排除的工具名称。对于不支持某些能力（例如视觉）的模型，可用此选项禁用特定工具。

工具

StagehandBrowser 提供 7 个用于浏览器自动化的 AI 驱动工具。

配置 recording 后，StagehandBrowser 还会添加 Alpha 版 browser_record 和 browser_record_caption 工具。请参阅浏览器录制（Alpha）。

核心工具：

工具	描述
stagehand_act	使用自然语言指令执行操作
stagehand_extract	从页面中提取结构化数据
stagehand_observe	发现页面中的有用元素
stagehand_navigate	导航到 URL
stagehand_tabs	管理浏览器标签页
stagehand_screenshot	截取 PNG 屏幕截图（默认为视口；设置 fullPage: true 可截取完整页面）
stagehand_close	关闭浏览器

要排除特定工具，请在构造函数中传入 excludeTools：

const browser = new StagehandBrowser({
  excludeTools: ['stagehand_screenshot'],
})

工具参考

stagehand_act

使用自然语言指令执行操作。AI 会解释你的指令并执行相应的浏览器操作。

// 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" }
}

参数	类型	描述
instruction	string	自然语言指令（必需）
variables	Record<string, string>	用于 %variableName% 替换的变量（可选）
useVision	boolean	启用视觉能力（可选）
timeout	number	超时时间（毫秒，可选）

返回：

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

stagehand_extract

使用自然语言指令从页面中提取结构化数据。

// 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" }
    }
  }
}

返回：

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

stagehand_observe

发现页面中的有用元素。返回元素列表及其 selector 和描述。

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

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

参数	类型	描述
instruction	string	自然语言指令（可选，省略时查找全部）
onlyVisible	boolean	是否仅包含可见元素（可选）
timeout	number	超时时间（毫秒，可选）

返回：

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

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

stagehand_navigate

导航到 URL。

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

参数	类型	描述
url	string	要打开的 URL（必需）
waitUntil	"load" | "domcontentloaded" | "networkidle"	何时将导航视为完成（可选）

stagehand_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_screenshot

将当前页面截取为 PNG 屏幕截图（默认为视口。设置 fullPage: true 可截取完整页面）。返回支持视觉能力的模型可直接解读的图像内容。只需要文本或结构化数据时，请使用 stagehand_observe 或 stagehand_extract。

// Viewport only (default)
{}

// Full scrollable page
{ "fullPage": true }

参数	类型	描述
fullPage	boolean	是否截取完整的可滚动页面，而不是仅截取视口（可选，默认值：false）

stagehand_close

关闭浏览器并清理资源。

// Tool input (no parameters required)
{}

使用 Browserbase

使用 Browserbase 在云端运行 Stagehand：

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

模型配置

为 Stagehand 操作配置 AI 模型：

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

// 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',
  },
})

AgentBrowser 与 StagehandBrowser 对比

方面	AgentBrowser	StagehandBrowser
方式	确定性 ref（@e5）	自然语言
精确度	精确定位元素	AI 解释
灵活性	需要先获取快照	直接提供指令
使用场景	可复现的自动化	自适应自动化
速度	更快（无 AI 推理）	更慢（需要 AI 推理）

需要精确、可复现的自动化时，请选择 AgentBrowser。需要灵活的自然语言交互时，请选择 StagehandBrowser。

相关内容

• MastraBrowser：基类参考
• AgentBrowser：确定性替代方案
• Browser 概述：概念指南
• Stagehand 指南：用法指南