Workspace クラス

追加バージョン： @mastra/core@1.1.0

Workspace クラスは Filesystem と Sandbox を組み合わせ、ファイルストレージとコマンド実行機能を Agent に提供します。インデックス化した内容の BM25 検索とベクトル検索にも対応します。

使用例

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

const workspace = new Workspace({
  id: 'my-workspace',
  name: 'My Workspace',
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  bm25: true,
  autoIndexPaths: ['docs'],
})

コンストラクターパラメーター

id?:

string

= Auto-generated

Workspace の一意な識別子。

name?:

string

= workspace-{id}

人が読みやすい名前。

filesystem?:

WorkspaceFilesystem | WorkspaceFilesystemResolver

Filesystem Provider インスタンス、または requestContext を受け取りリクエストごとの Filesystem を返す Resolver 関数。動的 Filesystemを参照してください。

sandbox?:

WorkspaceSandbox | WorkspaceSandboxResolver

Sandbox Provider インスタンス、または requestContext を受け取りリクエストごとの Sandbox を返す Resolver 関数。動的 Sandboxを参照してください。

instructions.dynamicSandbox?:

'placeholder' | 'resolve' | (({ requestContext }) => string)

= 'placeholder'

Resolver ベースの sandbox を Workspace の指示へ反映する方法を制御します。'placeholder'（デフォルト）は Resolver を呼び出さず固定テキストを出力します。'resolve' は Resolver を呼び出して Sandbox 自身の指示を使用します。関数は解決せずにカスタムテキストを返します。静的な Sandbox には影響しません。

sandboxCacheKey?:

({ requestContext }) => string | undefined

Resolver ベースの sandbox 用の固定キャッシュキー。設定すると、解決済み Sandbox は RequestContext インスタンスごとではなくキーごとにメモ化されるため、バックグラウンドプロセス Tool は後続リクエストでも同じ Sandbox へアクセスできます。静的な Sandbox には影響しません。

bm25?:

boolean | BM25Config

= undefined

BM25 キーワード検索を有効にします。デフォルトを使用するには true、カスタマイズするには設定オブジェクトを渡します。

vectorStore?:

MastraVector

セマンティック検索用のベクトルストア。

embedder?:

Embedder

テキストをベクトルへ変換する関数。vectorStore を設定する場合は必須です。単一テキスト用の関数 (text: string) => Promise<number[]>、または batch: true プロパティと任意の maxBatchSize を持つバッチ対応関数 (texts: string[]) => Promise<number[][]> を指定できます。バッチ Embeddingを参照してください。

autoIndexPaths?:

string[]

init() で自動インデックス化するパスまたは glob パターン。'**/*.md' などの glob パターンで対象を選択できます。

skills?:

string[] | ((context: SkillsContext) => string[] | Promise<string[]>)

SKILL.md ファイルがあるパス。静的配列、またはパスを動的に解決する非同期関数を指定できます。検出には './**/skills' などの glob パターンを使用できます。

skillSource?:

SkillSource

Skill 検出用のカスタム Skill ソース。指定すると、Workspace の Filesystem の代わりにこのソースを使用します。コンテンツアドレス可能な Blob ストアから公開済み Skill バージョンを提供するには、VersionedSkillSource を使用します。

onMount?:

OnMountHook

Sandbox へマウントする前に、各 Filesystem に対して呼び出すマウント前フック。マウントを省略するには false、フックがマウントを処理した場合は { success: true } を返します。デフォルトのマウント動作を使用するには undefined を返します。

searchIndexName?:

string

ベクトルストアのカスタムインデックス名。有効な SQL 識別子である必要があります（英字またはアンダースコアで始まり、英字、数字、アンダースコアのみを含み、最大63文字）。デフォルトは '{id}_search' をサニタイズした値です。

tools?:

WorkspaceToolsConfig

Tool の有効化と安全性オプションを設定する Tool ごとの設定。

WorkspaceToolsConfig

enabled?:

boolean

Agent が Tool を利用できるかどうか。

requireApproval?:

boolean

Tool の実行前にユーザーの承認が必要かどうか。

name?:

string

この Tool を公開する際のカスタム名。デフォルトの mastra_workspace_* 名を置き換えます。設定キーには引き続き元の WORKSPACE_TOOLS 定数を使用する必要があります。

requireReadBeforeWrite?:

boolean

書き込み Tool で上書きを防ぐため、先にファイルを読み取ることを必須にします。

maxOutputTokens?:

number

Tool 出力の最大トークン数。この上限を超える出力は tiktoken で切り詰められます。

