Mastra Studio now has an Agent Editor that lets subject matter experts and product teams iterate on agent behavior from Studio, without touching code or redeploying.
Developers define agents in code as usual. The editor stores changes separately with a draft/publish workflow, so you can compare versions, roll back, and keep a full history of your agent's configuration.
Why we built this
Building an agent is only the first step. Once it's running, you need to iterate on it: adjust instructions, add tools, and monitor results. When all of that lives in code, every change goes through the cycle of edit, commit, deploy. That's slow, and it limits who on your team can participate. The people closest to the problem are often not the ones who can make changes to the codebase.
The Editor moves agent configuration into Studio. Make a change, test it, monitor results, publish. No PR review or deploy required.
Combined with datasets, you can run experiments to test changes before publishing, and debug with logs and traces.
Get started
Upgrade to @mastra/core 1.24.0 or later and install the editor package:
1npm install @mastra/editorThen add the editor to your Mastra instance and configure storage:
1// src/mastra/index.ts
2
3import { Mastra } from "@mastra/core";
4import { MastraCompositeStore } from "@mastra/core/storage";
5import { LibSQLStore } from "@mastra/libsql";
6import { MastraEditor } from "@mastra/editor";
7
8export const mastra = new Mastra({
9 // ...
10 storage: new MastraCompositeStore({
11 id: "mastra-storage",
12 default: new LibSQLStore({...}),
13 editor: new LibSQLStore({
14 id: "mastra-editor",
15 url: "file:./editor.db"
16 })
17 }),
18 editor: new MastraEditor(),
19});The editor needs a storage provider to persist version snapshots and configuration changes outside of your codebase. Within MastraCompositeStore, the editor key is its own storage domain, so you can point it at a different database than the rest of your Mastra storage. This example uses LibSQL, but the editor also supports PostgreSQL and MongoDB.
1. Open the Editor in Studio
Once that's in place, open Studio and select an existing code-defined agent to start editing its configuration.
2. Configure tools
Add tools from your project, connect MCP clients to pull in tools from external servers. You can override the tool description from any source to give the agent better context on when and how to use it.
You can also use tools from integration providers like Composio and Arcade.
1//src/mastra/index.ts
2
3import { Mastra } from '@mastra/core'
4import { MastraEditor } from '@mastra/editor'
5import { ComposioToolProvider } from '@mastra/editor/providers/composio'
6
7export const mastra = new Mastra({
8 // ...
9 editor: new MastraEditor({
10 toolProviders: {
11 composio: new ComposioToolProvider({
12 apiKey: process.env.COMPOSIO_API_KEY!,
13 }),
14 },
15 }),
16})3. Instructions and prompt blocks
You can write instructions inline on the agent itself, or pull in prompt blocks. Prompt blocks are created under the Prompts section in Studio and can be shared across multiple agents. Both support Markdown and {{variable}} interpolation, where variables are resolved from requestContext when the agent runs.
4. Save and publish
Click Save to create a draft version. Click Publish to make it live. Once published, the new config applies to any application using the agent.
You can also tag each version with a change message to track what was updated.
Versioning
Every save creates an immutable version snapshot. The agent record tracks which version is published, so you can have multiple drafts without affecting what's live. You can compare changes between versions, browse history, and restore a previous version at any time.
All agent endpoints accept a version parameter. You can pass a versionId or status when calling .generate(), .stream(), or any other agent method:
1// Load the published version (default)
2const agent = mastra.getAgentById("support-agent");
3
4// Load the latest draft
5const agent = mastra.getAgentById("support-agent", {
6 status: "draft",
7});
8
9// Load a specific version
10const agent = mastra.getAgentById("support-agent", {
11 versionId: "abc-123",
12});This makes it straightforward to pin a version per environment, roll back to a known-good config, or run A/B tests by routing different requests to different versions.
Display conditions
Both tools and prompt blocks support display conditions, which are rules evaluated against requestContext when the agent runs. You configure these visually in Studio on each tool or prompt block.
For example, you could restrict a refund tool to admin users by checking requestContext.userRole:
Or conditionally include a prompt block based on request context:
The rules engine supports AND/OR groups with operators like equals, contains, greater_than, in, and exists.
Access control
The Editor is protected by Studio Auth, which locks down both the API endpoints and the Studio UI to authorized users. On top of that, RBAC lets you control what each user can do. For example, you could allow a member to edit agent drafts but only an admin can publish changes.
What you can configure
The editor lets you update instructions, tools, MCP clients, and variables on code-defined agents. Fields like the agent's id, name, and model come from your code and can't be changed through the editor.
Programmatic access
The full editor API is available through mastra.getEditor() and the REST API at /api/stored/agents. The API gives you access to the complete agent configuration surface, including memory, scorers, sub-agents, workflows, and conditional variants on nearly every field. This is useful for CI pipelines or building agent management into your own tooling.
1import { mastra } from "./mastra";
2
3const editor = mastra.getEditor();
4
5// Update an agent's instructions (automatically creates a new draft version)
6await editor.agent.update({
7 id: "support-agent",
8 instructions: "You are a customer support agent. Always greet the customer by name.",
9});Agents can also use the API to update their own or other agents' configuration. An agent could add or remove tools, adjust instructions, or modify display conditions based on what it learns at runtime.
See the MastraEditor class for the method references.
What's next
This is the first iteration of the Editor in Studio. We're shipping it now so we can learn how teams use the feature and what functionality matters most. We'll be rolling out updates in the coming weeks based on that feedback.
Resources
The Editor is available in Studio from 1.24.0. Every change is versioned with draft/publish, rollback, and version comparison. Studio Auth controls who can access the editor and what they can do. The editor is also available programmatically through mastra.getEditor() and the REST API at /api/stored/agents.
For full setup instructions, see the Editor docs.
