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

# StorageBrowserRef

`StorageBrowserRef` 是附加至已儲存 Agent 的內嵌瀏覽器設定。具現化時，會使用在 [`MastraEditor.browsers`](https://mastra.zisheng.pro/zh-TW/reference/editor/mastra-editor) 上註冊的 [`BrowserProvider`](https://mastra.zisheng.pro/zh-TW/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 }
```

瀏覽器不提供 `{ type: 'id' }` 變體，一律使用內嵌設定。

## 屬性

**type** (`'inline'`): 判別欄位。必須是常值 "inline"。

**config** (`StorageBrowserConfig`): Provider ID 與各執行個體的瀏覽器設定。請參閱下一節。

## `StorageBrowserConfig`

內嵌於 `config` 下的資料結構，定義於 `@mastra/core/storage`。

**provider** (`string`): Provider 識別碼（例如 "stagehand"）。必須與 MastraEditor.browsers 上註冊的 BrowserProvider.id 相符。目前沒有內建 Provider。

**headless** (`boolean`): 以 headless 模式執行瀏覽器（不顯示 UI）。 (Default: `true`)

**viewport** (`{ width: number; height: number }`): 瀏覽器檢視區尺寸，控制視窗大小與頁面呈現方式。

**timeout** (`number`): 瀏覽器操作的預設逾時時間，以毫秒為單位。 (Default: `10000`)

**screencast** (`ScreencastOptions`): 將瀏覽器畫面串流至 UI 的螢幕錄製選項。

**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](https://agent-builder.mastra.ai/browser)：概念與完整範例。
- [BrowserProvider](https://mastra.zisheng.pro/zh-TW/reference/editor/browser-provider)：供實作者使用的 Provider 介面。
- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults)：將此類型固定為 Builder 預設值的位置。
- [StorageWorkspaceRef](https://mastra.zisheng.pro/zh-TW/reference/editor/storage-workspace-ref)：Workspace 設定的同類參照類型。