writeLockTimeoutMs?:

number

書き込み Tool が失敗するまでファイルごとの書き込みロックの取得を待つ最大時間（ミリ秒）。低速な Filesystem やコールドスタートする Filesystem（リモート Sandbox など）では、この値を増やしてください。

hooks?:

WorkspaceToolHooks

有効な Workspace Tool を呼び出すたびに、その前後で実行するフック。後述の Tool フックを参照してください。

operationTimeout?:

number

操作のタイムアウト（ミリ秒）。

Tool の設定

tools オプションは、有効にする Workspace Tool とその安全性設定を制御する WorkspaceToolsConfig オブジェクトを受け取ります。

import { Workspace } from '@mastra/core/workspace'
import { WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  id: 'my-workspace',
  name: 'My Workspace',
  tools: {
    // Global defaults (apply to all tools)
    enabled: true,
    requireApproval: false,

    // Per-tool overrides using WORKSPACE_TOOLS constants
    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
      requireApproval: true,
    },
  },
})

設定オブジェクトは2つの部分で構成されます。

• グローバルデフォルト（enabled、requireApproval）：上書きされない限り、すべての Tool に適用
• Tool ごとの上書き：WORKSPACE_TOOLS 定数をキーとして各 Tool を設定

その他の例は、Workspace の概要を参照してください。

Tool 名の再マッピング

各 Tool の設定で name プロパティを指定すると、Workspace Tool の名前を変更できます。設定キーは元の定数のままで、Agent に公開する名前だけが変わります。

import { Workspace } from '@mastra/core/workspace'
import { WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  id: 'my-workspace',
  name: 'My Workspace',
  tools: {
    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' },
    [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' },
  },
})

Tool 名は、すべての Workspace Tool で一意である必要があります。他の Tool のデフォルト名またはカスタム名と競合する名前を設定すると、エラーがスローされます。

Tool フック

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

import { Workspace } from '@mastra/core/workspace'

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

beforeToolCall?:

(context: WorkspaceToolHookContext) => void | WorkspaceToolBeforeHookResult | Promise<void | WorkspaceToolBeforeHookResult>

Workspace Tool の実行前に動作します。{ toolName, workspaceToolName, input, context } を受け取ります。Tool の呼び出しを省略して output を結果として使用するには、{ proceed: false, output } を返します。

afterToolCall?:

(context: WorkspaceToolAfterHookContext) => void | Promise<void>

Workspace Tool の実行後に動作します。{ toolName, workspaceToolName, input, context, output, error } を受け取ります。Tool がエラーをスローした場合、output は undefined となり、代わりに error が設定されます。

所有する Agent にも Tool フックが定義されている場合、Workspace フックは Agent フックのラッパー内で動作します。実行順序は Agent の beforeToolCall → Workspace の beforeToolCall → Tool → Workspace の afterToolCall → Agent の afterToolCall です。

プロパティ

id:

string

Workspace の識別子。

name:

string

Workspace 名。

status:

WorkspaceStatus

'pending' | 'initializing' | 'ready' | 'paused' | 'error' | 'destroying' | 'destroyed'

filesystem:

WorkspaceFilesystem | undefined

静的な Filesystem Provider。Resolver 関数が設定されている場合は undefined を返します。利用可否の確認には hasFilesystemConfig() を使用してください。

sandbox:

WorkspaceSandbox | undefined

静的な Sandbox Provider。Resolver 関数が設定されている場合は undefined を返します。利用可否の確認には hasSandboxConfig() を使用してください。

skills:

WorkspaceSkills | undefined

SKILL.md ファイルへアクセスするための Skill インターフェース。

canBM25:

boolean

BM25 検索が利用できるかどうか。

canVector:

boolean

ベクトル検索が利用できるかどうか。

canHybrid:

boolean

ハイブリッド検索が利用できるかどうか。

メソッド

ライフサイクル

init()

Workspace を初期化してリソースを準備します。

await workspace.init()

ほとんどの場合、init() の呼び出しは任意です。

• Sandbox：最初の executeCommand() 呼び出し時に自動起動します。最初のコマンドの遅延を避けるには init() を使用します。
• Filesystem：ベースディレクトリを作成し、Provider 固有の設定を実行します。一部の Provider は最初の操作時にディレクトリを自動作成します。
• 検索：autoIndexPaths で自動インデックス化する場合にのみ必要です。

初期化では次の処理を行います。

• Filesystem Provider を起動（必要に応じてベースディレクトリを作成）
• Sandbox Provider を起動（作業ディレクトリを作成し、設定されている場合は分離を設定）
• 検索用に autoIndexPaths のファイルをインデックス化

