Workspace

Workspace は、Agent に File System へのアクセスとコマンド実行機能を提供します。mastra dev または mastra build で検出されたファイルベース Agent には、デフォルトの Workspace が自動的に割り当てられます。そのため、追加の設定なしでファイルの読み書きや Shell コマンドの実行が可能です。

ファイルベースの規約については、このページを参照してください。Workspace Provider、Tool、検索、Lifecycle、Sandbox の詳細については、Workspaceを参照してください。

デフォルトの Workspace

workspace.ts がない場合、ビルドによって Agent ごとの Workspace Path が提供されると、ファイルベース Agent にはデフォルトの Workspace が割り当てられます。デフォルトの Workspace では、次のものが使用されます。

• Agent にバンドルされた Workspace ディレクトリを Root とする LocalFilesystem。
• 同じ Working Directory を使用する LocalSandbox。

これにより、Agent には File Tool と Shell Tool が自動的に提供されます。デフォルトの Workspace は Agent ごとに用意されます。subagent には、親 Agent の Workspace Path の下にネストされた Workspace ディレクトリが割り当てられます。

クイックスタート

デフォルトの Workspace を使用する場合は、ファイルを追加する必要はありません。次のような Agent ディレクトリから始めます。

Default workspace

src/mastra/agents/weather/
├── config.ts
└── instructions.md

Workspace をカスタマイズする必要がある場合にのみ、workspace.ts を追加します。

src/mastra/agents/weather/workspace.ts

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

export default new Workspace({
  name: 'weather-workspace',
  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
})

すべての設定については、Workspace リファレンスを参照してください。

Workspace をカスタマイズする場合

デフォルトのローカルディレクトリでは不十分な場合は、Workspace をカスタマイズします。一般的な理由は次のとおりです。

• File Tool で別の File System Root を使用する。
• 別の Sandbox Provider で Shell コマンドを実行する。
• BM25 または Vector Search による Workspace 検索を追加する。
• 複数の Agent で1つの Workspace を共有する。

Provider のパターンと Runtime の動作については、Workspace の概要、Sandbox ガイド、Workspace 検索を参照してください。

Runtime の境界

Workspace の File System は、File Tool が読み書きできる範囲を制御します。Sandbox は、Shell コマンドが実行される場所を制御します。tools/ 内のコードを含むアプリケーションの Runtime コードは、Workspace API または Sandbox API を明示的に呼び出さない限り、引き続きアプリケーション／Server Process で実行されます。

Seed File

Agent に初期ファイルを含めるには、workspace/ ディレクトリを追加します。Mastra はビルド時に workspace/ 配下のファイルを Agent のデフォルト Runtime Workspace にミラーリングするため、Agent はそれらのファイルがディスク上に存在する状態で起動します。

Seed files

src/mastra/agents/weather/
├── config.ts
└── workspace/
    ├── README.md
    └── data/
        └── cities.json

ファイルはバンドルされた Workspace Path にコピーされ、Workspace の File Tool と Sandbox コマンドから読み取れるようになります。シンボリックリンクされた Seed File は、ミラーリング時にスキップされます。

config との優先順位

config.workspace は workspace.ts より優先されます。どちらもない場合は、ファイルベースのデフォルト Workspace が使用されます。完全なマージ表については、config.ts の優先順位を参照してください。