Editor

Editor は Mastra Agent 用の CMS のように機能します。共同作業者は、コードベースへアクセスしたりコードを書いたりせず、Studio で Agent の指示と Tool を変更できます。変更を公開する前にテストすることもできます。

Agent のデフォルト値は TypeScript で定義します。Editor はソースコードを更新せず、変更を別に保存します。そのため、開発者がモデル、識別情報、ランタイムを管理したまま、共同作業者が Agent を改善できます。

デプロイ済みの Studio では、ローカル開発環境の外にいる共同作業者も Editor を利用できます。

📹 動画

手順を追った解説は、Mastra Editor ワークショップをご覧ください。

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 で Editor を使用する

Studio で Agents を開き、Agent を選択してから Editor を選択します。共同作業者は、その Agent の Editor 権限に応じて指示と Tool を更新できます。

データベースストレージを使用する場合は、変更をドラフトとして保存すると、本番の Agent に影響を与えずにテストできます。使用する準備ができたらドラフトを公開します。

Instructions

Instructions セクションには、コードで定義された Agent のシステムプロンプトが表示されます。共同作業者はこれを上書きしたり、指示ブロックを追加したりできます。

指示ブロックには、現在のリクエストから値を取り込めます。たとえば、{{userName}} は request context から渡された名前を挿入します。表示条件を使うと、特定の顧客、ロール、機能フラグに対してのみブロックを表示できます。

Prompt block

Prompt block は、複数の Agent で使用できる、保存済みの指示テキストです。Prompts で作成して公開し、Agent の Instructions セクションを開いて Add block を選択します。

たとえば、サポート、返品、注文状況を担当する Agent で、同じ返金ポリシーが必要になる場合があります。ポリシーを Prompt block として保存し、各 Agent に追加します。ポリシーが変わったときは、3つの Agent を編集する代わりに、ブロックを一度更新して公開できます。

Prompt block を変更すると、公開済みバージョンを参照するすべての Agent に更新が反映されます。ドラフトの変更はプレビュー時だけ使用され、ブロックを公開するまで本番の Agent には影響しません。

テンプレート構文、条件、バージョン、API については、Prompt block リファレンスを参照してください。

Tool

Tool を使うと Agent がアクションを実行できます。共同作業者は Editor で利用可能な Tool を選択できますが、Studio で新しい Tool を実装することはできません。Tool を利用できるようにする方法は、その提供元によって異なります。

• Project Tool は、開発者が Mastra プロジェクトで実装して登録する必要があります。
• Integration Tool は、開発者が Composio や Arcade などの Provider を登録すると利用できます。共同作業者は Provider のカタログを閲覧し、個々の Tool を事前にコードへ追加せずに利用できます。
• MCP Tool は、MCP クライアントを設定すると利用できます。アクセス権を持つ共同作業者は Studio でクライアントを作成し、そのサーバーが公開する Tool を選択できます。

Agent の Tools セクションでは、必要な Tool を追加したり、その Agent 用に Tool の説明を書き換えたりできます。説明を具体的にすると、Tool 自体を変更せずに、Agent がいつ使うべきかを理解しやすくなります。

Project Tool

開発者は Mastra インスタンスに Project Tool を登録して 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 の Editor ビューには、コードで設定された Tool も表示されます。

Composio

Composio は GitHub、Slack、Gmail などのサービス向け Tool を提供します。Composio API キーを使って Provider を登録すると、Editor で 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 の作成者に関連付けられた接続を使用します。各呼び出し元の接続を使用する方法は、接続スコープを参照してください。

Arcade

Arcade は、組み込み認証を備えた別の 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 overrideを参照してください。

変更の保存先を選ぶ

Editor は、設定済みデータベースまたはリポジトリ内のファイルに変更を保存できます。

データベースストレージ

データベースがデフォルトです。Editor は Mastra インスタンスに設定されたストレージを使用するため、アプリケーションと Editor で同じバックエンドを共有できます。

Editor データに別のバックエンドを使用するには、MastraCompositeStore の editor オプションを設定します。明示的なルートがないストレージドメインは、引き続き default ストアを使用します。

次の例では、アプリケーションと Editor のデータを別々の 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(),
})

リポジトリファイル

コードソースを使用すると、override をアプリケーションコードとともに保持できます。開発者は Pull Request でファイルをレビューし、アプリケーションと一緒にデプロイできます。

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 override ファイルが1つ作られます。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 のモデル、名前、その他のコード管理フィールドは TypeScript ファイルに残ります。Mastra は JSON を読み込み、Agent の実行時に値を適用します。

共同作業者が Studio で保存すると、ローカルファイルシステムへファイルを書き込むか、ダウンロードできます。ソース管理連携を利用すると、Studio から Pull Request を作成できます。その後は Git がレビューとバージョン履歴を提供します。

ファイルの場所とソースオプションについては、MastraEditorを参照してください。

バージョン管理

データベースを使用する Agent と Prompt block には、ドラフトと公開済みのバージョンがあります。保存するとドラフトが作成され、その間も本番の Agent は公開済みバージョンを使用し続けます。公開するとドラフトが本番に反映されます。古いバージョンを復元すると、公開前にテストできるドラフトが作成されます。

コードを使用する Agent override では、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 テストで2つのバージョンを比較する。
• 全員へ公開する前に、少人数のグループへドラフトを提供する。
• ステージングでは最新のドラフトを使いながら、本番環境は公開済みバージョンに保つ。
• 顧客を特定のバージョンに固定する。

Supervisor が Sub-agent を呼び出す場合も、同じバージョン制御を使用できます。開発者はシステムの他の部分を変更せずに、ドラフトの Sub-agent をテストできます。

バージョン選択、Sub-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 の Agents APIを参照してください。

次のステップ

• MastraEditor リファレンス
• Prompt block リファレンス
• Editor Tool リファレンス
• Editor のバージョン管理リファレンス