跳到主要内容

AgentBrowser

@mastra/agent-browser 包使用 Playwright 提供浏览器自动化，并优先通过无障碍信息定位元素。元素由页面无障碍树中的引用标识，因此在不同页面布局中也能可靠交互。

何时使用 AgentBrowser
何时使用 AgentBrowser的直接链接

当你需要以下能力时，请使用 AgentBrowser：

  • 通过无障碍引用可靠定位元素
  • 精细控制浏览器操作
  • 使用 Playwright 可靠的自动化能力
  • 支持键盘快捷键和复杂交互

快速开始
快速开始的直接链接

安装该包：

npm install @mastra/agent-browser

创建浏览器实例并将其分配给 Agent：

src/mastra/agents/browser-agent.ts
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: false,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
备注

对于本地启动（默认方式），AgentBrowser 需要安装通过 Playwright 提供的 Chromium 二进制文件。安装 @mastra/agent-browser 时通常会自动下载该文件。如果启动浏览器时出现 "browser executable is missing" 错误，请运行 npx playwright install chromium。如果通过 cdpUrl 选项连接远程浏览器，则由远程浏览器提供 Chromium。

截图
截图的直接链接

当 Agent 使用 browser_screenshot Tool 时，它会捕获当前页面的 PNG 图像，并以支持视觉的模型可直接解读的图像内容形式返回。

需要直观检查页面（例如评估图像、布局或颜色）时，请使用截图。对于文本或结构化数据，请改用 browser_snapshot。

要为不支持视觉的模型禁用截图 Tool，请使用 excludeTools：

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

元素引用
元素引用的直接链接

AgentBrowser 使用无障碍树引用来标识元素。当 Agent 调用 browser_snapshot 时，会收到页面的文本表示，其中包含 @e1、@e2 等引用。随后，Agent 会在其他 Tool 中使用这些引用与元素交互。

录制
录制的直接链接

AgentBrowser 可选择启用 alpha 版浏览器录制 Tool：

const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: './browser-recordings',
  },
})

这会向 Agent 的 Tool 集添加 browser_record 和 browser_record_caption。有关详细信息，请参阅浏览器录制（alpha）。有关所有配置选项和 Tool 详情，请参阅 AgentBrowser 参考。

On this page