ブラウザ録画（ベータ版）

追加バージョン: @mastra/core@1.43.0

ブラウザ録画では、Agent がブラウザセッションを Motion-JPEG AVI 動画として保存できる、オプトイン方式の 2 つの Tool が追加されます。Agent は作業中に短いキャプションを追加することもできます。

beta

この機能はベータ版です。API が安定するまでは、メジャーバージョンを上げずに破壊的変更が行われる可能性があります。

ブラウザ録画を使用する場面

次のような場合にブラウザ録画を使用します。

• Agent がブラウザで行った操作を確認したい
• 短いブラウザ自動化の実行内容をチームメンバーと共有したい
• 実行されなかった操作、ページ読み込みの遅延、予期しないナビゲーションをデバッグしたい
• 主な手順を説明する短いキャプションを追加したい

録画 Tool はデフォルトで無効です。動画ファイルの書き込みが必要な Agent に対してのみ有効にしてください。

録画を有効にする

AgentBrowser または StagehandBrowser に recording オブジェクトを渡します。必須フィールドは 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 は、録画開始時に 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 instructions の例

録画するタイミングとキャプションを追加するタイミングを 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
• キャプション: 1 件あたり 80 文字
• プロセスごとに 1 件のアクティブな録画

可能な限り短く録画してください。長いブラウザセッションではファイルが大きくなり、確認も難しくなります。

次のステップ

• AgentBrowser
• Stagehand
• Browser の概要