---
title: Workflow
description: API Reference for Workflow class
---

# Workflow

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

```ts copy
import { Workflow } from "@mastra/core";

const workflow = new Workflow({ name: "my-workflow" });
```

## API Reference

### Constructor

<PropertiesTable
  content={[
    {
      name: "name",
      type: "string",
      description: "Identifier for the workflow",
    },
    {
      name: "logger",
      type: "Logger<WorkflowLogMessage>",
      isOptional: true,
      description: "Optional logger instance for workflow execution details",
    },
    {
      name: "steps",
      type: "Step[]",
      description: "Array of steps to include in the workflow",
    },
    {
      name: "triggerSchema",
      type: "z.Schema",
      description: "Optional schema for validating workflow trigger data",
    },
  ]}
/>

### Core Methods

#### `step()`

Adds a [Step](./step.mdx) to the workflow, including transitions to other steps. Returns the workflow instance for chaining. [Learn more about steps](./step.mdx).

#### `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](./workflow.mdx#trigger-schemas).

## Trigger Schemas

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

```ts showLineNumbers copy
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

## Variables & Data Flow

Variables allow steps to access data from:

- Previous steps' outputs
- Trigger data

Variables payloads are typesafe with fields defined in the [Step](./step.mdx) `inputSchema`.

```ts showLineNumbers copy
workflow
  .step("createOrder", {
    // Access trigger data
    variables: {
      orderId: { stepId: "trigger", path: "orderId" },
    },
  })
  .step("processPayment", {
    variables: {
      // Access previous step's data
      orderStatus: { stepId: "createOrder", path: "status" },
      amount: { stepId: "createOrder", path: "total" },
    },
  });
```

#### Variable Resolution

- Variables are resolved in order of step execution
- Each step can access outputs of all previous steps
- Paths use dot notation for nested data
- Missing or invalid paths throw errors during execution

### Example

```ts showLineNumbers copy
const workflow = new Workflow({
  name: "process-data",
  triggerSchema: z.object({
    items: z.array(
      z.object({
        id: z.number(),
        value: z.number(),
      }),
    ),
  }),
})
  .step("filter", {
    variables: {
      items: { stepId: "trigger", path: "." },
    },
  })
  .step("process", {
    variables: {
      items: { stepId: "filter", path: "filtered.user.name" },
    },
  })
  .commit();
```

## Validation

Workflow validation happens at two key times:

### 1. At Commit Time

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

```ts showLineNumbers copy
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 `execute()`, it validates:

```ts showLineNumbers copy
// Validates trigger data against schema
await workflow.execute({
  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

### Error Handling

```ts showLineNumbers copy
try {
  await workflow.execute(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[] }
  }
}
```

## Related Documentation

- [Step](./step.mdx)
- [Transition](./transition.mdx)
