Workspace

Workspace 為 Agent 提供檔案系統存取權與指令執行能力。透過 mastra dev 或 mastra build 探索檔案式 Agent 時，Agent 會自動取得預設 Workspace，因此不需額外設定便能讀寫檔案及執行 shell 指令。

本頁說明檔案式慣例。Workspace Provider、Tool、搜尋、生命週期與 Sandbox 詳細資訊請參閱 Workspace。

預設 Workspace

沒有 workspace.ts 時，只要建置流程提供各 Agent 專用的 Workspace 路徑，檔案式 Agent 就會取得預設 Workspace。預設 Workspace 使用：

• 以 Agent bundle 內的 Workspace 目錄為根目錄的 LocalFilesystem。
• 工作目錄相同的 LocalSandbox。

這會自動為 Agent 提供檔案 Tool 與 shell Tool。預設 Workspace 為各 Agent 專用；subagent 的 Workspace 目錄會巢狀放在父 Agent 的 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。常見原因包括：

• 將檔案 Tool 指向其他檔案系統根目錄。
• 在其他 Sandbox Provider 中執行 shell 指令。
• 使用 BM25 或向量搜尋新增 Workspace 搜尋功能。
• 讓多個 Agent 共用一個 Workspace。

Provider 模式與執行階段行為請參閱 Workspace 概觀、Sandbox 指南和 Workspace 搜尋。

執行階段邊界

Workspace 檔案系統控制檔案 Tool 可以讀寫的內容。Sandbox 控制 shell 指令的執行位置。應用程式的執行階段程式碼（包括 tools/ 中的程式碼）仍會在應用程式／server process 中執行，除非明確呼叫 Workspace 或 Sandbox API。

種子檔案

加入 workspace/ 目錄，以包含 Agent 的初始檔案。Mastra 會在建置時將 workspace/ 下的檔案鏡像至 Agent 的預設執行階段 Workspace，讓 Agent 啟動時，這些檔案已存在於磁碟中。

Seed files

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

檔案會複製至 bundle 內的 Workspace 路徑，Workspace 檔案 Tool 與 Sandbox 指令可在該處讀取檔案。鏡像期間會略過 symlink 種子檔案。

與 config 的優先順序

config.workspace 優先於 workspace.ts；否則會使用預設檔案式 Workspace。完整合併表請參閱 config.ts 優先順序。