Skip to main content

Workflow Class

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

Usage example
Direct link to Usage example

src/mastra/workflows/test-workflow.ts
import { createWorkflow } from "@mastra/core/workflows";
import { z } from "zod";

export const workflow = createWorkflow({
  id: "test-workflow",
  inputSchema: z.object({
    value: z.string(),
  }),
  outputSchema: z.object({
    value: z.string(),
  }),
});

Constructor parameters
Direct link to Constructor parameters

id:

string
Unique identifier for the workflow

inputSchema:

z.ZodType<any>
Zod schema defining the input structure for the workflow

outputSchema:

z.ZodType<any>
Zod schema defining the output structure for the workflow

stateSchema?:

z.ZodObject<any>
Optional Zod schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.

options?:

WorkflowOptions
Optional options for the workflow

WorkflowOptions
Direct link to WorkflowOptions

tracingPolicy?:

TracingPolicy
Optional tracing policy for the workflow

validateInputs?:

boolean
= true
Optional flag to determine whether to validate the workflow inputs. This also applies default values from zodSchemas on the workflow/step input/resume data. If input/resume data validation fails on start/resume, the workflow will not start/resume, it throws an error instead. If input data validation fails on a step execution, the step fails, causing the workflow to fail and the error is returned.

shouldPersistSnapshot?:

(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean
= () => true
Optional flag to determine whether to persist the workflow snapshot

Running with initial state
Direct link to Running with initial state

When starting a workflow run, you can pass initialState to set the starting values for the workflow's state:

const run = await workflow.createRun();

const result = await run.start({
  inputData: { value: "hello" },
  initialState: {
    counter: 0,
    items: [],
  },
});

The initialState object should match the structure defined in the workflow's stateSchema. See Workflow State for more details.

Workflow status
Direct link to Workflow status

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

success:

string
All steps finished executing successfully, with a valid result output

failed:

string
Workflow encountered an error during execution, with error details available

suspended:

string
Workflow execution is paused waiting for resume, with suspended step information

tripwire:

string
Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.

Handling tripwire status
Direct link to Handling tripwire status

When a workflow contains an agent step that triggers a tripwire, the workflow returns with status: 'tripwire' and includes tripwire details:

const run = await workflow.createRun();
const result = await run.start({ inputData: { message: "Hello" } });

if (result.status === "tripwire") {
  console.log("Workflow terminated by tripwire:", result.tripwire?.reason);
  console.log("Processor ID:", result.tripwire?.processorId);
  console.log("Retry requested:", result.tripwire?.retry);
}

This is distinct from status: 'failed' which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).