편집자

편집기는 Mastra Agent의 CMS처럼 작동합니다. 공동작업자는 코드베이스에 액세스하거나 코드를 작성하지 않고도 Studio에서 상담사의 지침과 Tool을 변경할 수 있습니다. 변경 사항을 적용하기 전에 테스트할 수 있습니다.

TypeScript는 Agent의 기본값을 정의합니다. 편집기는 소스 코드를 업데이트하는 대신 변경 사항을 별도로 저장하므로 공동 작업자는 Agent를 개선하는 동시에 개발자는 Model, ID 및 런타임에 대한 제어권을 유지할 수 있습니다.

배포된 Studio를 사용하면 로컬 개발 환경 외부의 공동 작업자도 Editor를 사용할 수 있습니다. :::tip[📹 보기]

단계별 안내는 Mastra Editor 워크숍을 시청하세요. :::

편집기를 사용하는 경우

Agent가 코드에 정의되어 있지만 그 동작을 담당하는 사람이 코드베이스를 편집해서는 안 되는 경우 Editor를 사용하세요. 지침이나 Tool이 자주 변경되고 사용자에게 제공하기 전에 테스트해야 할 때 유용합니다. 개발자가 애플리케이션의 모든 변경 사항과 Agent 구성 릴리스를 담당한다면 대신 코드에서 Agent를 구성하세요.

빠른 시작

@mastra/editor를 설치하세요. 이 빠른 시작에서는 Editor 변경 사항을 저장하는 데 LibSQL을 사용합니다.

npm

npm install @mastra/editor @mastra/libsql

pnpm

pnpm add @mastra/editor @mastra/libsql

Yarn

yarn add @mastra/editor @mastra/libsql

Bun

bun add @mastra/editor @mastra/libsql

Mastra 인스턴스에 MastraEditor와 스토리지를 추가하세요. 여기에 표시된 LibSQL 스토어를 추가하는 대신 기존 스토리지를 재사용할 수 있습니다.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  editor: new MastraEditor(),
})

Studio에서 편집기 사용

~ Studio에서 Agents를 열고 Agent를 선택한 다음 Editor를 선택하세요. 공동 작업자는 해당 Agent의 Editor 권한에 따라 지침과 Tool을 업데이트할 수 있습니다. 데이터베이스 스토리지를 사용하면 변경 사항을 초안으로 저장하여 라이브 Agent에 영향을 주지 않고 테스트할 수 있습니다. 사용할 준비가 되면 초안을 게시하세요.

지침

Instructions 섹션에는 코드에 정의된 Agent의 시스템 Prompt가 표시됩니다. 공동 작업자는 이를 재정의하거나 지침 블록을 추가할 수 있습니다. 지침 블록에는 현재 요청의 값을 포함할 수 있습니다. 예를 들어 {{userName}}은 요청 컨텍스트를 통해 제공된 이름을 삽입합니다. 표시 조건을 사용하면 특정 고객, 역할 또는 기능 플래그에 대해서만 블록을 표시할 수 있습니다.

Prompt 블록

Prompt 블록은 둘 이상의 Agent가 사용할 수 있는 저장된 지침 텍스트입니다. Prompts에서 Prompt 블록을 생성하고 게시한 다음, Agent의 Instructions 섹션을 열고 Add block을 선택하세요. 예를 들어 지원 Agent, 반품 Agent, 주문 상태 Agent 모두 동일한 환불 정책이 필요할 수 있습니다. 정책을 Prompt 블록으로 저장하고 각 Agent에 추가합니다. 정책이 변경되면 Agent 3개를 편집하는 대신 블록을 한 번 업데이트하고 게시합니다.

Prompt 블록이 변경되면 게시된 버전을 참조하는 모든 Agent가 업데이트를 받습니다. 초안 변경 사항은 미리 보는 동안에만 사용되므로 블록이 게시될 때까지 라이브 Agent에 영향을 주지 않습니다.

템플릿 구문, 조건, 버전 및 API는 Prompt 블록 레퍼런스를 참조하세요.

Tool

Tool을 사용하면 Agent가 조치를 취할 수 있습니다. 공동작업자는 Editor에서 사용할 수 있는 Tool 중에서 선택하지만 Studio에서 새로운 Tool을 구현할 수는 없습니다. Tool을 사용할 수 있는 방법은 해당 소스에 따라 다릅니다.

• 프로젝트 Tool개발자가 Mastra 프로젝트에 구현하고 등록해야 합니다.
• 통합 Tool개발자가 Composio 또는 Arcade와 같은 공급자를 등록한 후에 사용할 수 있습니다. 그런 다음 공동 작업자는 공급자의 카탈로그를 찾아보고 각 Tool을 코드에 먼저 추가하지 않고도 Tool을 추가할 수 있습니다.
• MCP ToolMCP 클라이언트가 구성되면 사용할 수 있게 됩니다. 액세스 권한이 있는 공동작업자는 Studio에서 클라이언트를 생성한 다음 서버에서 제공하는 Tool 중에서 선택할 수 있습니다.

