瀏覽器錄製（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 啟用錄製：

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

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 概觀