@mastra/core/dist/docs/references/reference-editor-browser-provider.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# BrowserProvider

`BrowserProvider` is the interface a package implements to register a browser with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createBrowser(config)` at agent hydration time, using the `provider` id from the stored [`StorageBrowserRef`](https://mastra.ai/reference/editor/storage-browser-ref) as the lookup key.

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

## Usage example

```typescript
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

```typescript
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`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults):

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

## Related

- [Browser](https://mastra.ai/docs/agent-builder/browser) — concept and worked examples.
- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — stored configuration consumed by `createBrowser`.
- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry.