【Mastra超入門】 Mastra Studio の Editor で、システムプロンプトを GUI から編集してみた

1 はじめに

こんにちは、AI事業本部の内田です。
今回は、Mastraの入門として、GUI上でエージェントのシステムプロンプトの修正を行ってみました。
これによってStudioの画面からも簡単にエージェントの調整が可能になると思います！

1-1 やりたいこと

コードを変えずに、GUI からシステムプロンプトを編集したい

前回の記事 でAgentのシステムプロンプトはinstructionsの文章という形で記載することを解説しました。

この記事では、システムプロンプトをGUI（Studio画面）上で変更して、Agentの調整をしていきたいと思います。

1-2 Editor とは

公式Docsより、

Collaborators can change an agent's instructions and tools in Studio without accessing the codebase or writing code.

コードベースにアクセスしたりコードを記述したりすることなく、Studio上でエージェントの指示（システムプロンプト）やツールを変更できる

機能のことです。

1-3 この記事で分かること

• Mastra Studio の Editor で、システムプロンプトを GUI から編集する方法
• 変更内容の保存先（db 方式と code 方式）の違い
• code 方式では、編集したのに反映されない場面があること（とその理由）

検証したバージョンは次のとおりです。

2 検証方法

2-1 準備

pnpm add @mastra/editor @mastra/libsql

公式ドキュメントより、@mastra/editorのライブラリをインストールする。

src/mastra/index.tsに

import { MastraEditor } from '@mastra/editor';

を追加し、

mastraのインスタンスにeditorを追加します。

2-2 保存先の 2 方式

• db 方式（デフォルト、上記画像の方式）
• code 方式（source: 'code'）

editorモジュールの中に、source:'code', codePath: './mastra/editor'を追加します。

2-3 Agent 側の書き方

前回作成した keigo-agent を、そのまま使います。Editor 用に Agent の定義へ足したものはありません。

// src/mastra/agents/keigo-agent.ts（前回から変更なし）
export const keigoAgent = new Agent({
  id: 'keigo-agent',
  name: 'Keigo Agent',
  instructions: 'あなたはビジネス敬語に直すエージェントです。ユーザーの入力に対して、自然な敬語になるよう回答を出力してください。',
  model: bedrock('jp.anthropic.claude-haiku-4-5-20251001-v1:0'),
})

コードにハードコードした instructions が、Editor で上書きされる元の値になります。

2-4 Studio の Editor タブで編集する

2-4-1 保存先をdb方式にするパターン

変更してSave New Version→Publish を選択します。

実際にAgentのチャット画面から試してみます。

「〜〜見といて」が「ご確認ください」というニュアンスに変更されてます。

Traceの方でもシステムプロンプトが変更されたことが確認できます。

2-4-2 保存先をcode方式にするパターン

code 方式は、変更内容を JSON ファイルとして保存します。Git で管理しやすいのがうれしいところです。

画面下のボタンは Save New Version と Publish ではなく、Save to filesystem になります。

1. 元のシステムプロンプトに、具体例を追記して Save to filesystem を押します。

   追記した内容：「以下、具体例です。見て：ご覧ください」

   すると、src/mastra/public/mastra/editor/agents/keigo-agent.json が作成されました。

   {
     "instructions": [
       {
         "content": "あなたはビジネス敬語に直すエージェントです。ユーザーの入力に対して、自然な敬語になるよう回答を出力してください。\n\n以下、具体例です。\n\n見て：ご覧ください",
         "type": "prompt_block"
       }
     ],
     "integrationTools": {},
     "mcpClients": {},
     "tools": {}
   }
   

   codePath: './mastra/editor' は、プロジェクトのルートではなく src/mastra/public/ を基準に解決されました。「JSON が見つからない」と思ったら、まずこの場所を探してください。

2. 再デプロイなどはせずに、もう一度システムプロンプトを編集します。「自然な敬語になるよう」のあとに「システムプロンプトの具体例を忠実に反映して」を足して、Save to filesystem を押します。

   「Saved to filesystem」と表示され、保存できたように見えます。

   

ここまでは順調です。ところが、この 2 回目の編集が、思わぬ形で反映されていませんでした。

2-5 code 方式: 2 回目の編集が反映されない

先ほどの手順 2 のあと、添付画像の画面は次のようになっていました。

チャットの Trace では、2 回目の編集が system message に入っていました。

{
  "role": "system",
  "content": "あなたはビジネス敬語に直すエージェントです。ユーザーの入力に対して、自然な敬語になるようシステムプロンプトの具体例を忠実に反映して回答を出力してください。\n\n以下、具体例です。\n\n見て：ご覧ください"
}

一方で、JSON ファイルは更新されず、右の Config パネルも古いままです。シークレットウィンドウで開き直しても、Editor タブには新しい文面が出ました。ブラウザではなく、サーバー側に残っているようです。

2-6 なぜ反映されなかったのか

node_modules のソースを読んで、理由を調べました。（@mastra/server と @mastra/core の 1.79.0 時点）

① 1 回目の保存は、自動で Publish される

@mastra/server の stored-agents.js（Agent を新規作成する処理）に、次のコードがありました。

const isCodeSourceEditor = editor?.getSource?.() === "code";
...
if (initialVersion && (autoPublish !== false || isCodeSourceEditor)) await agentsStore.update({
  id,
  activeVersionId: initialVersion.id,
  status: "published"
});

code 方式のときだけ、最初のバージョンが自動で published になります。そのため、1 回目の保存で JSON が作られ、Config にも反映されました。

② 2 回目以降の保存は、下書き（draft）として扱われる

2 回目以降は「更新」の処理になります。更新では、Studio が autoPublish を指定せず、既定値は「有効にしない」です。つまり、新しいバージョンは作られるものの、activeVersionId は切り替わりません。

③ JSON に書かれるのは、published のバージョンだけ

@mastra/core の FilesystemVersionedHelpers には、こう書かれています。

Versions are kept entirely in memory. Only the published snapshot config is persisted to the on-disk JSON file.

実際に JSON を書き出す persistToDisk() も、status が published で activeVersionId があるものだけを対象にしていました。

if (entity.status !== "published" || !entity.activeVersionId) continue;

つまり、下書きのバージョンは dev server のメモリ上にだけ存在します。ファイルには書かれず、dev server を再起動すると消えます。

④ 下書きは、保存するたびに上書きされる

code 方式の更新処理には、直前の下書きを削除する処理もあります。

if (source === "code" && versionCreated && !changeMessage) {
  ...
  if (previousVersion && !isPublishedVersion) await agentsStore.deleteVersion(previousVersion.id);
}

実際、何度か保存したあとにバージョンの一覧を開くと、Save1（Current）と最新の Save5（Saved）の 2 つしかありませんでした。Save2~4 は、保存のたびに削除されていたわけです。

2-7 Publish する手段はあるのか

Studio の画面に、code 方式で下書きを Publish するボタンはありません。Download JSON と Save to filesystem だけです。

過去のバージョン（Save1）を選ぶと、Read-only と表示され、最新の下書きとの差分が見られます。ここにも Publish ボタンは出ませんでした。

公式ドキュメントには、REST API で有効化する方法（POST /stored/agents/:id/versions/:versionId/activate）が載っています。ただし、画面から操作したいという今回の目的には合いません。

3 何がわかったのか（まとめ・所感）

3-1 2方式の比較

3-2 どちらを選ぶか

• GUI から何度も編集したい場合は、db 方式を選ぶのがよさそうです。Publish で確実に反映されます。
• code 方式は、「1 回編集して JSON をダウンロードして Git管理のリポジトリ に入れる」といった使い方なら成立します。ただし 2 回目以降の編集を反映する手段が、Studio の画面にはありません。反映するには REST API か、再デプロイ(JSON をコミットして反映する運用)が必要となります。

3-3 所感

あくまで、バージョン @mastra/editor | 0.16.4 での検証であり、今後変わる可能性はありそうです。

db方式のほうがソースコードへの書き込み権限等を気にしなくてよさそうだなというのと、今回はローカルのSQLiteのDBですが、別途用意するならそれにも対応できそうだなと思いました！

GUI上でどこまでシステムプロンプトを編集する機会があるか、ユースケースは分かりませんが、チューニングがしやすいのは利点かなと思います。

最後に、今回はnode_modulesまで調査を広げ、原因の切り分けを行いましたが、公式ドキュメントしかりnode_modulesなどのライブライのソースを読むことの重要性を感じました。さらに、それが要件に合うのか、合わないのかなど上流の視点も必要だと感じました。

3-4 留意事項

システムプロンプトがどの程度チャットの回答に反映されるかは、厳密には検証していません。この記事で確認したのは、「GUI から編集でき、保存先ごとに反映のされ方が違う」という点です。