Browser 浏览器

Browser 支持让 agents 能够浏览网站、与页面元素交互、填写表单并提取数据。Mastra 通过封装浏览器自动化库的 SDK 提供商，以及供 agents 通过命令行工具驱动浏览器的 CLI 提供商，提供浏览器能力。

Mastra 支持三个 SDK 提供商和一个 CLI 提供商：

• AgentBrowser：基于 Playwright 的提供商，采用无障碍优先的元素定位方式。最适合通用 Web 自动化和抓取。
• Stagehand：Browserbase 提供商，具备 AI 驱动的元素检测能力。最适合受益于自然语言选择器的复杂交互。
• FirecrawlBrowser：Firecrawl Browser Sandbox 提供商，在托管浏览器会话上运行 AgentBrowser 工具。最适合在托管的浏览器会话上运行自动化，而无需管理本地浏览器基础设施。
• BrowserViewer：CLI 提供商，启动 Chrome 并将 CDP URL 注入 agent-browser、browser-use 和 browse 等 CLI 工具。最适合通过 shell 命令驱动浏览器的工作区 agents。

何时使用 browser

当 agent 需要执行以下操作时使用 browser：

• 浏览网站并与页面元素交互
• 填写表单并提交数据
• 从网页中提取结构化数据
• 自动化多步骤 Web 工作流
• 执行需要真实浏览器的操作（JavaScript 渲染、身份验证流程）

工作原理

当你为 agent 分配浏览器时，Mastra 会将提供商的工具加入 agent 的工具集。Agent 使用这些工具控制浏览器。它可以打开 URL 并选择元素，还可以输入文本并读取页面内容。

每个提供商都提供一组针对其方法优化的不同工具。

快速开始

安装你选择的提供商，本示例使用 AgentBrowser 提供商。

npm

npm install @mastra/agent-browser

pnpm

pnpm add @mastra/agent-browser

Yarn

yarn add @mastra/agent-browser

Bun

bun add @mastra/agent-browser

创建一个新的浏览器实例：

src/mastra/browsers.ts

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

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

将浏览器分配给 agent：

src/mastra/agents/web-agent.ts

import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})

Agent 会自动接收来自该提供商的所有浏览器工具。

云提供商

所有 SDK 提供商都支持连接云浏览器服务，而不是启动本地浏览器。

Firecrawl Browser Sandbox（FirecrawlBrowser 原生）

FirecrawlBrowser 通过 Firecrawl API 提供托管会话：

import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})

Browserbase（Stagehand 原生）

Stagehand 具有原生 Browserbase 集成：

import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})

CDP URL（任何提供商）

连接到任何暴露 Chrome DevTools Protocol (CDP) 端点的浏览器：

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

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})

这适用于任何 CDP 兼容的浏览器服务。

屏幕录制

浏览器提供商会将浏览器的实时视频流传输到 Mastra Studio UI。这让你可以实时观看 agent 与页面交互。

屏幕录制需要 WebSocket 支持。请在项目中安装以下包：

npm

npm install ws @hono/node-ws

pnpm

pnpm add ws @hono/node-ws

Yarn

yarn add ws @hono/node-ws

Bun

bun add ws @hono/node-ws

备注

这些包默认不包含，因为它们与 Cloudflare Workers 等无服务器环境不兼容。如果未安装，屏幕录制会被禁用，但所有其他浏览器功能仍可正常工作。

屏幕录制默认启用，并可进行配置：

const browser = new AgentBrowser({
  screencast: {
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

录制浏览器会话

AgentBrowser 和 StagehandBrowser 可以选择启用录制，用于审查、分享或调试浏览器运行。配置 outputDir 以添加录制工具：

src/mastra/browsers.ts

import { join } from 'node:path'
import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
  },
})

StagehandBrowser 接受相同的 recording 选项。Agent 使用 browser_record 开始、检查和停止录制，并使用 browser_record_caption 标注主要操作。停止时会保存视频，并允许 agent 返回其路径。自定义 outputPath 可以是绝对路径，也可以是相对于当前工作目录的路径，但必须解析为 recording.outputDir 内的路径。

录制使用 Motion-JPEG AVI，不需要 ffmpeg。默认最长时长为 30 秒，硬性上限为 120 秒。默认最大帧大小为 1024 × 720，说明文字限制为 80 个字符，每个进程只能有一个活动录制。

后续步骤

• AgentBrowser
• Stagehand
• Firecrawl
• BrowserViewer
• MastraBrowser 参考
• 📹 Mastra browser 能力工作坊