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

# 瀏覽器錄製（beta）

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

瀏覽器錄製會新增兩個可選擇啟用的 Tool，讓 Agent 能將瀏覽器工作階段儲存為 Motion-JPEG AVI 影片。Agent 也可以在工作過程中加入簡短字幕。

> **Beta:** 此功能目前為 beta。在 API 穩定前，次要版本可能會包含破壞性變更，不一定會提升主要版本號。

## 適合使用瀏覽器錄製的時機

在需要以下操作時使用瀏覽器錄製：

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

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

## 啟用錄製

將 `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` 檔案。

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