destroy()

Workspace を破棄してリソースをクリーンアップします。

await workspace.destroy()

destroy() は、Workspace が所有するリソースを Language Server、ブラウザー、Sandbox Provider、Filesystem Provider の順に閉じます。キャッシュ済みの Sandbox 参照も消去します。

アプリケーションで Workspace の使用を終えたら、destroy() を呼び出してください。mastra.shutdown() は、シャットダウン時に登録済み Workspace に対してこのメソッドを呼び出します。Mastra のレジストリから Workspace を削除するには、mastra.removeWorkspace() を使用します。

LocalFilesystem.destroy() はディスク上のファイルを削除しません。Resolver ベースの Filesystem Provider と Sandbox Provider はアプリケーションが所有するため、アプリケーション側でクリーンアップする必要があります。

検索操作

index(path, content, options?)

検索用に内容をインデックス化します。

await workspace.index('/docs/guide.md', 'Guide content...')

search(query, options?)

インデックス化した内容を検索します。

const results = await workspace.search('password reset', {
  topK: 10,
  mode: 'hybrid',
})

ユーティリティ

getInfo()

Workspace の情報を取得します。

const info = await workspace.getInfo()
// { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? }

Resolver を呼び出さず、Resolver ベースの Provider をランタイム定義として報告するには、resolveDynamicProviders: false を渡します。

const info = await workspace.getInfo({ resolveDynamicProviders: false })

パラメーター：

options.includeFileCount?:

boolean

ファイルの総数を数えるかどうか。大規模な Workspace では時間がかかることがあります。

options.requestContext?:

RequestContext

resolveDynamicProviders が有効な場合に、動的 Provider の Resolver へ渡します。

options.resolveDynamicProviders?:

boolean

= true

動的 Provider の Resolver を呼び出すかどうか。メタデータだけが必要で、Resolver ベースの Provider を dynamic として報告する場合は false に設定します。

getInstructions(opts?)

Filesystem Provider と Sandbox Provider の指示を組み合わせて返します。Agent が実行コンテキストを理解できるよう、システムメッセージへ挿入されます。

const instructions = workspace.getInstructions()

Provider の instructions オプションが関数の場合、リクエストごとのカスタマイズを有効にするには requestContext を渡します。

const instructions = workspace.getInstructions({ requestContext })

パラメーター：

opts.requestContext?:

RequestContext

Filesystem Provider または Sandbox Provider に instructions 関数が設定されている場合、その関数へ転送します。

戻り値： string

getInstructionsAsync(opts?)

Workspace の指示を組み合わせて返します。Workspace が Resolver ベースの Provider を使用する場合に利用します。ランタイム定義の Filesystem はリクエストごとに解決されます。ランタイム定義の Sandbox は、instructions.dynamicSandbox を 'resolve' に設定しない限り、固定のプレースホルダーテキストを提供します。

const instructions = await workspace.getInstructionsAsync({ requestContext })

パラメーター：

opts.requestContext?:

RequestContext

動的 Filesystem の Resolver、および instructions.dynamicSandbox が 'resolve' の場合は動的 Sandbox の Resolver へ渡します。

戻り値： Promise<string>

デフォルトの出力を上書きするには、LocalFilesystem または LocalSandbox へ instructions オプションを渡します。

getToolsConfig()

現在の Tool 設定を取得します。

const config = workspace.getToolsConfig()

戻り値： WorkspaceToolsConfig | undefined

setToolsConfig(config?)

実行時に Tool ごとの設定を置き換えます。以前の設定とはマージせず、完全に置き換えます。デフォルトへ戻すには undefined を渡します。変更は次の Agent 操作（次の createWorkspaceTools() 呼び出し）から有効になります。

import { WORKSPACE_TOOLS } from '@mastra/core/workspace'

