Browser recording (beta)

Added in: @mastra/core@1.43.0

Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.

beta

This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.

When to use browser recording

Use browser recording when you need to:

• Review what an agent did in a browser
• Share a short browser automation run with a teammate
• Debug missed actions, slow page loads, or unexpected navigation
• Add short captions that explain each major step

Recording tools are disabled by default. Enable them only for agents that need to write video files.

Enable recording

Pass a recording object to AgentBrowser or StagehandBrowser. The only required field is outputDir. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording started by this browser.

The following example enables recording for 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,
  },
})

The same option works with 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,
  },
})

The agent can still override these defaults per-recording by passing maxDurationMs, maxWidth, or maxHeight to the browser_record tool at start time.

Recording tools

Enabling recording adds these tools:

Tool	Description
browser_record	Starts, stops, or checks the status of a recording.
browser_record_caption	Adds a short caption at the current moment in the recording.

browser_record accepts an action field:

• start: Start recording the current browser session.
• status: Check whether a recording is active.
• stop: Stop recording and write the .avi file.

The outputPath option for browser_record must be an absolute path inside the configured recording.outputDir. If you omit it, Mastra creates a file in outputDir.

Example agent instructions

Tell the agent when to record and when to add captions:

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.5',
  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.`,
})

Output format and limits

Recordings are saved as Motion-JPEG AVI files. This format is encoded in JavaScript and doesn't require ffmpeg or native dependencies.

Default limits:

• Maximum duration: 30 seconds
• Hard duration cap: 120 seconds
• Maximum frame size: 1024 × 720
• Captions: 80 characters each
• One active recording per process

Use shorter recordings when possible. Long browser sessions produce larger files and are harder to review.

Next steps

• AgentBrowser
• Stagehand
• Browser overview