版本控制

Editor 會為已儲存的 Agent 及 prompt block 建立版本。以資料庫為後端的資源使用 draft 和發佈操作；以代碼為後端的 Agent 覆寫則使用確定性檔案及 Git 歷史記錄。

發佈及實驗模式請參閱 Editor 版本控制。

資料庫生命週期

資源記錄會儲存 activeVersionId，個別 snapshot 不會儲存生命週期狀態。

詞彙	含義
最新	最近建立的配置 snapshot
已發佈	activeVersionId 選取的 snapshot
Draft	與 activeVersionId 不同的最新 snapshot，或在沒有使用中版本時的最新 snapshot
歷史版本	其他任何保留的 snapshot

儲存有變更的 snapshot 欄位會建立新的最新版本。儲存相同的 snapshot 欄位或只更改 metadata 不會建立版本。

如果已有使用中版本，建立 draft 不會更改處理已發佈請求的版本。發佈會更新 activeVersionId。還原歷史版本會將其配置複製至新的非使用中 draft。

直接 namespace 方法與 REST API 有一項重要差異。editor.prompt.update() 會建立非使用中 draft；editor.agent.update() 會建立版本並立即將它指派給 activeVersionId。除非啟用 autoPublish，否則已儲存 Agent 的 REST PATCH route 會建立非使用中 draft。

當一般已儲存資源沒有使用中版本時，已發佈解析可改用最新 snapshot。對以代碼定義的 Agent 覆寫，如果在沒有使用中覆寫時要求 status: 'published'，則會傳回原本的代碼 Agent。

代碼來源

使用 source: 'code' 時，使用中的 Agent 覆寫會序列化為 <codePath>/agents/<encodedAgentId>.json 下的確定性 JSON。預設 codePath 是 ./mastra/editor。

初始 Agent 會發佈以建立檔案。其後的伺服器更新預設會建立 draft，並在該版本成為使用中版本時寫入檔案。Git 版本在 Studio 中是唯讀的，並使用 commit 訊息作為變更訊息。預設歷史掃描最多讀取最近 50 個 commit，並略過已剖析 JSON snapshot 沒有變更的連續 commit。

來源選項請參閱 MastraEditor。

選擇 Agent 版本

呼叫 mastra.getAgentById() 而不傳入 selector，會傳回已註冊、以代碼定義的 Agent。傳入 status 或 versionId 可套用已儲存的覆寫。TypeScript 範例請參閱選擇版本。

使用預設伺服器 prefix 時，請在 /api 下以 query parameter 傳入 selector：

Version selection through the API

# Published version
curl http://localhost:4111/api/agents/support-agent

# Latest draft
curl http://localhost:4111/api/agents/support-agent?status=draft

# Exact version
curl http://localhost:4111/api/agents/support-agent?versionId=abc-123

Client SDK 及 React SDK selector 請參閱 Client SDK Agent 參考。

子 Agent 版本控制

版本覆寫會透過 request context 在 supervisor Agent 委派中傳遞。可在三個層級定義 selector：

1. Mastra 實例 versions：每次呼叫的預設值
2. 伺服器 request body versions：加入 request context 的每次請求值
3. 直接 generate() 或 stream() 的 versions：每次呼叫值

項目按 Agent ID 合併。對相同 ID，優先次序為：直接呼叫 > request body 或現有 request context > Mastra 實例預設值。

在 Mastra 實例設定預設值：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: { supervisor, researchAgent, writerAgent },
  editor: new MastraEditor(),
  versions: {
    agents: {
      'research-agent': { status: 'published' },
      'writer-agent': { versionId: 'abc-123' },
    },
  },
})

在直接呼叫時覆寫一個子 Agent：

src/routes/experiment.ts

const result = await supervisor.generate('Research and write about AI safety', {
  versions: {
    agents: {
      'research-agent': { status: 'draft' },
    },
  },
})

或在伺服器 request body 傳入 selector：

Per-request sub-agent versions

curl -X POST http://localhost:4111/api/agents/supervisor/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Research AI safety" }],
    "versions": {
      "agents": {
        "research-agent": { "status": "draft" }
      }
    }
  }'

如果未配置 Editor 或無法解析版本，Mastra 會記錄警告並使用以代碼定義的子 Agent。

已儲存 Agent REST API

Mastra 伺服器的預設 prefix 是 /api。自訂伺服器 prefix 會更改以下路徑。

方法	路徑	描述
GET	/api/stored/agents	列出已儲存的 Agent
POST	/api/stored/agents	建立已儲存的 Agent
GET	/api/stored/agents/:storedAgentId	取得已儲存的 Agent
PATCH	/api/stored/agents/:storedAgentId	更新已儲存的 Agent
DELETE	/api/stored/agents/:storedAgentId	刪除已儲存的 Agent
GET	/api/stored/agents/:storedAgentId/dependents	列出可讀取的依賴項，並計算隱藏的跨 Workspace 引用
POST	/api/stored/agents/:storedAgentId/export	將允許覆寫的欄位匯出為確定性 JSON

Dependents response 會按 id 及 name 列出呼叫者可讀取的 Agent。其 hiddenCount 欄位會計算呼叫者無法讀取的跨 Workspace 引用，但只會在目標 Agent 為公開時進行計算。

版本管理 route 位於 /api/stored/agents/:storedAgentId/versions 下。操作及 Client SDK 方法請參閱版本管理。

Client SDK 提供 listStoredAgents()、createStoredAgent() 及 getStoredAgent()。getStoredAgent(id) 傳回的資源包含更新、刪除、dependents、匯出及版本管理方法。