浏览器录制（beta）

添加于： @mastra/core@1.43.0

浏览器录制添加了两个可选择启用的 Tool，让 Agent 能将浏览器会话保存为 Motion-JPEG AVI 视频。Agent 还可以在工作过程中添加简短字幕。

beta

此功能处于 beta 阶段。在 API 稳定之前，可能会发生不伴随主版本号变更的破坏性更改。

何时使用浏览器录制

当你需要以下操作时，请使用浏览器录制：

• 回顾 Agent 在浏览器中执行的操作
• 与团队成员分享简短的浏览器自动化运行过程
• 调试遗漏的操作、缓慢的页面加载或意外的导航
• 添加简短字幕，说明每个主要步骤

录制 Tool 默认禁用。仅为需要写入视频文件的 Agent 启用它们。

启用录制

向 AgentBrowser 或 StagehandBrowser 传入 recording 对象。唯一的必填字段是 outputDir。你还可以设置 maxDurationMs、maxWidth 和 maxHeight，作为此浏览器启动的每次录制的默认值。

以下示例为 AgentBrowser 启用录制：

src/mastra/browsers/agent-browser.ts

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

export const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
    maxDurationMs: 60_000,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

相同选项也适用于 StagehandBrowser：

src/mastra/browsers/stagehand-browser.ts

import { join } from 'node:path'
import { StagehandBrowser } from '@mastra/stagehand'

export const browser = new StagehandBrowser({
  headless: false,
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
    maxDurationMs: 60_000,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

Agent 仍可在每次录制开始时向 browser_record Tool 传入 maxDurationMs、maxWidth 或 maxHeight，覆盖这些默认值。

录制 Tool

启用录制后会添加以下 Tool：

Tool	说明
browser_record	开始、停止录制或检查录制状态。
browser_record_caption	在录制的当前时间点添加简短字幕。

browser_record 接受 action 字段：

• start：开始录制当前浏览器会话。
• status：检查录制是否正在进行。
• stop：停止录制并写入 .avi 文件。

browser_record 的 outputPath 选项必须是已配置的 recording.outputDir 内的绝对路径。如果省略，Mastra 会在 outputDir 中创建文件。

Agent 指令示例

告诉 Agent 何时录制以及何时添加字幕：

src/mastra/agents/browser-agent.ts

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

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `Use browser tools to complete the requested task.

When the user asks for a recording:
1. Call browser_record with action="start" before browser work begins.
2. After each major action, call browser_record_caption with a caption of about six words.
3. Call browser_record with action="stop" as soon as the task is complete.
4. Return the saved video path to the user.`,
})

输出格式和限制

录制内容保存为 Motion-JPEG AVI 文件。此格式使用 JavaScript 编码，不需要 ffmpeg 或原生依赖项。

默认限制：

• 最长时长：30 秒
• 硬性时长上限：120 秒
• 最大帧尺寸：1024 × 720
• 字幕：每条 80 个字符
• 每个进程只能进行一项录制

请尽可能使用较短的录制。较长的浏览器会话会生成更大的文件，也更难回顾。

后续步骤

• AgentBrowser
• Stagehand
• Browser 概览