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

# StorageBrowserRef

`StorageBrowserRef` 是附加到已存储 Agent 的内联 browser 配置。实例化时，会根据在 [`MastraEditor.browsers`](https://mastra.zisheng.pro/reference/editor/mastra-editor) 上注册的 [`BrowserProvider`](https://mastra.zisheng.pro/reference/editor/browser-provider) 解析 `provider` id。

[`BuilderAgentDefaults.browser`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) 和已存储 Agent 记录均使用此类型。

## 使用示例

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

new MastraEditor({
  browsers: { [stagehandBrowserProvider.id]: stagehandBrowserProvider },
  builder: {
    enabled: true,
    configuration: {
      agent: {
        browser: {
          type: 'inline',
          config: {
            provider: 'stagehand',
            headless: true,
            viewport: { width: 1280, height: 720 },
          },
        },
      },
    },
  },
})
```

## 类型

```typescript
type StorageBrowserRef = { type: 'inline'; config: StorageBrowserConfig }
```

Browser 不支持 `{ type: 'id' }` 变体：它们始终以内联方式存储。

## 属性

**type** (`'inline'`): 判别字段。必须是字面量 "inline"。

**config** (`StorageBrowserConfig`): Provider id 和每个实例的 browser 配置。请参阅下文。

## `StorageBrowserConfig`

嵌入在 `config` 下的数据结构。定义于 `@mastra/core/storage`。

**provider** (`string`): Provider 标识符（例如 "stagehand"）。必须与在 MastraEditor.browsers 上注册的 BrowserProvider.id 一致。没有内置 Provider。

**headless** (`boolean`): 以无头模式运行 browser（无可见 UI）。 (Default: `true`)

**viewport** (`{ width: number; height: number }`): Browser viewport 尺寸。用于控制窗口大小以及页面的渲染方式。

**timeout** (`number`): Browser 操作的默认超时时间（毫秒）。 (Default: `10000`)

**screencast** (`ScreencastOptions`): 用于将 browser 帧流式传输到 UI 的 screencast 选项。

**screencast.format** (`'jpeg' | 'png'`): 图像格式。

**screencast.quality** (`number`): JPEG 质量，范围为 0–100。

**screencast.maxWidth** (`number`): 最大宽度（像素）。

**screencast.maxHeight** (`number`): 最大高度（像素）。

**screencast.everyNthFrame** (`number`): 每隔 N 帧捕获一次。

## 实例化

`StorageBrowserRef` 会在调用 `mastra.editor.agent.getById()` 时延迟解析。Editor 在 `MastraEditor.browsers` 中查找 `config.provider`，然后调用 `provider.createBrowser(config)`。如果 Provider 未注册，Editor 会记录警告并返回 `undefined`：Agent 仍会加载，但不包含 browser。

## 相关内容

- [Browser](https://agent-builder.mastra.ai/browser)：概念和完整示例。
- [BrowserProvider](https://mastra.zisheng.pro/reference/editor/browser-provider)：面向实现者的 Provider 接口。
- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults)：将此类型固定为 Builder 默认值的位置。
- [StorageWorkspaceRef](https://mastra.zisheng.pro/reference/editor/storage-workspace-ref)：用于 Workspace 配置的同级引用类型。