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

# 瀏覽器錄影（測試版）

**新增於：** `@mastra/core@1.43.0`

瀏覽器錄影功能新增了兩個可選用的 Tool，讓 Agent 將瀏覽器工作階段儲存為 Motion-JPEG AVI 影片。Agent 亦可在操作期間加入簡短字幕。

> **Beta:** 此功能目前為測試版。在 API 穩定之前，即使沒有提升主要版本號，亦可能出現破壞性變更。

## 何時使用瀏覽器錄影

如有以下需要，可使用瀏覽器錄影：

- 檢視 Agent 在瀏覽器中執行過的操作
- 與團隊成員分享一段簡短的瀏覽器自動化操作過程
- 為遺漏的操作、頁面載入緩慢或非預期導覽進行除錯
- 加入簡短字幕，說明每個主要步驟

錄影 Tool 預設為停用。只應為需要寫入影片檔案的 Agent 啟用這些 Tool。

## 啟用錄影

將 `recording` 物件傳入 `AgentBrowser` 或 `StagehandBrowser`。唯一必填欄位是 `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 仍可按每次錄影覆寫這些預設值，方法是在開始時將 `maxDurationMs`、`maxWidth` 或 `maxHeight` 傳入 `browser_record` Tool。

## 錄影 Tool

啟用錄影後會新增以下 Tool：

| Tool                     | 說明               |
| ------------------------ | ---------------- |
| `browser_record`         | 開始、停止錄影，或檢查錄影狀態。 |
| `browser_record_caption` | 在錄影目前的時間點加入簡短字幕。 |

`browser_record` 接受 `action` 欄位：

- `start`：開始錄製目前的瀏覽器工作階段。
- `status`：檢查是否正在錄影。
- `stop`：停止錄影並寫入 `.avi` 檔案。

`outputPath` 選項（適用於 `browser_record`）必須是已設定 `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/zh-HK/docs/browser/agent-browser)
- [Stagehand](https://mastra.zisheng.pro/zh-HK/docs/browser/stagehand)
- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)