Skip to main content

Mastra.addStoredWorkflows()

beta

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

The .addStoredWorkflows() method adds a bundle of stored workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.

The whole bundle is validated up front. Members are then registered in dependency order, so a helper is always in place before the workflow that nests it.

addStoredWorkflow() is the single-member case.

Usage example
Direct link to Usage example

await mastra.addStoredWorkflows([
  helperDefinition, // nested by the root — order in the array doesn't matter
  rootDefinition, // graph contains { type: 'workflow', workflowId: helperDefinition.id }
])

Parameters
Direct link to Parameters

defs:

readonly StoredWorkflowGraph[]
The workflow definitions to add. Nested-workflow references may resolve against the live registries or against other members of the same bundle.

Returns
Direct link to Returns

A promise that resolves once every member is validated, registered, and persisted.

Behavior
Direct link to Behavior

  • References resolve against the instance's registries union the bundle's own IDs, so a root may nest a helper introduced in the same call. Registration order is derived from the dependency graph, not the array order.
  • A rejected bundle registers nothing. Duplicate IDs, invalid members, and dependency cycles are detected before anything is mutated, and if registration or persistence fails partway, the in-memory registry is restored to its prior state.
  • Storage writes happen last. A storage-level failure mid-bundle can leave some rows written, but the registry is still rolled back and the orphaned rows are inert until the next boot.
On this page