Mastra.addStoredWorkflow()

beta

Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.

The .addStoredWorkflow() method validates a stored workflow definition and registers it as a live workflow on the instance, persisting it through the workflowDefinitions storage domain. Once registered, the workflow runs like any other workflow via getWorkflow().

See Stored workflows for a complete setup example and the stored workflow definition reference for the accepted fields and graph entries.

Usage example

await mastra.addStoredWorkflow({
  id: 'greeting-workflow',
  description: 'Returns a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: { message: { type: 'string' } },
    required: ['message'],
  },
  graph: [
    {
      type: 'mapping',
      id: 'create-greeting',
      mapConfig: JSON.stringify({
        message: { template: 'Hello, ${initData.name}!' },
      }),
    },
  ],
})

const run = await mastra.getWorkflow('greeting-workflow').createRun()
const result = await run.start({ inputData: { name: 'Ada' } })

Parameters

def:

StoredWorkflowGraph

The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.

Returns

A promise that resolves once the definition is validated, registered, and persisted.

Behavior

• The definition is fully validated (structure, references, schema flow) before anything is mutated. Agents, tools, and workflows referenced by the graph must already be registered on the instance.
• Adding a definition with an existing ID replaces both the stored definition and the live registration. In-flight runs keep the graph they started with.
• Without a storage adapter that supports the workflowDefinitions domain, the workflow is still validated and registered in memory, but the definition is lost on restart.
• To add a root workflow together with helper workflows it nests, use addStoredWorkflows().

Related

• Mastra.addStoredWorkflows(): Add a dependency-ordered bundle of definitions
• Mastra.getWorkflow(): Retrieve a registered workflow
• Stored workflows: Set up and use stored workflows
• Stored workflow definition: Definition fields and graph entries