// Disable write tools for read-only mode
workspace.setToolsConfig({
  [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { enabled: false },
  [WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE]: { enabled: false },
})

// Reset to defaults
workspace.setToolsConfig(undefined)

パラメーター：

config?:

WorkspaceToolsConfig | undefined

適用する新しい Tool 設定。デフォルトへ戻すには undefined を渡します。

動的 Filesystem

hasFilesystemConfig()

静的インスタンスまたは Resolver 関数として Filesystem が設定されているか確認します。Resolver ベースの Workspace では filesystem プロパティが undefined を返すため、workspace.filesystem を直接確認せず、このメソッドを使用してください。

if (workspace.hasFilesystemConfig()) {
  // Filesystem tools are available
}

戻り値： boolean

resolveFilesystem({ requestContext })

リクエストコンテキスト用の Filesystem を解決します。Resolver 関数が設定されている場合、指定された requestContext で呼び出します。静的な Filesystem が設定されている場合は、その値を直接返します。Filesystem が設定されていない場合は undefined を返します。

import { RequestContext } from '@mastra/core/request-context'

const ctx = new RequestContext([['agent-role', 'admin']])
const fs = await workspace.resolveFilesystem({ requestContext: ctx })

パラメーター：

requestContext:

RequestContext

Resolver 関数へ渡すリクエストコンテキスト。

戻り値： Promise<WorkspaceFilesystem | undefined>

動的 Sandbox

hasSandboxConfig()

静的インスタンスまたは Resolver 関数として Sandbox が設定されているか確認します。Resolver ベースの Workspace では sandbox プロパティが undefined を返すため、workspace.sandbox を直接確認せず、このメソッドを使用してください。

if (workspace.hasSandboxConfig()) {
  // Sandbox tools are available
}

戻り値： boolean

resolveSandbox({ requestContext })

リクエストコンテキスト用の Sandbox を解決します。Resolver 関数が設定されている場合、指定された requestContext で呼び出します。静的な Sandbox が設定されている場合は、その値を直接返します。Sandbox が設定されていない場合は undefined を返します。

import { RequestContext } from '@mastra/core/request-context'

const ctx = new RequestContext([['user-id', 'alice']])
const sandbox = await workspace.resolveSandbox({ requestContext: ctx })

パラメーター：

requestContext:

RequestContext

Resolver 関数へ渡すリクエストコンテキスト。

戻り値： Promise<WorkspaceSandbox | undefined>

clearSandboxCache(cacheKey?)

sandboxCacheKey でキャッシュされた Resolver ベースの Sandbox を消去します。1つのエントリを消去するにはキャッシュキーを渡し、キー付きの Sandbox エントリをすべて消去するには省略します。

このメソッドは、RequestContext ごとの weak cache を消去しません。これらのエントリはガベージコレクションで管理されます。

Workspace は Resolver が返した Sandbox を所有しません。このメソッドは Workspace の参照だけを破棄します。Sandbox は独自のライフサイクルコードで破棄してください。

workspace.clearSandboxCache('thread-123')
workspace.clearSandboxCache()

パラメーター：

cacheKey?:

string

消去するキャッシュキー。キー付きの Sandbox エントリをすべて消去するには省略します。

戻り値： void

Agent 向け Tool

Workspace は設定内容に基づいて Agent に Tool を提供します。

Filesystem の Tool

Filesystem が設定されている場合に追加されます。

Tool	説明
mastra_workspace_read_file	ファイル内容を読み取ります。テキストファイルはテキストとして返します（任意で行範囲を指定可能）。画像と PDF は、モデルが直接参照できるネイティブメディアパーツとして返します。その他のバイナリは、明示的な encoding を渡さない限りメタデータだけを返します。
mastra_workspace_write_file	新しい内容でファイルを作成または上書きします。親ディレクトリは自動作成されます。
mastra_workspace_edit_file	テキストを検索・置換して既存ファイルを編集します。ファイル全体を書き直さず、対象箇所だけを変更する場合に便利です。
mastra_workspace_list_files	ディレクトリ内容をツリー構造で一覧表示します。深さ制限付きの再帰表示、glob パターン、.gitignore による絞り込み（デフォルトで有効）に対応します。
mastra_workspace_delete	ファイルまたはディレクトリを削除します。ディレクトリの再帰削除に対応します。
mastra_workspace_file_stat	サイズ、種類、更新日時など、ファイルまたはディレクトリのメタデータを取得します。
mastra_workspace_mkdir	ディレクトリを作成します。親ディレクトリが存在しない場合は自動作成されます。
mastra_workspace_grep	正規表現パターンでファイル内容を検索します。glob による絞り込み、コンテキスト行、大文字と小文字を区別しない検索に対応します。

静的な Filesystem が読み取り専用モードの場合、書き込み Tool（write_file、edit_file、delete、mkdir）は除外されます。ランタイム定義の Filesystem では書き込み Tool が常に含まれ、読み取り専用の制限は実行時に適用されます。

read_file Tool は mediaTypes と maxMediaBytes オプションを受け取り、モデルにネイティブメディアパーツとして公開する MIME タイプとファイルサイズの上限を制御します。

mediaTypes?:

string[] | ((mimeType: string) => boolean) | false

= ['image/png', 'image/jpeg', 'image/webp', 'application/pdf']

テキストではなくメディアパーツ（ファイル / 画像パーツ）としてモデルに公開する MIME タイプ。glob の配列（例：['image/*']）、カスタム述語関数、またはメディア検出を無効にする false を指定できます。デフォルトは、複数 Provider で安全に共通利用できる画像形式と PDF です。呼び出し元が明示的な encoding を渡さない場合にのみ適用されます。

maxMediaBytes?:

number

= 10 * 1024 * 1024 (10 MiB)

メディアパーツとしてインライン化する最大ファイルサイズ（バイト）。これより大きいファイルは完全に base64 エンコードしてコンテキストへ追加し、復元時にストレージへ永続化する代わりに、メタデータだけを出力します。

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: {
      // Broaden to any image (including SVG, BMP, HEIC) — may fail on some providers
      mediaTypes: ['image/*'],
      // Raise the inline-media cap to 25 MiB
      maxMediaBytes: 25 * 1024 * 1024,
    },
  },
})

