MastraEditor 클래스

그만큼MastraEditor클래스는 편집기 시스템을 설정합니다. 그것을 전달MastraPrompt 블록, Agent 코드 재정의, 버전 관리, Tool 제공자와 같은 편집기 기능을 켜는 생성자입니다.

편집기의 기능에 대한 소개는 Editor를 참조하세요.

사용예

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* your agents */},
  editor: new MastraEditor(),
})

생성자 매개변수

logger?:

Logger

Logger 인스턴스입니다. 설정하지 않으면 Mastra 인스턴스의 Logger로 폴백합니다.

toolProviders?:

Record<string, ToolProvider>

= {}

ID를 키로 사용하는 통합 Tool Provider입니다(예: Composio 또는 Arcade). Agent가 편집기를 통해 추가된 타사 Tool을 사용할 수 있게 합니다.

processorProviders?:

Record<string, ProcessorProvider>

= {}

구성 가능한 입력/출력 처리용 프로세서 Provider입니다(예: 조정 또는 토큰 제한). 내장 Provider는 항상 포함됩니다.

filesystems?:

Record<string, FilesystemProvider>

= {}

파일 액세스를 위한 파일 시스템 Provider입니다(예: S3 또는 GCS). 로컬 파일 시스템 Provider는 항상 포함됩니다.

sandboxes?:

Record<string, SandboxProvider>

= {}

코드 실행을 위한 Sandbox Provider입니다(예: E2B). 로컬 Sandbox Provider는 항상 포함됩니다.

blobStores?:

Record<string, BlobStoreProvider>

= {}

바이너리 데이터용 Blob Storage Provider입니다(예: S3). Provider를 지정하지 않으면 Mastra 스토리지의 Blob Store로 폴백합니다.

browsers?:

Record<string, BrowserProvider>

= {}

Agent의 브라우저 액세스를 위한 브라우저 Provider입니다(예: Stagehand). 내장 Provider가 없으므로 builder.features.agent.browser가 활성화된 경우 필수입니다. Provider 인터페이스는 BrowserProvider 레퍼런스를 참조하세요.

builder?:

AgentBuilderOptions

Agent Builder 구성입니다. AgentBuilderOptions 레퍼런스를 참조하세요. Builder를 비활성화하려면 생략하거나 enabled: false로 설정하세요.

source?:

'code' | 'db'

= 'db'

Agent 재정의가 저장되는 위치입니다. 'db'를 사용하면 재정의가 구성된 스토리지 백엔드에 저장되고 Studio에 저장 및 게시 흐름이 표시됩니다. 'code'를 사용하면 재정의가 디스크의 Agent별 JSON 파일로 저장되며(로컬 FilesystemStore를 통해 라우팅됨), Studio에 파일 시스템 작업이 표시됩니다. 차이점은 Editor 스토리지 옵션을 참조하세요.

codePath?:

string

= './mastra/editor/'

'code' 소스가 Agent별 JSON 파일에 사용하는 디렉터리입니다. source가 'code'가 아니면 무시됩니다.

공급자 인터페이스

위의 각 제공자 필드는 제공자 ID로 입력된 레코드를 사용합니다. 구현 형태는 공급자별 참조 페이지를 참조하세요.

• 프로세서 공급자
• 파일 시스템 공급자
• 샌드박스 제공자
• BlobStoreProvider
• 브라우저 제공자

Agent 빌더

builder 필드는 저장된 Agent를 만들고 편집할 수 있는 브라우저 기반 UI인 Agent Builder를 활성화합니다. 다음을 참조하세요.

• Agent 빌더 개요: 개념 및 시작하기
• AgentBuilder옵션: 전체 옵션 스키마.
• BuilderAgentDefaults: 새 Agent에 대해 관리자가 고정한 기본값입니다.
• 빌더.구성.Agent.Model: Model 허용 목록 및 기본 Model입니다.

Builder Agent 등록

Builder UI는 @mastra/editor/ee의 createBuilderAgent() 팩터리로 생성된 Agent에 대해 실행됩니다. 팩터리를 가져와 호출한 후 반환된 Agent를 Mastra 인스턴스의 agents 아래에 등록하세요.

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

export const mastra = new Mastra({
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: { enabled: true },
  }),
})

키 이름(builderAgent)은 관례일 뿐이며 어떤 키든 사용할 수 있습니다. @mastra/editor/ee 하위 경로는 런타임에 Mastra Enterprise Edition 라이선스의 적용을 받습니다. 전체 설정 체크리스트는 Agent Builder 개요를 참조하세요.

네임스페이스

