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

# Workspace

**追加バージョン:** `@mastra/core@1.1.0`

Mastra Workspace は、ファイルの保存やコマンドの実行に使用できる永続的な環境を Agent に提供します。Agent は Workspace Tool を使用して、ファイルの読み書き、シェルコマンドの実行、インデックス化されたコンテンツの検索を行います。

Workspace は次の機能をサポートします。

- **[Filesystem](https://mastra.zisheng.pro/ja/docs/workspace/filesystem)**: ファイルストレージ（読み取り、書き込み、一覧表示、削除、コピー、移動、grep）
- **[Sandbox](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)**: コマンド実行（シェルコマンド）とバックグラウンドプロセス
- **[LSP inspection](https://mastra.zisheng.pro/ja/docs/workspace/lsp)**: Language Server を介したホバー、定義、実装の照会
- **[Search](https://mastra.zisheng.pro/ja/docs/workspace/search)**: インデックス化されたコンテンツに対する BM25、ベクトル、またはハイブリッド検索
- **[Skills](https://mastra.zisheng.pro/ja/docs/workspace/skills)**: Agent 向けの再利用可能な指示

## Workspace を使用する場面

Agent がローカルファイルシステム、シェルコマンド、セマンティックなコード検査、インデックス検索、または再利用可能な Skill の指示にアクセスする必要がある場合に Workspace を使用します。

## 仕組み

Agent に Workspace を割り当てると、Mastra は対応する Tool を Agent の Tool セットに追加します。これにより、Agent はこれらの Tool を使用してファイルを操作し、コマンドを実行できます。

サポートされている機能を任意に組み合わせて Workspace を作成できます。Agent が受け取るのは、設定された機能に関連する Tool だけです。

## 使用方法

### Workspace の作成

必要な機能を指定して `Workspace` クラスをインスタンス化し、Workspace を作成します。

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  skills: ['skills'],
})
```

`skills` 配列には、Skill 定義を含むディレクトリへのパスを指定します。詳しくは [Skills](https://mastra.zisheng.pro/ja/docs/workspace/skills) を参照してください。

### グローバル Workspace

Mastra インスタンスに Workspace を設定します。独自の Workspace を定義していない限り、すべての Agent がこの Workspace を継承します。

```typescript
import { Mastra } from '@mastra/core'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
})

const mastra = new Mastra({
  workspace,
})
```

### Agent レベルの Workspace

グローバル Workspace を上書きするには、Agent に Workspace を直接割り当てます。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './agent-workspace' }),
})

export const myAgent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})
```

## ライフサイクルとクリーンアップ

Mastra はグローバル Workspace と Agent の Workspace を登録するため、実行時に一覧表示および取得できます。`mastra.shutdown()` を呼び出すと、Mastra が所有する登録済み Workspace が破棄されます。これにより、Language Server、ブラウザー、Sandbox プロセス、Filesystem Provider のハンドルなどの Workspace リソースが閉じられます。

手動でクリーンアップするには、[`mastra.removeWorkspace()`](https://mastra.zisheng.pro/ja/reference/core/removeWorkspace) を使用します。レジストリから削除する前に Workspace を破棄する場合は、`{ destroy: true }` を渡します。

静的 Provider は Workspace が所有します。Resolver ベースの Provider はリクエスト時に Workspace が作成するため、アプリケーションが所有します。Resolver のクリーンアップモデルについては、[実行時の Sandbox ライフサイクルの所有権](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)を参照してください。

## 設定パターン

Workspace は、Agent に必要な機能に応じて複数の設定パターンをサポートします。主な構成要素は `filesystem`（ファイル Tool）と `sandbox`（コマンド実行）で、`mounts` を使用するとクラウドストレージを Sandbox に接続できます。

### Filesystem + Sandbox（ローカル）

ローカル開発では、同じディレクトリを指す `LocalFilesystem` と `LocalSandbox` を組み合わせます。どちらもローカルマシン上で動作するため、Filesystem 経由で書き込まれたファイルは Sandbox 内のコマンドからすぐに利用できます。

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
})
```

Agent はファイル Tool と `execute_command` の両方を受け取ります。これは、すべての機能を利用できる最もシンプルな設定です。

### Mounts + Sandbox（クラウドストレージ）

Sandbox 内からクラウドストレージにアクセスする必要がある場合は、`mounts` を使用します。クラウドの Filesystem が FUSE によって Sandbox 内へマウントされ、コマンドはマウントパスにあるファイルを読み書きできるようになります。

```typescript
const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

