Introducing Browser Recording for Mastra Agents

Your Mastra agents can now record their browser sessions with browser recording. Each run writes a video file to disk letting you replay every step your agent took.

Recordings include open captions explaining what the agent is doing — “opening blog post”, “entering email address”, or “clicking submit” — embedding a running trace of its reasoning, useful for debugging and agent tuning.

Before browser recording, an agent's browser session was live-only in Studio. When the run ended, there was no option to replay. Now every session can be recorded, archived or shared with your team.

Browser recording exposes two tools to the agent: browser_record which starts and stops the recording, and browser_record_caption which adds the open captions.

Get started

Install a browser provider:

npm install @mastra/stagehand # or @mastra/agent-browser

Configure StagehandBrowser with an outputDir for recordings — and a headless mode:

import { join } from "node:path";
import { Agent } from "@mastra/core/agent";
import { StagehandBrowser } from "@mastra/stagehand";
 
export const webSearchAgent = new Agent({
  id: "webSearchAgent",
  name: "Web Search Agent",
  model: "anthropic/claude-opus-4-8",
  instructions: "You are a research assistant.",
  browser: new StagehandBrowser({
    headless: false,
    recording: {
      outputDir: join(process.cwd(), "browser-recordings")
    }
  })
});

When developing locally with Studio the above config would output a .avi file to: src/mastra/public/browser-recordings.

For more information and full configuration options, see:

• Browser recording
• Browser overview
• AgentBrowser
• StagehandBrowser