瀏覽器錄影（測試版）

新增於： @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 啟用錄影：

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 仍可按每次錄影覆寫這些預設值，方法是在開始時將 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 何時錄影及何時加入字幕：

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
• 瀏覽器概覽