BrowserProvider

BrowserProvider is the interface a package implements to register a browser with MastraEditor. The editor calls createBrowser(config) at agent hydration time, using the provider id from the stored StorageBrowserRef as the lookup key.

There are no built-in browser providers. To use the browser feature in the Agent Builder, register a provider package (for example, @mastra/stagehand).

Usage example

src/mastra/index.ts

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

new MastraEditor({
  browsers: {
    [stagehandBrowserProvider.id]: stagehandBrowserProvider,
  },
})

Properties

id:

string

Unique provider identifier (for example, `"stagehand"`). Must match `StorageBrowserConfig.provider` on every stored agent that uses this provider.

name:

string

Human-readable name for UI display.

description?:

string

Short description shown in the Agent Builder browser picker.

configSchema?:

Record<string, unknown>

JSON Schema describing provider-specific configuration. Used by the UI to render config forms.

createBrowser:

(config: TConfig) => MastraBrowser | Promise<MastraBrowser>

Create a runtime `MastraBrowser` instance from the stored config. Called once per agent hydration; the resulting instance is cached alongside the agent.

Implementing a provider

src/providers/my-browser.ts

import type { BrowserProvider, MastraBrowser } from '@mastra/core/editor'

export const myBrowserProvider: BrowserProvider<{ apiKey: string }> = {
  id: 'my-browser',
  name: 'My Browser',
  description: 'Headless browser for agent use.',
  configSchema: {
    type: 'object',
    properties: {
      apiKey: { type: 'string' },
    },
    required: ['apiKey'],
  },
  async createBrowser(config): Promise<MastraBrowser> {
    // construct and return a MastraBrowser instance
    return createMastraBrowser({ apiKey: config.apiKey })
  },
}

Once registered, admins can pin the provider as a Builder default via BuilderAgentDefaults.browser:

new MastraEditor({
  browsers: { [myBrowserProvider.id]: myBrowserProvider },
  builder: {
    enabled: true,
    configuration: {
      agent: {
        browser: { type: 'inline', config: { provider: 'my-browser' } },
      },
    },
  },
})

Related

• Browser — concept and worked examples.
• StorageBrowserRef — stored configuration consumed by createBrowser.
• MastraEditor class — provider registry.