Skip to main content

Agent Builder API

The Agent Builder API provides methods to interact with Agent Builder actions on the server. Each action is a workflow exposed under /agent-builder/:actionId/*. The Builder must be enabled on the server via MastraEditor.builder.enabled, with a valid MASTRA_EE_LICENSE in production.

Getting all actions​

Retrieve a record of available Agent Builder actions:

const actions = await mastraClient.getAgentBuilderActions()

Returns a Record<string, WorkflowInfo> keyed by action ID.

Working with a specific action​

Get an instance of a specific action by its ID:

const action = mastraClient.getAgentBuilderAction('create-agent')

Action methods​

details()​

Retrieve metadata about an Agent Builder action:

const info = await action.details()

createRun()​

Create a new run for this action and receive a runId. Use the returned id with startActionRun(), stream(), resume(), or observeStream().

const { runId } = await action.createRun()

You can also pass an explicit runId:

const { runId } = await action.createRun({ runId: 'my-run-id' })

startAsync()​

Start the action and wait for completion. Returns the final AgentBuilderActionResult with success, applied, branchName, message, validationResults, error, errors, and stepResults.

const result = await action.startAsync({
  inputData: { agentName: 'support-bot' },
})

Pass an existing runId as the second argument to start a previously created run:

const { runId } = await action.createRun()
const result = await action.startAsync({ inputData }, runId)

startActionRun()​

Start an existing run without waiting for completion. Returns { message }.

const { runId } = await action.createRun()
await action.startActionRun({ inputData }, runId)

stream()​

Start an existing run and stream progress events as a ReadableStream<{ type, payload }>.

const { runId } = await action.createRun()
const stream = await action.stream({ inputData }, runId)

for await (const event of stream) {
  console.log(event.type, event.payload)
}

resume()​

Resume a suspended step on a run. Returns { message }.

await action.resume({ step: 'review', resumeData: { approved: true } }, runId)

resumeAsync()​

Resume a suspended step and wait for completion. Returns an AgentBuilderActionResult.

const result = await action.resumeAsync({ step: 'review', resumeData: { approved: true } }, runId)

resumeStream()​

Resume a suspended step and stream subsequent events.

const stream = await action.resumeStream({
  runId,
  step: 'review',
  resumeData: { approved: true },
})

observeStream()​

Attach to an existing run, replaying cached events from the beginning, then continuing with live events. Use this to recover after a page refresh or hot reload.

const stream = await action.observeStream({ runId })

observeStreamLegacy()​

Same as observeStream() but uses the legacy streaming endpoint. Prefer observeStream() for new code.

const stream = await action.observeStreamLegacy({ runId })

runs()​

List runs for this action with optional filters.

const runs = await action.runs({ page: 0, perPage: 20 })

Accepts fromDate, toDate, page, perPage, resourceId, and legacy limit/offset.

runById()​

Fetch a specific run by ID. Use fields to limit the returned payload and withNestedWorkflows to skip nested workflow data.

const run = await action.runById(runId, {
  fields: ['result', 'steps'],
  withNestedWorkflows: false,
})

cancelRun()​

Cancel an in-flight run.

await action.cancelRun(runId)

Access control​

The /agent-builder/* routes are gated by the agent-builder permission resource. Calling clients need at minimum agent-builder:read and agent-builder:execute, plus any picker resources the action touches (stored-agents, stored-skills, tools, workflows, memory). See Access control for the full grant list.