> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 浏览器录制（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` 启用录制：

```typescript
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`：

```typescript
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 何时录制以及何时添加字幕：

```typescript
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](https://mastra.zisheng.pro/docs/browser/agent-browser)
- [Stagehand](https://mastra.zisheng.pro/docs/browser/stagehand)
- [Browser 概览](https://mastra.zisheng.pro/docs/browser/overview)