> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Mastra.addDynamicWorkflow()

> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.

The `.addDynamicWorkflow()` method validates a dynamic 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()`](https://mastra.ai/reference/core/getWorkflow).

See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for a complete setup example and the [dynamic workflow definition reference](https://mastra.ai/reference/workflows/dynamic-workflow-definition) for the accepted fields and graph entries.

## Usage example

```typescript
await mastra.addDynamicWorkflow({
  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** (`DynamicWorkflowGraph`): 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 [`addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows).

## Related

- [Mastra.addDynamicWorkflows()](https://mastra.ai/reference/core/addDynamicWorkflows): Add a dependency-ordered bundle of definitions
- [Mastra.getWorkflow()](https://mastra.ai/reference/core/getWorkflow): Retrieve a registered workflow
- [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows): Set up and use dynamic workflows
- [Dynamic workflow definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition): Definition fields and graph entries