内部では、`mounts` が [CompositeFilesystem](https://mastra.zisheng.pro/ja/docs/workspace/filesystem) を作成し、パスのプレフィックスに基づいてファイル Tool の操作を適切な Provider に振り分けます。Sandbox 内のコマンドは、マウントされたパスに直接アクセスします（例: `ls /data`）。

異なるパスに複数の Provider をマウントできます。各マウントパスは一意で、互いに重複してはいけません。

> **注記:** `filesystem` と `mounts` は相互に排他的で、同じ Workspace では併用できません。Sandbox を使用せず単一の Provider を利用する場合は `filesystem` を、クラウドストレージと Sandbox を組み合わせる場合は `mounts` を使用してください。

### Filesystem のみ

Agent がファイルの読み書きだけを必要とする場合は、単一の `filesystem` を使用します。コマンド実行は利用できません。

```typescript
const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
})
```

Agent は、ストレージ Provider を直接操作するファイル Tool（`read_file`、`write_file`、`list_directory`、`grep` など）を受け取ります。

### Sandbox のみ

Agent がコマンド実行だけを必要とする場合は、単一の `sandbox` を使用します。ファイル Tool は追加されません。

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

Agent は `execute_command` Tool を受け取ります。

### 動的 Filesystem（リクエスト単位）

リクエストごとに異なる Filesystem を返すには、Resolver 関数を `filesystem` に渡します。これは、リクエストごとに異なるストレージルートや権限が必要なマルチテナントアプリケーションや、複数のロールを扱う Agent に便利です。

```typescript
const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})
```

1つの Workspace インスタンスですべてのリクエストを処理します。Resolver は Tool の実行時に動作するため、リクエストごとに専用の Filesystem が割り当てられます。詳しくは[動的 Filesystem](https://mastra.zisheng.pro/ja/docs/workspace/filesystem)を参照してください。

### 動的 Sandbox（リクエスト単位）

リクエストごとに異なる Sandbox を返すには、Resolver 関数を `sandbox` に渡します。これは、ユーザーやロールごとに分離された作業ディレクトリや異なる実行権限が必要なマルチテナント環境で便利です。

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string
    return new LocalSandbox({
      workingDirectory: `/workspaces/${userId}`,
    })
  },
})
```

`mounts` と `lsp: true` は構築時に具体的な Sandbox インスタンスを必要とするため、Resolver と併用できません。詳しくは[動的 Sandbox](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)を参照してください。

### どのパターンを使用すべきですか？

| シナリオ                                        | パターン                                         |
| ------------------------------------------- | -------------------------------------------- |
| ファイルとコマンドを使用するローカル開発                        | `filesystem` + `sandbox`（両方ともローカルで、同じディレクトリ） |
| クラウド Sandbox 内からアクセスできるクラウドストレージ            | `mounts` + `sandbox`                         |
| 1つの Sandbox で複数のクラウド Provider を使用           | `mounts` + `sandbox`（Provider ごとに1つのマウント）    |
| Agent はファイルを読み書きし、コマンド実行は不要                 | `filesystem` のみ                              |
| Agent はコマンドを実行し、ファイル Tool は不要               | `sandbox` のみ                                 |
| リクエスト単位のストレージを使用する、複数ロール対応またはマルチテナントの Agent | Resolver 関数を指定した `filesystem`                |
| リクエスト単位の実行スコープを使用するマルチテナント Agent            | Resolver 関数を指定した `sandbox`                   |

## Tool の設定

Workspace の `tools` オプションを使用して Tool の動作を設定します。このオプションは、有効にする Tool とその動作を制御します。

```typescript
import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    // Global defaults
    enabled: true,
    requireApproval: false,

    // Per-tool overrides
    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
      requireApproval: true,
      requireReadBeforeWrite: true,
    },
    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: {
      enabled: false,
    },
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      requireApproval: true,
    },
  },
})
```

### Tool オプション

| オプション                    | 型                                 | 説明                                                                                    |
| ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------- |
| `enabled`                | `boolean \| (context) => boolean` | Tool が利用可能かどうか（デフォルト: `true`）。関数の場合は、Tool の一覧取得時に評価されます。                              |
| `requireApproval`        | `boolean \| (context) => boolean` | Tool の実行前にユーザーの承認が必要かどうか（デフォルト: `false`）。関数の場合は、`args` にアクセスできる状態で実行時に評価されます。         |
| `requireReadBeforeWrite` | `boolean \| (context) => boolean` | 書き込み Tool で、先にファイルを読み取る必要があるかどうか（デフォルト: `false`）。関数の場合は、`args` にアクセスできる状態で実行時に評価されます。 |
| `name`                   | `string`                          | Tool のカスタム名。デフォルトの `mastra_workspace_*` 名を置き換えます。                                     |
| `maxOutputTokens`        | `number`                          | Tool 出力の最大トークン数（デフォルト: `2000`）。この制限を超えた出力は、tiktoken を使用して切り詰められます。                    |

### Tool の動的設定

関数を受け取る Tool オプションにはコンテキストオブジェクトが渡され、関数は真偽値を返します。これにより、コンテキストに応じた Tool の動作を設定できます。

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  tools: {
    // Dynamic enabled: disable command execution unless explicitly allowed
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      enabled: async ({ requestContext }) => {
        return requestContext['allowExecution'] === 'true'
      },
    },

    // Dynamic requireApproval: only require approval for protected paths
    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
      requireApproval: async ({ args }) => {
        return (args.path as string).startsWith('/protected')
      },
      requireReadBeforeWrite: true,
    },
  },
})
```

