MastraBrowser 类

MastraBrowser 类是浏览器自动化 Provider 的抽象基类。它的通用接口涵盖浏览器启动、线程隔离、screencast 流式传输和输入事件。

你不会直接实例化 MastraBrowser。请改用 Provider 实现：

• AgentBrowser：使用 ref 的确定性浏览器自动化
• StagehandBrowser：使用自然语言的 AI 驱动浏览器自动化
• BrowserViewer：注入 CDP URL 的基于 CLI 的浏览器自动化

用法示例

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: 'You can browse the web to find information.',
  model: 'openai/gpt-5.6-sol',
  browser,
})

构造函数参数

headless?:

boolean

= true

是否以无头模式（无可见 UI）运行浏览器。

viewport?:

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

= { width: 1280, height: 720 }

浏览器视口尺寸。控制浏览器窗口的大小。设为 'window' 可匹配真实浏览器窗口，而不使用固定尺寸；agent-browser Provider 和通过 CDP 连接时的 Stagehand 支持此设置。

timeout?:

number

默认超时时间（毫秒）。每个 Provider 都定义自己的语义和默认值。详情请参阅相应 Provider 参考。

cdpUrl?:

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

CDP WebSocket URL、HTTP 端点或同步/异步 Provider 函数。提供后，会连接现有浏览器，而不是启动新浏览器。HTTP 端点会在内部解析为 WebSocket。不能与 scope: 'thread' 一起使用（会自动使用 shared 作用域）。

scope?:

'shared' | 'thread'

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

跨线程的浏览器实例作用域。'shared' 表示所有线程共享一个浏览器实例。'thread' 表示每个线程都有自己的浏览器实例（完全隔离）。

onLaunch?:

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

浏览器达到 'ready' 状态后调用的回调。

onClose?:

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

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

screencast?:

ScreencastOptions

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

ScreencastOptions

format?:

'jpeg' | 'png'

screencast 帧的图像格式。

quality?:

number

图像质量（1-100）。仅适用于 JPEG 格式。

maxWidth?:

number

screencast 帧的最大宽度。

maxHeight?:

number

screencast 帧的最大高度。

everyNthFrame?:

number

每 N 帧捕获一次，以减少带宽。

属性

以下属性（id、name、provider）是抽象属性，必须由具体的 Provider 实现定义：

id:

string

此浏览器实例的唯一标识符。抽象属性，由 Provider 定义。

name:

string

浏览器 Provider 的人类可读名称（例如 'AgentBrowser'、'StagehandBrowser'）。抽象属性，由 Provider 定义。

provider:

string

Provider 标识符（例如 'vercel-labs/agent-browser'、'browserbase/stagehand'）。抽象属性，由 Provider 定义。

headless:

boolean

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

status:

BrowserStatus

当前浏览器状态：'pending'、'launching'、'ready'、'error'、'closing' 或 'closed'。

方法

生命周期

ensureReady()

确保浏览器已启动并可供使用。在工具执行前自动调用。由基类实现。

await browser.ensureReady()

close()

关闭浏览器并清理所有资源。由基类实现，并提供避免竞态条件的处理。

await browser.close()

isBrowserRunning()

检查浏览器当前是否正在运行。

const isRunning = browser.isBrowserRunning()

返回： boolean

线程管理

setCurrentThread(threadId)

设置浏览器操作的当前线程 ID。由 Agent runtime 在内部使用。

browser.setCurrentThread('thread-123')

getCurrentThread()

获取当前线程 ID。

const threadId = browser.getCurrentThread()

返回： string

hasThreadSession(threadId)

检查线程是否有活跃的浏览器 session。

const hasSession = browser.hasThreadSession('thread-123')

返回： boolean

closeThreadSession(threadId)

关闭特定线程的浏览器 session。使用 'thread' 作用域时，它会关闭该线程的浏览器实例。使用 'shared' 作用域时，它会清除线程状态。

await browser.closeThreadSession('thread-123')

工具

getTools()

返回供 Agent 使用的浏览器工具。每个 Provider 都会根据其模型返回不同的工具。

const tools = browser.getTools()

返回： Record<string, Tool>

屏幕串流

startScreencast(options?, threadId?)

开始流式传输浏览器帧。返回一个发出帧事件的 ScreencastStream。

const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')

stream.on('frame', frame => {
  console.log('Frame received:', frame.data.length, 'bytes')
})

stream.on('stop', reason => {
  console.log('Screencast stopped:', reason)
})

返回： Promise<ScreencastStream>

输入注入

injectMouseEvent(params, threadId?)

将鼠标事件注入浏览器。Studio 使用此方法进行实时交互。

await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1,
})

injectKeyboardEvent(params, threadId?)

将键盘事件注入浏览器。Studio 使用此方法进行实时交互。

await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
})

状态

getState(threadId?)

获取当前浏览器状态，包括 URL 和标签页。

const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)

返回： Promise<BrowserState>

interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}

getCurrentUrl(threadId?)

获取当前页面 URL。

const url = await browser.getCurrentUrl()

返回： Promise<string | null>

浏览器作用域

scope 选项控制如何跨对话线程共享浏览器实例：

作用域	描述	使用场景
'shared'	所有线程共享一个浏览器实例	适用于无冲突任务，成本更低
'thread'	每个线程都有自己的浏览器实例	为并发用户提供完全隔离

// Shared browser for all threads
const sharedBrowser = new AgentBrowser({
  scope: 'shared',
})

// Isolated browser per thread
const isolatedBrowser = new AgentBrowser({
  scope: 'thread',
})

使用 cdpUrl 连接外部浏览器时，由于无法生成新的浏览器实例，作用域会自动回退为 'shared'。

云浏览器 Provider

使用 cdpUrl 选项连接云浏览器服务：

// Static CDP URL
const browser = new AgentBrowser({
  cdpUrl: 'wss://browser.example.com/ws',
})

// Dynamic CDP URL (e.g., session-based)
const browser = new AgentBrowser({
  cdpUrl: async () => {
    const session = await createBrowserSession()
    return session.wsUrl
  },
})

相关内容

• AgentBrowser：确定性浏览器自动化
• StagehandBrowser：AI 驱动的浏览器自动化
• Browser 概述：浏览器自动化概念指南