Agent의 Tools 섹션에서 공동 작업자는 필요한 Tool을 추가하거나 해당 Agent에 맞게 Tool의 설명을 다시 작성할 수 있습니다. 설명이 구체적일수록 Tool 자체를 변경하지 않고도 Agent가 Tool을 언제 사용해야 하는지 더 잘 이해할 수 있습니다.

프로젝트 Tool

개발자는 프로젝트의 Tool을 Mastra 인스턴스에 등록하여 Editor에서 사용할 수 있게 할 수 있습니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { searchOrders } from './tools/search-orders'

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

Studio Tool 선택기에 Tool이 나열됩니다. 공동작업자는 Agent가 Tool 편집을 허용하는 경우 해당 Agent에 이를 추가할 수 있습니다. Agent의 편집기 보기에는 코드에 연결된 Tool도 나열됩니다.

작곡

작곡GitHub, Slack, Gmail과 같은 서비스를 위한 Tool을 제공합니다. Composio API 키로 공급자를 등록하여 편집기에서 Tool 카탈로그를 사용할 수 있도록 합니다.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      composio: new ComposioToolProvider({
        apiKey: process.env.COMPOSIO_API_KEY!,
      }),
    },
  }),
})

Composio Tool ID는 GITHUB_CREATE_ISSUE와 같은 형식입니다. 기본적으로 선택한 Tool은 Agent 작성자와 연결된 커넥션을 사용합니다. 각 호출자의 커넥션을 대신 사용하려면 커넥션 범위를 참조하세요.

아케이드

아케이드인증이 내장된 또 다른 Tool 카탈로그를 제공합니다. Arcade API 키로 등록하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      arcade: new ArcadeToolProvider({
        apiKey: process.env.ARCADE_API_KEY!,
      }),
    },
  }),
})

Arcade Tool ID는 Github.GetRepository 같은 Toolkit.ToolName 형식을 사용합니다.

MCP 클라이언트

공동 작업자는 Studio에서 재사용 가능한 MCP 클라이언트를 생성하고 그 Tool을 Agent에 추가할 수도 있습니다. 저장된 클라이언트는 로컬 stdio 서버를 시작하거나 원격 HTTP 서버에 연결할 수 있습니다. Tool 필터를 사용하면 각 Agent가 해당 서버에서 필요한 Tool만 사용하도록 제한할 수 있습니다. MCP 구성, 조건, 필터링 및 확인 순서는 Editor Tool 레퍼런스를 참조하세요. Provider 옵션은 ToolProvider를 참조하세요.

공동작업자가 편집할 수 있는 항목 결정

기본적으로 공동 작업자는 Agent의 지침을 변경하고 설명을 포함한 Tool을 관리할 수 있습니다. Agent의 id, name, model은 항상 코드에서 가져옵니다. 변경할 수 있는 항목을 제한하려면 Agent의 editor 필드를 사용하세요.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Help customers with Acme products.',
  model: 'openai/gpt-5.6-sol',
  editor: {
    instructions: true,
    tools: {
      description: true,
    },
  },
})

이 Agent를 사용하면 공동작업자는 지침을 변경하고 이미 연결된 Tool의 설명을 개선할 수 있습니다. Tool을 추가하거나 제거할 수 없습니다.

editor 값	공동 작업자가 변경할 수 있는 항목
생략	지침, Tool 및 Tool 설명
false	없음
{ instructions: true }	지침
{ tools: true }	Tool 및 Tool 설명
{ tools: { description: true } }	코드에 이미 추가된 Tool의 설명
Studio에서는 그 밖의 모든 항목이 읽기 전용으로 표시됩니다. 전체 구성은 Editor 재정의를 참조하세요.

변경 사항이 저장되는 위치 선택

편집자는 구성된 데이터베이스에 변경 사항을 저장하거나 저장소에 파일로 저장할 수 있습니다.

데이터베이스 스토리지

데이터베이스 옵션이 기본값입니다. Editor는 Mastra 인스턴스에 구성된 스토리지를 사용하므로 애플리케이션과 Editor가 동일한 백엔드를 공유할 수 있습니다. Editor 데이터에 별도의 백엔드를 사용하려면 MastraCompositeStore의 editor 옵션을 사용하세요. 명시적 경로가 없는 스토리지 도메인은 계속해서 default 스토어를 사용합니다. 다음 예에서는 애플리케이션 및 편집기 데이터를 별도의 LibSQL 파일에 보관합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new MastraCompositeStore({
    id: 'mastra-storage',
    default: new LibSQLStore({
      id: 'app-storage',
      url: 'file:./mastra.db',
    }),
    editor: new LibSQLStore({
      id: 'editor-storage',
      url: 'file:./editor.db',
    }),
  }),
  editor: new MastraEditor(),
})

