版本管理

Editor 會對已儲存的 Agent 與提示詞區塊進行版本管理。以資料庫為後端的資源使用草稿及發布操作。以程式碼為後端的 Agent 覆寫則使用確定性的檔案與 Git 歷史記錄。

發布與實驗模式請參閱 Editor 版本管理。

資料庫生命週期

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

詞彙	意義
最新	最近建立的設定快照
已發布	activeVersionId 選取的快照
草稿	與 activeVersionId 不同的最新快照，或不存在作用中版本時的最新快照
歷史版本	其他所有保留的快照

儲存變更過的快照欄位會建立新的最新版本。若儲存相同的快照欄位，或只變更中繼資料，則不會建立版本。

如果有作用中的版本，建立草稿不會變更處理已發布請求的版本。發布會更新 activeVersionId。還原歷史版本時，會將其設定複製到新的非作用中草稿。

直接命名空間方法與 REST API 有一項重要差異。editor.prompt.update() 會建立非作用中草稿。editor.agent.update() 會建立版本，並立即將其指派給 activeVersionId。除非啟用 autoPublish，否則已儲存 Agent 的 REST PATCH 路由會建立非作用中草稿。

若一般已儲存資源沒有作用中版本，已發布版本的解析可以改用最新快照。對程式碼定義的 Agent 覆寫而言，若要求 status: 'published' 但沒有作用中的覆寫，則會傳回原始的程式碼 Agent。

程式碼來源

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

初始 Agent 會發布以建立該檔案。後續的伺服器更新預設會建立草稿，並在該版本生效時寫入檔案。Git 版本在 Studio 中是唯讀的，並使用 commit 訊息作為變更訊息。預設的歷史記錄掃描最多會讀取近期 50 個 commit，並略過解析後 JSON 快照未變更的連續 commit。

來源選項請參閱 MastraEditor。

選取 Agent 版本

呼叫 mastra.getAgentById() 時若未提供選取器，會傳回已註冊且由程式碼定義的 Agent。傳入 status 或 versionId 可套用已儲存的覆寫。TypeScript 範例請參閱選取版本。

使用預設伺服器前綴時，請將選取器以 /api 下的查詢參數傳入：

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

使用者端 SDK 與 React SDK 的選取器請參閱使用者端 SDK Agent 參考文件。

子 Agent 版本管理

版本覆寫會透過 request context，在 supervisor Agent 委派期間傳遞。可在三個層級定義選取器：

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 中傳入選取器：

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 伺服器的預設前綴為 /api。自訂伺服器前綴會變更下列路徑。

方法	路徑	說明
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

相依項目回應會依 id 與 name 列出呼叫者可讀取的 Agent。其 hiddenCount 欄位會計算呼叫者無法讀取的跨 Workspace 參照，但只在目標 Agent 為公開時才會計算。

版本管理路由位於 /api/stored/agents/:storedAgentId/versions 下。操作與使用者端 SDK 方法請參閱版本管理。

使用者端 SDK 提供 listStoredAgents()、createStoredAgent() 與 getStoredAgent()。getStoredAgent(id) 傳回的資源包含更新、刪除、相依項目、匯出及版本管理方法。