편집기는 다양한 엔터티 유형을 관리하기 위한 네임스페이스를 노출합니다. 모든 Mastra 인스턴스에서 mastra.getEditor()를 사용해 액세스하고 애플리케이션 코드에서 CRUD 메서드를 직접 호출하거나, 내부적으로 해당 메서드를 사용하는 Mastra 서버 경로를 이용하세요. 모든 네임스페이스는 공유 CRUD 기본 클래스를 확장하므로 동일한 create, getById, update, delete, list, listResolved, clearCache 메서드를 노출합니다. 아래의 네임스페이스별 속성 표에는 추가 메서드도 설명되어 있습니다.

agent:

EditorAgentNamespace

저장된 Agent에 대한 CRUD 작업 및 버전 관리입니다. 코드로 정의된 Agent에 저장된 재정의를 적용합니다.

EditorAgentNamespace

create:

(input: StorageCreateAgentInput) => Promise<Agent>

새로운 저장된 Agent를 생성하고 하이드레이션된 Agent 인스턴스를 반환합니다. id, authorId, metadata 및 초기 스냅샷(name, description, instructions, model, tools, memory 등)을 받습니다.

getById:

(id: string, options?: GetByIdOptions) => Promise<Agent | null>

저장된 Agent의 하이드레이션된 Agent 인스턴스를 반환합니다. 특정 버전을 대상으로 하려면 versionId, versionNumber 또는 status("draft" | "published" | "archived")가 포함된 옵션을 전달하세요. 기본 버전 요청은 캐시됩니다.

update:

(input: StorageUpdateAgentInput) => Promise<Agent>

저장된 Agent를 부분적으로 업데이트합니다. 제공된 스냅샷 필드로 버전을 생성하고 activeVersionId에 할당한 후 캐시를 무효화합니다. Memory를 비활성화하려면 memory를 null로 설정하세요.

delete:

(id: string) => Promise<void>

저장된 Agent를 삭제하고 Mastra 런타임 레지스트리에서 제거합니다.

list:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>

선택적 페이지네이션, orderBy, authorId 및 metadata 필터를 사용해 저장된 Agent를 나열합니다. 원시 저장 스냅샷을 반환합니다.

listResolved:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>

list와 동일하지만 참조가 역참조된 완전히 해석된 구성을 반환합니다.

applyStoredOverrides:

(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>

저장된 재정의(instructions, tools, variables)를 적용하도록 코드로 정의된 Agent를 제자리에서 변경합니다. mastra.getAgent()가 내부적으로 호출하므로 직접 호출할 일은 거의 없습니다.

clone:

(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>

기존 Agent를 복제하여 새로운 저장된 Agent를 생성합니다.

clearCache:

(agentId?: string) => void

Agent 하나 또는 모든 Agent의 인메모리 캐시를 지웁니다. 변경 작업 후 자동으로 호출됩니다.

prompt:

EditorPromptNamespace

Prompt 블록에 대한 CRUD 작업입니다. 초안 콘텐츠를 사용해 지시 블록을 해석하는 미리보기 메서드를 포함합니다.

EditorPromptNamespace

create:

(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

새로운 저장된 Prompt 블록을 생성합니다. id, authorId, metadata 및 초기 스냅샷(name, description, content, rules, requestContextSchema)을 받습니다.

getById:

(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>

해석된 Prompt 블록을 반환합니다. 특정 버전이나 상태를 대상으로 하려면 옵션을 전달하세요.

update:

(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

저장된 Prompt 블록을 부분적으로 업데이트합니다. 제공된 스냅샷 필드로 새 초안 버전을 생성합니다.

delete:

(id: string) => Promise<void>

저장된 Prompt 블록을 삭제하고 Mastra 런타임 레지스트리에서 제거합니다.

list:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>

선택적 페이지네이션, orderBy, authorId, metadata 및 status 필터를 사용해 저장된 Prompt 블록을 나열합니다.

listResolved:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>

list와 동일하지만 완전히 해석된 Prompt 블록 콘텐츠를 반환합니다.

preview:

(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>

컨텍스트를 기준으로 지시 블록 배열을 해석하여 템플릿 변수를 렌더링하고 표시 조건을 평가합니다. 참조된 Prompt 블록의 초안 콘텐츠도 포함합니다.

clearCache:

(id?: string) => void

Prompt 블록 하나 또는 모든 Prompt 블록의 인메모리 캐시를 지웁니다.

mcp:

EditorMCPNamespace

저장된 MCP 클라이언트 구성에 대한 CRUD 작업입니다.

EditorMCPNamespace

create:

(input: StorageCreateMCPClientInput) => Promise<MCPClient>

새로운 저장된 MCP 클라이언트를 생성합니다. id, authorId, metadata 및 초기 스냅샷(servers, tool filtering)을 받습니다.

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>

저장된 MCP 클라이언트의 하이드레이션된 MCPClient 인스턴스를 반환합니다.

update:

(input: StorageUpdateMCPClientInput) => Promise<MCPClient>

저장된 MCP 클라이언트를 부분적으로 업데이트하고 캐시를 무효화합니다.

delete:

(id: string) => Promise<void>

저장된 MCP 클라이언트를 삭제하고 Mastra 런타임 레지스트리에서 제거합니다.

list:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>

선택적 페이지네이션과 필터를 사용해 저장된 MCP 클라이언트를 나열합니다.

listResolved:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>

list와 동일하지만 완전히 해석된 MCP 클라이언트 구성을 반환합니다.

clearCache:

(id?: string) => void

MCP 클라이언트 하나 또는 모든 MCP 클라이언트의 인메모리 캐시를 지웁니다.

mcpServer:

EditorMCPServerNamespace

MCP 서버 구성에 대한 CRUD 작업입니다.

EditorMCPServerNamespace

create:

(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>

새로운 저장된 MCP 서버 구성을 생성하고 하이드레이션된 서버 인스턴스를 반환합니다.

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>

지정된 id에 해당하는 하이드레이션된 MCP 서버를 반환합니다.

update:

(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>

저장된 MCP 서버 구성을 부분적으로 업데이트합니다.

delete:

(id: string) => Promise<void>

저장된 MCP 서버 구성을 삭제합니다.

list:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>

저장된 MCP 서버 구성을 나열합니다.

listResolved:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>

list와 동일하지만 완전히 해석된 서버 구성을 반환합니다.

clearCache:

(id?: string) => void

MCP 서버 하나 또는 모든 MCP 서버의 인메모리 캐시를 지웁니다.

scorer:

EditorScorerNamespace

스코어러 구성에 대한 CRUD 작업입니다.

EditorScorerNamespace

create:

(input: StorageCreateScorerInput) => Promise<MastraScorer>

새로운 저장된 스코어러를 생성하고 하이드레이션된 MastraScorer 인스턴스를 반환합니다.

getById:

(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>

지정된 id에 해당하는 하이드레이션된 스코어러를 반환합니다.

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>

저장된 스코어러를 부분적으로 업데이트합니다.

delete:

(id: string) => Promise<void>

저장된 스코어러를 삭제하고 Mastra 런타임 레지스트리에서 제거합니다.

list:

(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>

선택적 페이지네이션과 필터를 사용해 저장된 스코어러를 나열합니다.

listResolved:

(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>

list와 동일하지만 완전히 해석된 스코어러 구성을 반환합니다.

clearCache:

(id?: string) => void

스코어러 하나 또는 모든 스코어러의 인메모리 캐시를 지웁니다.

Agent 네임스페이스 예시

기존 코드 정의 Agent에 대한 저장된 재정의를 만듭니다.

src/scripts/seed-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  instructions: 'You are a friendly support agent for Acme.',
  tools: {
    search_kb: { description: 'Search the Acme knowledge base' },
  },
})

행동 양식

공급자 액세스

getToolProvider(id)

등록된 Tool 제공자를 해당 ID로 반환합니다.

const composio = mastra.getEditor()?.getToolProvider('composio')

getToolProviders()

등록된 모든 Tool 공급자를Record<string, ToolProvider>.

getProcessorProvider(id)

등록된 프로세서 공급자를 해당 ID로 반환합니다.

getProcessorProviders()

등록된 모든 프로세서 공급자를 반환합니다.

getFilesystemProviders()

등록된 모든 파일 시스템 공급자를 반환합니다.

getSandboxProviders()

등록된 모든 샌드박스 공급자를 반환합니다.

getBlobStoreProviders()

등록된 모든 Blob 저장소 공급자를 반환합니다.

원천

getSource()

구성된 소스('code' 또는 'db')를 반환하며, 명시적인 source 없이 편집기를 생성한 경우에는 undefined를 반환합니다.

const source = mastra.getEditor()?.getSource()

보고:'code' | 'db' | undefined

source를 생략하면 getSource()가 undefined를 반환하더라도 Editor는 구성된 데이터베이스 스토리지를 사용합니다. 스토리지 Workflow는 Editor 스토리지 옵션을, 활성화 및 Git 기록 동작은 코드 소스 버전 관리를 참조하세요.