저장소 파일

코드 소스를 사용하여 애플리케이션 코드와 함께 재정의를 유지합니다. 개발자는 풀 요청의 파일을 검토하고 애플리케이션과 함께 배포할 수 있습니다.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  editor: new MastraEditor({
    source: 'code',
    codePath: './mastra/editor',
  }),
})

이 모드에서는 편집된 Agent마다 JSON 재정의 파일이 하나씩 존재합니다. Editor는 TypeScript를 생성하거나 Agent가 생성된 파일을 변경하지 않습니다. 기본적으로 ID가 support-agent인 Agent에는 다음 파일이 생성됩니다.

mastra/editor/agents/support-agent.json

파일에는 Editor에서 관리하는 부분만 포함되어 있습니다. 예를 들어:

mastra/editor/agents/support-agent.json

{
  "instructions": "Help customers with Acme products and answer in their language.",
  "tools": {
    "searchOrders": {
      "description": "Look up an order by its number"
    }
  }
}

Agent의 Model, 이름 및 기타 코드 소유 필드는 TypeScript 파일에 유지됩니다. Mastra는 JSON을 읽고 Agent가 실행될 때 이러한 값을 적용합니다.

공동작업자가 Studio에 저장할 때 파일을 로컬 파일 시스템에 쓰거나 다운로드할 수 있습니다. 소스 제어 통합을 통해 Studio는 대신 풀 요청을 열 수 있습니다. 그런 다음 Git은 검토 및 버전 기록을 제공합니다.

파일 위치와 소스 옵션은 MastraEditor를 참조하세요.

버전 관리

데이터베이스 지원 Agent와 Prompt 블록은 초안 및 게시된 버전을 사용합니다. 저장하면 라이브 Agent가 게시된 버전을 계속 사용하는 동안 초안이 생성됩니다. 게시하면 초안이 게시됩니다. 이전 버전을 복원하면 공동작업자가 게시하기 전에 테스트할 수 있는 초안이 생성됩니다.

코드 지원 Agent 재정의에서는 JSON 파일과 Git 기록을 사용합니다.

버전을 선택하세요

애플리케이션은 상태(published 또는 draft)나 정확한 버전 ID를 선택할 수 있습니다.

Version selection

const publishedAgent = await mastra.getAgentById('support-agent', {
  status: 'published',
})

const draftAgent = await mastra.getAgentById('support-agent', {
  status: 'draft',
})

const versionedAgent = await mastra.getAgentById('support-agent', {
  versionId: 'abc-123',
})

버전 선택은 다음을 지원합니다.

• A/B 테스트에서 두 버전을 비교합니다.
• 모든 사용자에게 게시하기 전에 소규모 그룹에 초안을 제공합니다.
• 스테이징에서는 최신 초안을 사용하면서 프로덕션은 게시된 버전으로 유지합니다.
• 고객을 특정 버전에 고정합니다. 감독자가 하위 Agent를 호출할 때도 동일한 버전 제어가 적용됩니다. 개발자는 시스템의 나머지 부분을 변경하지 않고도 초안 버전의 하위 Agent를 테스트할 수 있습니다. 버전 선택, 하위 Agent 동작, REST 엔드포인트 및 SDK 메서드에 관한 내용은 Editor 버전 관리 레퍼런스를 참조하세요.

프로그래밍 방식으로 액세스하기

Studio에서 사용할 수 있는 모든 기능은 mastra.getEditor(), REST API 또는 Client SDK를 통해 프로그래밍 방식으로도 사용할 수 있습니다. 이를 사용하여 대량 업데이트를 스크립팅하거나 코드에서 저장된 구성을 초기화하세요. 평가 결과를 기반으로 Agent를 조정하는 자동화에도 활용할 수 있습니다. 애플리케이션 코드에서 Mastra 인스턴스에 접근할 수 있다면 mastra.getEditor()를 호출하세요.

src/scripts/update-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: 'Help customers with Acme products. Reply in their language.',
})

editor.agent.update() 메서드는 새 버전을 즉시 활성화합니다. 실행 중인 Agent를 변경하지 않고 초안을 생성하려면 저장된 Agent REST API 또는 Client SDK를 대신 사용하세요.

Create a draft through the REST API

curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help customers with Acme products. Reply in their language."
  }'

기본 서버 접두사는 /api입니다. 개발자는 서버 구성에서 사용자 지정 접두사를 설정할 수 있습니다. 사용 가능한 작업은 MastraEditor 네임스페이스와 Client SDK Agent API를 참조하세요.

다음 단계

• MastraEditor 참조
• Prompt 블록 참조
• 편집기 Tool 참조
• 편집기 버전 관리 참조