`enabled` の関数は `{ requestContext, workspace }` を受け取ります。`requireApproval` と `requireReadBeforeWrite` の関数は Tool の呼び出し時に評価されるため、さらに `args` も受け取ります。

### Tool 名の再マッピング

Agent が想定する命名規則に合わせて Workspace Tool の名前を変更できます。設定キーには元の `WORKSPACE_TOOLS` 定数を使用し、公開される名前だけが変わります。

```typescript
import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: true,
  tools: {
    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' },
    [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' },
    [WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES]: { name: 'find_files' },
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: { name: 'execute_command' },
    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: { name: 'lsp_inspect' },
  },
})
```

Agent には、デフォルトの `mastra_workspace_*` 名ではなく、`view`、`search_content`、`find_files`、`execute_command`、`lsp_inspect` が表示されます。Tool 名は一意である必要があり、重複した名前や他のデフォルト名と競合する名前を指定するとエラーがスローされます。

### Tool フック

有効な Workspace Tool の各呼び出し前後にロジックを実行するには、`tools.hooks` を設定します。フックは名前の再マッピング後に実行されるため、フックのコンテキストには、公開された `toolName` と元の `workspaceToolName` の両方が含まれます。

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  tools: {
    hooks: {
      beforeToolCall: ({ toolName, workspaceToolName, input }) => {
        console.log(`Running ${toolName} (${workspaceToolName})`, input)
      },
      afterToolCall: ({ toolName, output, error }) => {
        console.log(`Finished ${toolName}`, { output, error })
      },
    },
  },
})
```

`beforeToolCall` から `{ proceed: false, output }` を返すと、Tool の呼び出しをスキップし、`output` を結果として使用します。

所有元の Agent にも [Tool フック](https://mastra.zisheng.pro/ja/docs/agents/using-tools)が定義されている場合、Workspace のフックは Agent のフックラッパー内で実行されます。実行順序は、Agent の `beforeToolCall`、Workspace の `beforeToolCall`、Tool、Workspace の `afterToolCall`、Agent の `afterToolCall` です。

## LSP inspection

Workspace で `lsp` を有効にすると、Language Server を介したセマンティックなコード検査が追加されます。デフォルトでは `mastra_workspace_lsp_inspect` Tool が追加され、ホバー情報、定義位置、および特定のカーソル位置にあるシンボルの実装を返せます。

設定、例、Tool 名の再マッピングについては、[LSP inspection](https://mastra.zisheng.pro/ja/docs/workspace/lsp)を参照してください。

### 出力の切り詰め

Workspace Tool は、LLM のコンテキスト制限を超えないように大きな出力を自動的に切り詰めます。次の切り詰め処理が適用されます。

1. **行数に基づく末尾の取得**: コマンド出力はデフォルトで末尾の200行に制限されます（コマンドごとに `tail` パラメーターで設定可能）
2. **トークン数に基づく制限**: Tool の出力はデフォルトで2000トークンに制限されます

Tool ごとに `maxOutputTokens` を設定して、トークン数の上限を調整します。

```typescript
const workspace = new Workspace({
  // ...
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      maxOutputTokens: 5000,
    },
  },
})
```

ANSI エスケープコード（色、カーソルシーケンス）は、モデルに渡される前にコマンド出力から自動的に削除されます。

### 書き込み前の読み取り

書き込み Tool で `requireReadBeforeWrite` を有効にすると、Agent はファイルを書き込む前にそのファイルを読み取る必要があります。これにより、Agent が確認していないファイルの上書きを防ぎます。

- **新規ファイル**: 読み取らずに書き込めます（まだ存在しないため）
- **既存ファイル**: 最初に読み取る必要があります
- **外部で変更されたファイル**: Agent が読み取った後にファイルが変更されていると、書き込みは失敗します

ファイル書き込みの安全性は、次の2つのレイヤーで確保されます。

1. **Tool レイヤー**: 書き込み Tool の実行前に、読み取りトラッカーが、ファイルが最後に読み取られてから変更されていないか確認します。変更されている場合、Tool は `FileReadRequiredError` をスローします。
2. **Filesystem レイヤー**: 書き込み時に、`writeFile()` がファイルの現在の変更時刻を、書き込みオプションの `expectedMtime` で渡された想定値と比較します。一致しない場合は `StaleFileError` をスローします。これにより、Tool レイヤーでの確認から実際の書き込みまでの間に行われた外部変更（たとえば、エディターによるファイル保存）を検出できます。

`requireReadBeforeWrite` が有効な場合、Workspace Tool は記録された変更時刻を自動的に渡します。Tool の外部で `filesystem.writeFile()` を呼び出す場合は、`expectedMtime` を直接指定することもできます。

```typescript
const stat = await filesystem.stat('/docs/file.md')
// ... later ...
await filesystem.writeFile('/docs/file.md', newContent, {
  expectedMtime: stat.modifiedAt,
})
```

## 初期化

ほとんどの場合、`init()` の呼び出しは任意です。一部の Provider は最初の操作時に初期化されます。Mastra の外部（スタンドアロンスクリプトやテスト）で Workspace を使用する場合や、Agent の最初の操作前にリソースを事前準備する必要がある場合は、`init()` を手動で呼び出してください。

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
})

// Optional: pre-create directories and sandbox before first use
await workspace.init()
```

### `init()` の処理

初期化では、設定された各 Provider のセットアップロジックが実行されます。

- `LocalFilesystem`: ベースディレクトリが存在しない場合に作成します
- `LocalSandbox`: 作業ディレクトリを作成します
- `Search`（設定されている場合）: `autoIndexPaths` のファイルをインデックス化します。詳しくは [Search and Indexing](https://mastra.zisheng.pro/ja/docs/workspace/search) を参照してください

外部 Provider では、接続の確立や認証など、追加のセットアップが行われる場合があります。

## 関連項目

- [Filesystem](https://mastra.zisheng.pro/ja/docs/workspace/filesystem)
- [Sandbox](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)
- [LSP inspection](https://mastra.zisheng.pro/ja/docs/workspace/lsp)
- [Skills](https://mastra.zisheng.pro/ja/docs/workspace/skills)
- [検索とインデックス作成](https://mastra.zisheng.pro/ja/docs/workspace/search)
- [Workspace クラスのリファレンス](https://mastra.zisheng.pro/ja/reference/workspace/workspace-class)
- 📹 [Mastra Workspaces 入門ワークショップ](https://www.youtube.com/watch?v=QcQLiYlJuNQ)