AgentBrowser 类

AgentBrowser 类使用 agent-browser 库提供确定性浏览器自动化。它使用无障碍树快照和元素 ref（例如 @e5）实现精确、可复现的交互。

需要可靠的确定性浏览器自动化时，请使用 AgentBrowser。如需使用自然语言的 AI 驱动交互，请参阅 StagehandBrowser。

用法示例

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. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})

构造函数参数

headless?:

boolean

= true

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

viewport?:

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

= { width: 1280, height: 720 }

浏览器视口尺寸；也可设为 'window'，以匹配真实浏览器窗口，而不使用固定尺寸。

timeout?:

number

= 30000

浏览器操作的默认超时时间（毫秒）。

cdpUrl?:

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

用于连接现有浏览器的 CDP WebSocket URL。适用于云浏览器 Provider。

scope?:

'shared' | 'thread'

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

浏览器实例作用域。'shared' 让所有线程共享一个浏览器。'thread' 为每个线程提供独立浏览器。

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?:

BrowserToolName[]

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

工具

AgentBrowser 提供 16 个用于浏览器自动化的确定性工具。所有与元素交互的工具都使用无障碍树快照中的 ref。

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

核心工具

工具	描述
browser_goto	导航到 URL
browser_snapshot	获取包含元素 ref 的无障碍树快照
browser_click	按 ref 点击元素
browser_type	向元素中输入文本
browser_press	按下键盘按键
browser_select	从下拉菜单中选择选项
browser_scroll	滚动页面或元素
browser_screenshot	截取 PNG 屏幕截图（默认为视口；设置 fullPage: true 可截取完整页面）
browser_close	关闭浏览器

扩展工具

工具	描述
browser_hover	将鼠标悬停在元素上
browser_back	在浏览器历史记录中后退
browser_dialog	处理浏览器对话框（alert、confirm、prompt）
browser_wait	等待元素状态变化
browser_tabs	管理浏览器标签页（列出、新建、切换、关闭）
browser_drag	拖放元素
browser_evaluate	在页面中执行 JavaScript（逃生舱）

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

const browser = new AgentBrowser({
  excludeTools: ['browser_screenshot'],
})

工具参考

browser_goto

导航到 URL。

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

参数	类型	描述
url	string	要打开的 URL
waitUntil	"load" | "domcontentloaded" | "networkidle"	何时将导航视为完成（可选）
timeout	number	导航超时时间（毫秒，可选）

browser_snapshot

获取页面的无障碍树快照。返回 @e5 之类的元素 ref，供其他工具使用。

// Tool input
{
  "interactiveOnly": true,
  "maxDepth": 10
}

参数	类型	描述
interactiveOnly	boolean	是否仅包含交互式元素（可选）
maxDepth	number	最大树深度（可选）

示例输出：

[document] Example Page
  [banner]
    [link @e1] Home
    [link @e2] About
  [main]
    [heading @e3] Welcome
    [textbox @e4] Search...
    [button @e5] Submit

browser_click

使用快照中的 ref 点击元素。

{
  "ref": "@e5",
  "button": "left",
  "clickCount": 1,
  "modifiers": ["Control", "Shift"]
}

参数	类型	描述
ref	string	快照中的元素 ref（必需）
button	"left" | "right" | "middle"	鼠标按键（可选）
clickCount	number	激活次数；双击时为 2（可选）
modifiers	string[]	修饰键（可选）

browser_type

向输入元素中输入文本。

// Tool input
{
  "ref": "@e4",
  "text": "search query",
  "clear": true,
  "delay": 50
}

参数	类型	描述
ref	string	快照中的元素 ref（必需）
text	string	要输入的文本（必需）
clear	boolean	是否先清除现有内容（可选）
delay	number	按键之间的延迟（毫秒，可选）

browser_press

按下键盘按键。

// Tool input
{
  "key": "Enter",
  "modifiers": ["Control"]
}

// Key combinations
{ "key": "Control+a" }
{ "key": "Control+c" }

参数	类型	描述
key	string	按键名称（例如 "Enter"、"Tab"、"Escape"、"Control+a"）（必需）
modifiers	string[]	修饰键（可选）

browser_select

从下拉菜单中选择选项。请提供 value、label 或 index 之一。

// Tool input - by value
{
  "ref": "@e10",
  "value": "option-value"
}

// Tool input - by label
{
  "ref": "@e10",
  "label": "Option Text"
}

// Tool input - by index
{
  "ref": "@e10",
  "index": 0
}

browser_scroll

滚动页面或特定元素。

// Tool input
{
  "direction": "down",
  "amount": 300,
  "ref": "@e15"
}

参数	类型	描述
direction	"up" | "down" | "left" | "right"	滚动方向（必需）
amount	number	滚动像素数，默认为 300（可选）
ref	string	要滚动的元素；省略时滚动页面（可选）

browser_hover

将鼠标悬停在元素上以触发悬停效果。

// Tool input
{
  "ref": "@e7"
}

browser_back

在浏览器历史记录中后退。

// Tool input (no parameters required)
{}

browser_dialog

处理浏览器对话框（alert、confirm、prompt）。点击触发对话框的元素并进行处理。

// Tool input
{
  "triggerRef": "@e5",
  "action": "accept",
  "text": "response"
}

参数	类型	描述
triggerRef	string	触发对话框的元素（必需）
action	"accept" | "dismiss"	处理对话框的方式（必需）
text	string	prompt 对话框的文本（可选）

browser_wait

等待元素达到特定状态。

// Tool input
{
  "ref": "@e20",
  "state": "visible",
  "timeout": 30000
}

参数	类型	描述
ref	string	要等待的元素 ref（可选）
state	"visible" | "hidden" | "attached" | "detached"	要等待的状态（可选）
timeout	number	最大等待时间（毫秒，可选）

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
{ "action": "close", "index": 1 }

browser_drag

将元素拖到目标位置。

// Tool input
{
  "sourceRef": "@e10",
  "targetRef": "@e20"
}

参数	类型	描述
sourceRef	string	要拖动的元素（必需）
targetRef	string	放置目标元素（必需）

browser_evaluate

在页面上下文中执行 JavaScript。当其他工具无法覆盖你的使用场景时，可将其作为逃生舱。

// Tool input
{
  "script": "document.title",
  "returnValue": true
}

参数	类型	描述
script	string	要执行的 JavaScript（必需）
returnValue	boolean	是否返回结果（可选）

browser_screenshot

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

// Viewport only (default)
{}

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

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

browser_close

关闭浏览器并清理资源。

// Tool input (no parameters required)
{}

ref 的工作原理

browser_snapshot 工具返回一个无障碍树，其中包含 @e1、@e2 等元素 ref。这些 ref 是供其他工具使用的稳定标识符：

1. 调用 browser_snapshot 查看页面结构
2. 找到要交互的元素
3. 将其 ref 与 browser_type 或 browser_scroll 等交互工具配合使用。

// 1. Get snapshot
// Returns: [textbox @e4] Search... [link @e5] Home

// 2. Type in the search box
{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }

// 3. Navigate to home
{ "tool": "browser_goto", "input": { "url": "https://example.com" } }

相关内容

• MastraBrowser：基类参考
• StagehandBrowser：AI 驱动的替代方案
• Browser 概述：概念指南
• agent-browser 指南：用法指南