버전 관리

편집기 버전에는 Agent와 Prompt 블록이 저장되어 있습니다. 데이터베이스 지원 리소스는 초안 및 게시 작업을 사용합니다. 코드 지원 Agent 재정의에서는 결정적 파일과 Git 기록을 사용합니다.

릴리스 및 실험 패턴은 Editor 버전 관리를 참조하세요.

데이터베이스 수명주기

리소스 레코드는 activeVersionId를 저장합니다. 개별 스냅샷은 수명 주기 상태를 저장하지 않습니다.

용어	의미
최신	가장 최근에 생성된 구성 스냅샷
게시됨	activeVersionId가 선택한 스냅샷
초안	최신 스냅샷이 activeVersionId와 다르거나 활성 버전이 없을 때의 최신 스냅샷
이전 버전	그 밖의 보존된 스냅샷
변경된 스냅샷 필드를 저장하면 새로운 최신 버전이 생성됩니다. 동일한 스냅샷 필드를 저장하거나 메타데이터를 변경하는 것만으로는 버전이 생성되지 않습니다.

활성 버전이 있는 경우 초안을 생성해도 게시된 요청을 처리하는 버전은 변경되지 않습니다. 게시하면 activeVersionId가 업데이트됩니다. 이전 버전을 복원하면 해당 구성이 새로운 비활성 초안으로 복사됩니다. 직접 네임스페이스 메서드와 REST API에는 한 가지 중요한 차이점이 있습니다. editor.prompt.update()는 비활성 초안을 생성합니다. editor.agent.update()는 버전을 생성하고 즉시 activeVersionId에 할당합니다. 저장된 Agent의 REST PATCH 경로는 autoPublish가 활성화되지 않은 한 비활성 초안을 생성합니다. 일반 저장 리소스에 활성 버전이 없으면 게시된 상태를 해석할 때 최신 스냅샷으로 대체될 수 있습니다. 코드 정의 Agent 재정의의 경우 활성 재정의 없이 status: 'published'를 요청하면 원래 코드 Agent를 반환합니다.

코드 소스

source: 'code'를 사용하면 활성 Agent 재정의가 <codePath>/agents/<encodedAgentId>.json 아래에 결정적 JSON으로 직렬화됩니다. 기본 codePath는 ./mastra/editor입니다. 파일을 생성하기 위해 초기 Agent가 게시됩니다. 이후 서버 업데이트는 기본적으로 초안을 생성하고 해당 버전이 활성화되면 파일을 작성합니다. Git 버전은 Studio에서 읽기 전용이며 커밋 메시지를 변경 메시지로 사용합니다. 기본 기록 스캔은 최대 50개의 최근 커밋을 읽고 구문 분석된 JSON 스냅샷이 변경되지 않은 연속 커밋을 건너뜁니다.

소스 옵션은 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

Client SDK 및 React SDK 선택자는 Client SDK Agent 레퍼런스를 참조하세요.

하위 Agent 버전 관리

버전 재정의는 요청 컨텍스트에서 Supervisor Agent 위임을 통해 전파됩니다. 선택자는 다음 세 수준에서 정의합니다.

1. Mastra 인스턴스의 versions: 모든 호출의 기본값
2. 서버 요청 본문의 versions: 요청 컨텍스트에 추가되는 요청별 값
3. 직접 호출한 generate() 또는 stream()의 versions: 호출별 값 항목은 Agent ID별로 병합됩니다. 동일한 ID의 우선순위는 직접 호출 > 요청 본문 또는 기존 요청 컨텍스트 > 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' },
    },
  },
})

또는 서버 요청 본문에 선택기를 전달합니다.

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으로 내보냅니다.
종속 항목 응답에는 호출자가 읽을 수 있는 Agent가 id 및 name과 함께 나열됩니다. hiddenCount 필드는 호출자가 읽을 수 없는 Workspace 간 참조 수를 집계하지만, 대상 Agent가 공개 상태일 때만 집계합니다.
버전 관리 경로는 /api/stored/agents/:storedAgentId/versions 아래에 중첩됩니다. 작업 및 Client SDK 메서드는 버전 관리를 참조하세요.
Client SDK는 listStoredAgents(), createStoredAgent(), getStoredAgent()를 노출합니다. getStoredAgent(id)가 반환하는 리소스에는 업데이트, 삭제, 종속 항목, 내보내기 및 버전 관리용 메서드가 포함됩니다.