Workspaces

Workspace 是 Mastra 平台在部署時佈建並交予 Agent 使用的一組執行階段資源。每個環境都有獨立的 Workspace，確保 production 與 staging 互相隔離。

每個 Workspace 都提供兩項功能：

• 一個用於檔案系統儲存的 bucket，由 PlatformFilesystem 封裝。這個 bucket 是按環境劃分的持久儲存空間，Agent 可在不同執行之間讀寫資料。
• 一組按需要提供、用於執行命令的 Sandbox，由 PlatformSandbox 封裝。每個 PlatformSandbox 實例都會在 start() 時佈建專屬的遠端 Sandbox，並在 destroy() 時將其銷毀。Agent 通常會在每個工作階段啟動多個 Sandbox，用它們完成工作後便釋放資源。

Workspace 只屬於單一環境，因此 production 與 staging 不會共用 bucket 或 Sandbox 資源池。平台會管理佈建、驗證及閒置資源清理。

何時佈建 Workspace

新項目預設會啟用 Workspace。建立環境時，平台會自動為該環境佈建 bucket。Sandbox 基礎映像檔會在背景預熱，讓首次 PlatformSandbox 呼叫可以快速啟動。

尚未選擇啟用的現有項目會在 Workspaces 分頁顯示 Enable workspaces 操作。啟用後，系統會為項目中的每個環境佈建 bucket。

如果某個環境佈建失敗（例如 Sandbox Provider 負載過高），Workspaces 分頁會顯示失敗狀態並提供重試選項。環境本身仍會建立，只有 Workspace 在你重試前無法使用。

在程式碼中使用 Workspace

安裝 Provider 套件：

npm

npm install @mastra/platform-workspace

pnpm

pnpm add @mastra/platform-workspace

Yarn

yarn add @mastra/platform-workspace

Bun

bun add @mastra/platform-workspace

將各個 Provider 組合成 Workspace，並向 Mastra 註冊：

src/mastra/workspace.ts

import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

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

PlatformFilesystem 與 PlatformSandbox 會從環境變數讀取設定，因此在平台上毋須傳入任何選項。平台會在部署時注入這些變數。詳情請參閱環境變數。

一個 bucket，多個 Sandbox

PlatformFilesystem 與 PlatformSandbox 的生命週期不同，設計 Agent 時必須留意這一點。

PlatformFilesystem 是環境 bucket 的長期存取介面。 環境中的所有請求、Agent 及 Sandbox 都會讀寫相同的物件儲存空間。除非你明確刪除資料，否則 Agent 寫入的所有內容都可供下一個請求存取。

PlatformSandbox 是用於佈建臨時 Sandbox 的客戶端。 每個 PlatformSandbox 實例都擁有一個遠端 Sandbox：

• start() 會佈建全新的 Sandbox（如果傳入了 sandboxId，則會重新連接）。
• executeCommand() 會在其中執行命令。
• destroy() 會終止 Sandbox。stop() 是它的別名。

傳給 Workspace 的 sandbox 會提供 Agent 在本身請求中使用的 Tool。當 Agent 需要另一個隔離環境時，例如每項工作專用的 Workspace、每位用戶專用的租戶，或不應影響呼叫者 shell 狀態的背景工作，請建立另一個 PlatformSandbox：

src/mastra/tools/run-in-fresh-sandbox.ts

import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}

你亦可以複製已設定的 Sandbox，將其用作一組 Sandbox 的範本，讓複本繼承憑證、環境、網絡隔離及預設值，而毋須重複設定：

const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()

如要了解完整生命週期、檢查點復原、重新連接及複製選項，請參閱 PlatformSandbox 參考資料。

環境變數

每個在設有 Workspace 的平台環境中執行的部署，都會自動收到以下變數：

變數	內容
MASTRA_PLATFORM_ACCESS_TOKEN	由平台發出的 JSON Web Token (JWT)，供 Workspace Provider 用作驗證。Token 的範圍限於該部署所屬的機構及項目。
MASTRA_PROJECT_ID	部署所屬的項目。
MASTRA_ENVIRONMENT_ID	部署所屬的環境，用於選擇平台所使用的 Sandbox 資源池。
MASTRA_PLATFORM_BUCKET_NAME	連接至該環境的 bucket 名稱，用於選擇 PlatformFilesystem 讀寫的 bucket。

這些名稱為保留名稱。如果你的項目明確設定其中任何名稱，將以平台管理的值為準。

本機開發

將四個變數加入 .env 檔案，即可在本機沿用相同的 Provider。你可從項目的 Workspaces 分頁取得項目、環境及 bucket 的值。至於 MASTRA_PLATFORM_ACCESS_TOKEN，請在機構設定頁面的 API Tokens 下建立 sk_ API 金鑰；平台部署則會使用注入的 JWT。

.env

MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

PlatformFilesystem 與 PlatformSandbox 在本機及平台上的行為相同，兩者都會連接至該環境的同一個 bucket 及 Sandbox 資源池。如果你想將生產環境數據隔離，請在本機執行時使用 staging 或 preview 環境的變數。

如要完全離線運作而不連接平台，請在本機組建中將 Provider 換成 LocalFilesystem 及 LocalSandbox。

檢視 Workspace

平台項目的 Workspaces 分頁會按環境顯示：

• bucket 狀態及內容，並提供上載、下載及刪除操作。
• 最近的 Sandbox 工作階段，包括其命令、結束代碼及執行時間。
• 佈建失敗項目，以及 Retry 操作。

另請參閱

• PlatformFilesystem：檔案系統 Provider 的參考資料。
• PlatformSandbox：Sandbox Provider 的參考資料，包括檢查點復原及複製功能。
• 環境：環境如何劃分 Workspace、變數及資料庫。