版本控制

Editor 会对已存储 Agent 和 prompt block 进行版本控制。数据库支持的资源使用草稿和发布操作，代码支持的 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 message 作为变更消息。默认历史扫描最多读取最近 50 个 commit，并跳过解析后 JSON 快照没有变化的连续 commit。

有关来源选项，请参阅 MastraEditor。

选择 Agent 版本

调用 mastra.getAgentById() 时不传 selector，会返回已注册的代码定义 Agent。传递 status 或 versionId 可应用已存储覆盖。有关 TypeScript 示例，请参阅选择版本。

使用默认服务器前缀时，将 selector 作为 /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

有关 Client SDK 和 React SDK selector，请参阅 Client SDK Agent 参考。

Sub-agent 版本控制

版本覆盖通过 request context 中的 supervisor-agent 委派传播。可在三个层级定义 selector：

1. Mastra 实例 versions：每次调用的默认值
2. 服务器请求体 versions：添加到 request context 的每请求值
3. 直接调用 generate() 或 stream() 时的 versions：每次调用的值

条目按 Agent ID 合并。对于相同 ID，优先级为：直接调用 > 请求体或现有 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' },
    },
  },
})

为一次直接调用覆盖一个 sub-agent：

src/routes/experiment.ts

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

也可以在服务器请求体中传递 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 会记录警告并使用代码定义的 sub-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

dependents 响应按 id 和 name 列出调用者可读取的 Agent。仅当目标 Agent 为公开状态时，其 hiddenCount 字段才会统计调用者无法读取的跨 Workspace 引用。

版本管理路由嵌套在 /api/stored/agents/:storedAgentId/versions 下。有关操作和 Client SDK 方法，请参阅版本管理。

Client SDK 公开 listStoredAgents()、createStoredAgent() 和 getStoredAgent()。getStoredAgent(id) 返回的资源包含更新、删除、依赖项、导出和版本管理方法。