第15章 Browser 浏览器能力

# 第15章 Browser 浏览器支持让 Agent 能够浏览网站、操作页面元素、填写表单并提取数据。Mastra 通过封装浏览器自动化库的 SDK provider，以及一个基于命令行工具驱动浏览器的 CLI provider，来提供浏览器能力。 Mastra 支持三个 SDK provider 和一个 CLI provider： AgentBrowser：基于 Playwright 的 provider，采用无障碍优先的元素定位方式，最适合通用网页自动化和数据抓取。 Stagehand：Browserbase 出品的 provider，利用 AI 进行元素识别，最适合需要自然语言选择器的复杂交互场景。 FirecrawlBrowser：Firecrawl Browser Sandbox 的 provider，可在托管的浏览器会话上运行 AgentBrowser 工具，适合无需自建本地浏览器基础设施就能运行自动化的场景。 BrowserViewer：CLI provider，负责启动 Chrome 并将 CDP URL 注入到 agent-browser、browser-use、browse 等命令行工具中，适合通过 shell 命令驱动浏览器的工作区 Agent。 何时使用 Browser 当 Agent 需要以下能力时，可以使用 browser： 浏览网页并操作页面元素 填写表单并提交数据 从网页中提取结构化数据 自动化多步骤网页工作流 执行需要真实浏览器的操作（JavaScript 渲染、登录认证流程等） 工作原理 为 Agent 配置浏览器后，Mastra 会把 provider 的工具加入 Agent 的工具集，Agent 就能用这些工具控制浏览器——打开 URL、选中元素、输入文本、读取页面内容等。 每个 provider 都提供一套工具，针对各自的方式做了优化。 快速上手 先安装你选择的 provider，本例使用 AgentBrowser。 npmpnpmYarnBunnpm install @mastra/agent-browser
pnpm add @mastra/agent-browser
yarn add @mastra/agent-browser
bun add @mastra/agent-browser
创建一个新的浏览器实例： src/mastra/browsers.tsimport { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
headless: false,
})
将浏览器配置给 Agent： src/mastra/agents/web-agent.tsimport { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
id: 'web-agent',
name: 'Web Agent',
description: '一个能浏览网站并完成任务的网页自动化助手。',
model: 'openai/gpt-5.6-sol',
browser,
instructions:
'你是一个网页自动化助手。使用浏览器工具浏览网站并完成任务。',
})
Agent 会自动获得 provider 提供的全部浏览器工具。 云端 provider 所有 SDK provider 都支持连接云端浏览器服务，而不必启动本地浏览器。 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（适用于任意 provider） 可以连接任何暴露 Chrome DevTools Protocol（CDP）端点的浏览器： import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
cdpUrl: process.env.BROWSER_CDP_URL,
headless: true,
})
任何兼容 CDP 的浏览器服务都可以这样连接。 实时屏幕串流 浏览器 provider 会向 Mastra Studio UI 串流浏览器的实时画面，让你实时观看 Agent 与页面的交互过程。 屏幕串流需要 WebSocket 支持，请在项目中安装以下包： npmpnpmYarnBunnpm install ws @hono/node-ws
pnpm add ws @hono/node-ws
yarn add ws @hono/node-ws
bun add ws @hono/node-ws
注意：这些包默认不会安装，因为它们与 Cloudflare Workers 等 serverless 环境不兼容。如果未安装，屏幕串流会被禁用，但其他浏览器功能不受影响。 屏幕串流默认开启，也可以进行配置： const browser = new AgentBrowser({
screencast: {
format: 'jpeg',
quality: 80,
maxWidth: 1280,
maxHeight: 720,
},
})
录制浏览器会话 AgentBrowser 和 StagehandBrowser 支持开启录制功能，方便回看、分享或调试浏览器运行过程。配置 outputDir 即可启用录制工具： src/mastra/browsers.tsimport { 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 浏览器能力工作坊