Sandbox の Tool

Sandbox が設定されている場合に追加されます。

Tool	説明
mastra_workspace_execute_command	シェルコマンドを実行し、stdout、stderr、終了コードを返します。Sandbox にプロセスマネージャーがある場合は background: true を指定して長時間稼働するプロセスを起動し、PID を取得できます。
mastra_workspace_get_process_output	PID でバックグラウンドプロセスの stdout、stderr、ステータスを取得します。出力行を制限する tail と、終了まで待機する wait: true を指定できます。Sandbox にプロセスマネージャーがある場合にのみ利用できます。
mastra_workspace_kill_process	PID でバックグラウンドプロセスを終了し、出力の最後の50行を返します。Sandbox にプロセスマネージャーがある場合にのみ利用できます。

静的な Sandbox では、機能チェック（executeCommand、processes）により公開する Tool の種類が決まります。ランタイム定義の Sandbox ではすべての Sandbox Tool が登録され、解決済み Sandbox が要求された機能を実装していない場合は、実行時に明確なエラーをスローします。

execute_command Tool は、バックグラウンドプロセスのライフサイクルコールバック用に backgroundProcesses オプションを受け取ります。

backgroundProcesses?:

BackgroundProcessesConfig

バックグラウンドプロセスを処理するための設定。Sandbox がバックグラウンド実行に対応する場合にのみ適用されます。

BackgroundProcessesConfig

onStdout?:

(data: string, meta: BackgroundProcessMeta) => void

バックグラウンドプロセスの stdout チャンク用コールバック。

onStderr?:

(data: string, meta: BackgroundProcessMeta) => void

バックグラウンドプロセスの stderr チャンク用コールバック。

onExit?:

(meta: BackgroundProcessExitMeta) => void

バックグラウンドプロセス終了時のコールバック。meta には pid、exitCode、stdout、stderr が含まれます。

abortSignal?:

AbortSignal | null | false

バックグラウンドプロセスの中断シグナル。undefined（デフォルト）は Agent のシグナルを使用します。null または false は中断を無効にし、Agent のシャットダウン後もプロセスを維持します。

使用例は、バックグラウンドプロセスのコールバックを参照してください。

検索 Tool

BM25 検索またはベクトル検索が設定されている場合に追加されます。

Tool	説明
mastra_workspace_search	キーワード（BM25）、セマンティック（ベクトル）、またはハイブリッド検索でインデックス化済みの内容を検索します。スコア付きで順位付けした結果を返します。
mastra_workspace_index	検索用に内容をインデックス化します。後から取得できるよう、内容をパスに関連付けます。

Filesystem が読み取り専用モードの場合、index Tool は除外されます。

Skill の Tool

Skill が設定されている場合に追加されます。

Tool	説明
skill	名前またはパスで Skill を有効にします。Skill の完全な指示、リファレンス、スクリプト、アセットを返します。
skill_search	Skill の内容を横断検索します。任意の Skill 名リストによる絞り込みと topK パラメーターを指定できます。
skill_read	Skill ディレクトリから特定のファイル（リファレンス、スクリプト、アセット）を読み取ります。

同名の Skill が複数ある場合、list() はすべてを返します。名前を指定した get() は優先順位（local > managed > external）で選択します。同名かつ同じソース種別の Skill が2つある場合、get() はエラーをスローします。優先順位による選択を避けるには、Skill の完全なパスを get() へ渡します。詳細は、同名の Skillを参照してください。