Browser

The Agent Builder can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, there are no built-in browser providers and you must register one through MastraEditor.browsers.

Quickstart

Register a browser provider on MastraEditor, then pin it as the Builder default through builder.configuration.agent.browser:

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { StagehandBrowser } from '@mastra/stagehand'

new MastraEditor({
  browsers: {
    stagehand: {
      id: 'stagehand',
      name: 'Stagehand Browser',
      createBrowser: config =>
        new StagehandBrowser({
          ...config,
          apiKey: process.env.BROWSERBASE_API_KEY ?? '',
          env: 'BROWSERBASE',
          projectId: process.env.BROWSERBASE_PROJECT_ID ?? '',
        }),
    },
  },
  builder: {
    enabled: true,
    configuration: {
      agent: {
        browser: {
          type: 'inline',
          config: { provider: 'stagehand', headless: true },
        },
      },
    },
  },
})

Browser providers

MastraEditor.browsers accepts a Record<string, BrowserProvider>. Each provider exposes:

• id: Provider identifier, matched against StorageBrowserConfig.provider (e.g., 'stagehand').
• name: Display name shown in the Builder UI.
• createBrowser(config): Hydrates a stored browser config into a runtime MastraBrowser. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.

Browser classes release as separate packages (e.g., @mastra/stagehand, @mastra/agent-browser). The provider entry is a plain object wrapping the class, register one entry per browser you want the Builder to expose to end users. See the StorageBrowserRef reference for the full browser field schema, including all StorageBrowserConfig options.

Feature toggle

The features.agent.browser toggle controls whether end users can enable browser access per agent in the Builder UI. It defaults to true only when a valid configuration.agent.browser (with a config.provider) is provided. Without a registered provider matching the pinned config, the toggle is forced off.