Skip to main content

Agent Builder

The Agent Builder provides a UI for creating and operating Mastra agents. It runs inside your Mastra server. Everything persists to Mastra's storage layer, with support for multi-tenant agent workflows, 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.
  • Deployment: 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.

📹 Watch

Watch Mastra Agent Builder overview to see how teams create and configure agents from the UI.

Prerequisites​

The Agent Builder requires:

  • Mastra Enterprise Edition: Production deployments require a valid EE license. Contact sales for more information.

Quickstart​

Run this command to create a new Mastra project with the Agent Builder enabled:

npm create mastra@latest -- --template agent-builder

Afterwards, start Mastra's development server:

npx mastra dev

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

Manual install​

Instructions

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.

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 and registers a builder agent, plus enables the editor as explained in the prerequisites:

TypeScriptsrc/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({ id: 'mastra-storage', 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.

Next steps​