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

# StorageWorkspaceRef

`StorageWorkspaceRef` は、保存済み Agent に Workspace を関連付けるための判別共用体です。ID によって Mastra ランタイムに登録された Workspace を参照するか、Workspace のスナップショットをインラインで埋め込みます。

これは、[`BuilderAgentDefaults.workspace`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) と保存済み Agent レコードで使用される型です。

## 使用例

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

// Variant 1 — reference a runtime workspace by id
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: { type: 'id', workspaceId: 'builder-workspace' },
      },
    },
  },
})

// Variant 2 — inline a workspace snapshot
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: {
          type: 'inline',
          config: {
            name: 'inline-builder-workspace',
            filesystem: {
              provider: 'local',
              config: { basePath: './agent-files' },
            },
          },
        },
      },
    },
  },
})
```

## バリアント

**{ type: 'id'; workspaceId: string }** (`IdRef`): Mastra ランタイムに new Mastra({ workspace }) または mastra.addWorkspace() で登録された Workspace を参照します。id は、管理設定、保存済み Agent レコード、ハイドレーションを結び付けるキーです。

**{ type: 'id'; workspaceId: string }.type** (`'id'`): 判別子。リテラル "id" でなければなりません。

**{ type: 'id'; workspaceId: string }.workspaceId** (`string`): Mastra ランタイムに登録された Workspace の ID。Builder が Workspace のスナップショットを取得して永続化し、後でハイドレートするために使用します。

**{ type: 'inline'; config: StorageWorkspaceSnapshotType }** (`InlineRef`): Workspace のスナップショットを直接埋め込みます。Builder は inline-\<sha256(config)\[:12]> 形式の決定的な ID を生成してスナップショットを永続化するため、同一のインライン設定は Agent 間で重複排除されます。

**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.type** (`'inline'`): 判別子。リテラル "inline" でなければなりません。

**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.config** (`StorageWorkspaceSnapshotType`): シリアライズされた Workspace 設定（filesystem、sandbox、mounts、search、skills、tools）。フィールド一覧については、以下の StorageWorkspaceSnapshotType セクションを参照してください。

## `StorageWorkspaceSnapshotType`

`{ type: 'inline', config }` の config に埋め込まれる構造です。`@mastra/core/storage` で定義されています。

**name** (`string`): Workspace の表示名。

**description** (`string`): Workspace 一覧に表示される用途の説明。

**filesystem** (`StorageFilesystemConfig`): プライマリファイルシステムの設定。provider は MastraEditor.filesystems に登録された ID（組み込み：local）と一致する必要があります。

**sandbox** (`StorageSandboxConfig`): Sandbox の設定。provider は MastraEditor.sandboxes に登録された ID（組み込み：local）と一致する必要があります。

**mounts** (`Record<string, StorageFilesystemConfig>`): Workspace にマウントする追加のファイルシステム。マウントパスをキーとします。

**search** (`StorageSearchConfig`): 検索設定（ベクトル Provider、Embedder、BM25 設定）。

**skills** (`string[]`): この Workspace に割り当てる Skill エンティティの ID。

**tools** (`StorageWorkspaceToolsConfig`): Workspace の Tool 設定（許可リスト、デフォルト）。

**autoSync** (`boolean`): ファイルシステムと Sandbox の間で自動同期します。 (Default: `false`)

**operationTimeout** (`number`): 個々の操作のタイムアウト（ミリ秒）。

## ハイドレーション

`StorageWorkspaceRef` は `list()` ではなく、`mastra.editor.agent.getById()` の呼び出し時に遅延解決されます。Editor は `MastraEditor.filesystems` / `MastraEditor.sandboxes` からファイルシステムと Sandbox の Provider を検索し、ランタイムの `Workspace` を実体化します。Provider が見つからない場合は警告が表示され、Workspace は省略されます。

## 関連項目

- [Workspace](https://agent-builder.mastra.ai/workspace)：概念と実践的な例。
- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults)：この型が Builder のデフォルトとして固定される場所。
- [MastraEditor クラス](https://mastra.zisheng.pro/ja/reference/editor/mastra-editor)：ファイルシステムと Sandbox の Provider を登録します。
- [StorageBrowserRef](https://mastra.zisheng.pro/ja/reference/editor/storage-browser-ref)：ブラウザー設定に対応する関連参照型。