Skip to main content

Agent Builder overview

note

The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. Contact sales for more information.

The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to Mastra.storage, and supports multi-tenant agent workflows with RBAC and channel integrations.

  • Configuration: Toggle UI sections and pin admin-controlled defaults for every new agent.
  • Model policy: Restrict which providers and models the Builder exposes, and pin a default.
  • Memory: Configure the default memory shape for every Builder-created agent.
  • Workspace: Configure the default filesystem, sandbox, and skills workspace for Builder-created agents.
  • Browser: Register browser providers and pin a default browser configuration.
  • Access control: Gate the Builder behind Mastra RBAC roles and permissions.
  • Channels: Connect Builder-created agents to Slack and other channels.
  • Tool providers: Connect Builder-created agents to third-party apps through OAuth-backed tool providers.
  • Skill registries: Browse and install community skills from opt-in registries.
  • Deploying: Swap local primitives for cloud-backed storage, filesystems, and sandboxes.

For building agents entirely in code, see the Agents overview. For editing code-defined agents through Studio, see the Editor overview.

Prerequisites
Direct link to Prerequisites

The Agent Builder requires:

  • An existing Mastra project (Follow the installation guide to set up a new project)
  • Storage: A @mastra/core storage adapter on the Mastra instance. Agents, memory, and workspace state all persist through Mastra.storage.
  • A builder agent: Register a builderAgent created with the createBuilderAgent() factory from @mastra/editor/ee on Mastra.agents. The chat-based editor invokes it through the same Mastra.getAgent(id) lookup as any other agent. Without this registration, the chat-based editor returns 404.
  • Model credentials: createBuilderAgent() uses an OpenAI model by default, which requires OPENAI_API_KEY. To use a different provider, pass a model override to createBuilderAgent({ model }) and set that provider's credentials instead.

Get started
Direct link to Get started

Install @mastra/editor alongside a storage adapter. This example uses @mastra/libsql:

npm install @mastra/editor @mastra/libsql

The example below defines a storage adapter, registers a builder agent, and enables the editor as explained in the prerequisites:

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { MastraEditor } from '@mastra/editor'
import { createBuilderAgent } from '@mastra/editor/ee'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: {
      enabled: true,
      configuration: {
        agent: {
          memory: { observationalMemory: true },
        },
      },
    },
  }),
})

Start Mastra's development server:

npx mastra dev

The Agent Builder is mounted at http://localhost:4111/agent-builder.

Disabling the Builder
Direct link to Disabling the Builder

Set enabled: false to keep the config in place but turn the surface off:

src/mastra/index.ts
new MastraEditor({
  builder: {
    enabled: false,
  },
})

Omitting the builder field has the same effect.

Next steps
Direct link to Next steps

  • Configuration: Toggle Builder surfaces and pin defaults for new agents.
  • Access control: Gate the Builder with authentication and role-based access control.
  • Deploying: Replace local development primitives with production-ready storage, filesystems, and sandboxes.
On this page