Workflows in Mastra

Workflows in Mastra help you orchestrate complex sequences of operations with features like branching, parallel execution, resource suspension, and more.

When to use workflows

Most AI applications need more than a single call to a language model. You may want to run multiple steps, conditionally skip certain paths, or even pause execution altogether until you receive user input. Sometimes your agent tool calling is not accurate enough.

Mastra’s workflow system provides:

A standardized way to define steps and link them together.
Support for both simple (linear) and advanced (branching, parallel) paths.
Debugging and observability features to track each workflow run.

Example

To create a workflow, you define one or more steps, link them, and then commit the workflow before starting it.

Typically, you would call an LLM or other service in some way in some step. But for this example, we’ll just double the input value in the first step and increment it in the second.

import { Workflow, Step } from "@mastra/core";
import { z } from "zod";
 
// 1. Define the workflow
const myWorkflow = new Workflow({
  name: "my-workflow",
  triggerSchema: z.object({
    inputValue: z.number(),
  }),
});
 
// 2. Create steps
const stepOne = new Step({
  id: "stepOne",
  execute: async ({ context: { machineContext } }) => ({
    doubledValue: machineContext.triggerData.inputValue * 2
  })
});
 
const stepTwo = new Step({
  id: "stepTwo",
  execute: async ({ context: { machineContext } }) => ({
    incrementedValue: machineContext.stepResults.stepOne.payload.doubledValue + 1
  })
});
 
// 3. Link and commit steps
myWorkflow.step(stepOne).then(stepTwo).commit();
 
// 4. Run the workflow
const { runId, start } = myWorkflow.createRun({ triggerData: { inputValue: 3 } });
 
const result = await start();
console.log("Workflow result:", result.results);

This example shows the essentials: define your workflow, add steps, commit the workflow, then execute it.

Defining Steps

The basic building block of a workflow is a step. Steps are defined using schemas for inputs and outputs, and can fetch prior step results.

Control Flow

Workflows let you define a control flow to chain steps together in with parallel steps, branching paths, and more.

Suspend and Resume

When you need to pause execution for external data, user input, or asynchronous events, Mastra supports suspension at any step, persisting the state of the workflow so you can resume it later.

Observability and Debugging

Mastra workflows automatically log the input and output of each step within a workflow run, allowing you to send this data to your preferred logging, telemetry, or observability tools.

You can:

Track the status of each step (e.g., success, error, or suspended).
Store run-specific metadata for analysis.
Integrate with third-party observability platforms like Datadog or New Relic by forwarding logs.

More Resources

The Workflow Guide in the Guides section is a tutorial that covers the main concepts.
Sequential Steps workflow example
Parallel Steps workflow example
Branching Paths workflow example
Cyclical Dependencies workflow example
Suspend and Resume workflow example

Tools Steps