DocsReferenceWorkflowsWorkflow

Workflow Class

The Workflow class enables you to create state machines for complex sequences of operations with conditional branching and data validation.

import { Workflow } from "@mastra/core/workflows";
 
const workflow = new Workflow({ name: "my-workflow" });

API Reference

Constructor

name:

string
Identifier for the workflow

logger?:

Logger<WorkflowLogMessage>
Optional logger instance for workflow execution details

steps:

Step[]
Array of steps to include in the workflow

triggerSchema:

z.Schema
Optional schema for validating workflow trigger data

Core Methods

step()

Adds a Step to the workflow, including transitions to other steps. Returns the workflow instance for chaining. Learn more about steps.

commit()

Validates and finalizes the workflow configuration. Must be called after adding all steps.

execute()

Executes the workflow with optional trigger data. Typed based on the trigger schema.

Trigger Schemas

Trigger schemas validate the initial data passed to a workflow using Zod.

const workflow = new Workflow({
  name: "order-process",
  triggerSchema: z.object({
    orderId: z.string(),
    customer: z.object({
      id: z.string(),
      email: z.string().email(),
    }),
  }),
});

The schema:

  • Validates data passed to execute()
  • Provides TypeScript types for your workflow input

Validation

Workflow validation happens at two key times:

1. At Commit Time

When you call .commit(), the workflow validates:

workflow
  .step('step1', {...})
  .step('step2', {...})
  .commit(); // Validates workflow structure
  • Circular dependencies between steps
  • Terminal paths (every path must end)
  • Unreachable steps
  • Variable references to non-existent steps
  • Duplicate step IDs

2. During Execution

When you call start(), it validates:

const { runId, start } = workflow.createRun();
 
// Validates trigger data against schema
await start({
  triggerData: {
    orderId: "123",
    customer: {
      id: "cust_123",
      email: "invalid-email", // Will fail validation
    },
  },
});
  • Trigger data against trigger schema
  • Each step’s input data against its inputSchema
  • Variable paths exist in referenced step outputs
  • Required variables are present

Workflow Status

A workflow’s status indicates its current execution state. The possible values are:

CREATED:

string
Workflow instance has been created but not started

RUNNING:

string
Workflow is actively executing steps

SUSPENDED:

string
Workflow execution is paused waiting for resume

COMPLETED:

string
All steps finished executing successfully

FAILED:

string
Workflow encountered an error during execution

Example: Handling Different Statuses

const { runId, start } = workflow.createRun();
 
workflow.watch(runId, async ({ status }) => {
  switch (status) {
    case "SUSPENDED":
      // Handle suspended state
      break;
    case "COMPLETED":
      // Process results
      break;
    case "FAILED":
      // Handle error state
      break;
  }
});
 
await start({ triggerData: data });

Error Handling

try {
  const { runId, start } = workflow.createRun();
  await start({ triggerData: data });
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation errors
    console.log(error.type); // 'circular_dependency' | 'no_terminal_path' | 'unreachable_step'
    console.log(error.details); // { stepId?: string, path?: string[] }
  }
}

Passing Context Between Steps

Steps can access data from previous steps in the workflow through the context object. Each step receives the accumulated context from all previous steps that have executed.

workflow
  .step({
    id: 'getData',
    execute: async ({ context }) => {
      return {
        data: { id: '123', value: 'example' }
      };
    }
  })
  .step({
    id: 'processData',
    execute: async ({ context }) => {
      // Access data from previous step through context.steps
      const previousData = context.steps.getData.output.data;
      // Process previousData.id and previousData.value
    }
  });

The context object:

  • Contains results from all completed steps in context.steps
  • Provides access to step outputs through context.steps.[stepId].output
  • Is typed based on step output schemas
  • Is immutable to ensure data consistency

Related Documentation

stream()Step