---
title: "Reference: Step Class | Workflows"
description: Documentation for the Step class in Mastra, which defines individual units of work within a workflow.
packages:
  - "@mastra/core"
---

# Step Class

The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
It can take either a tool or an agent as a parameter to automatically create a step from them.

## Usage example

```typescript title="src/mastra/workflows/test-workflow.ts"
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  id: "step-1",
  description: "passes value from input to output",
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
  execute: async ({ inputData }) => {
    const { value } = inputData;
    return {
      value,
    };
  },
});
```

## Creating steps from agents

You can create a step directly from an agent. The step will use the agent's name as its ID.

### Basic agent step

```typescript title="src/mastra/workflows/test-workflow.ts"
import { testAgent } from "../agents/test-agent";

const agentStep = createStep(testAgent);
// inputSchema: { prompt: string }
// outputSchema: { text: string }
```

### Agent step with structured output

Pass `structuredOutput` to have the agent return typed structured data:

```typescript title="src/mastra/workflows/test-workflow.ts"
const articleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
});

const agentStep = createStep(testAgent, {
  structuredOutput: { schema: articleSchema },
});
// inputSchema: { prompt: string }
// outputSchema: { title: string, summary: string, tags: string[] }
```

### Agent step options

<PropertiesTable
  content={[
    {
      name: "structuredOutput",
      type: "{ schema: z.ZodType<any> }",
      description: "When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.",
      required: false,
    },
    {
      name: "onFinish",
      type: "(result: AgentResult) => void",
      description: "Callback invoked when the agent completes generation.",
      required: false,
    },
  ]}
/>

## Constructor Parameters

<PropertiesTable
  content={[
    {
      name: "id",
      type: "string",
      description: "Unique identifier for the step",
      required: true,
    },
    {
      name: "description",
      type: "string",
      description: "Optional description of what the step does",
      required: false,
    },
    {
      name: "inputSchema",
      type: "z.ZodType<any>",
      description: "Zod schema defining the input structure",
      required: true,
    },
    {
      name: "outputSchema",
      type: "z.ZodType<any>",
      description: "Zod schema defining the output structure",
      required: true,
    },
    {
      name: "resumeSchema",
      type: "z.ZodType<any>",
      description: "Optional Zod schema for resuming the step",
      required: false,
    },
    {
      name: "suspendSchema",
      type: "z.ZodType<any>",
      description: "Optional Zod schema for suspending the step",
      required: false,
    },
    {
      name: "stateSchema",
      type: "z.ZodObject<any>",
      description:
        "Optional Zod schema for the step state. Automatically injected when using Mastra's state system. The stateSchema must be a subset of the workflow's stateSchema. If not specified, type is 'any'.",
      required: false,
    },
    {
      name: "execute",
      type: "(params: ExecuteParams) => Promise<any>",
      description: "Async function containing step logic",
      required: true,
    },
  ]}
/>

### ExecuteParams

<PropertiesTable
  content={[
    {
      name: "inputData",
      type: "z.infer<TStepInput>",
      description: "The input data matching the inputSchema",
    },
    {
      name: "resumeData",
      type: "z.infer<TResumeSchema>",
      description:
        "The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.",
    },
    {
      name: "suspendData",
      type: "z.infer<TSuspendSchema>",
      description:
        "The suspend data that was originally passed to suspend() when the step was suspended. Only exists if the step is being resumed and was previously suspended with data.",
    },
    {
      name: "mastra",
      type: "Mastra",
      description: "Access to Mastra services (agents, tools, etc.)",
    },
    {
      name: "getStepResult",
      type: "(step: Step | string) => any",
      description: "Function to access results from other steps",
    },
    {
      name: "getInitData",
      type: "() => any",
      description:
        "Function to access the initial input data of the workflow in any step",
    },
    {
      name: "suspend",
      type: "(suspendPayload: any, suspendOptions?: { resumeLabel?: string }) => Promise<void>",
      description: "Function to pause workflow execution",
    },
    {
      name: "state",
      type: "z.infer<TState>",
      description:
        "The current workflow state. Contains shared values that persist across all steps and suspend/resume cycles. The structure is defined by the step's stateSchema.",
    },
    {
      name: "setState",
      type: "(state: z.infer<TState>) => void",
      description:
        "Function to set the state of the workflow. Inject via reducer-like pattern, such as 'setState({ ...state, ...newState })'",
    },
    {
      name: "runId",
      type: "string",
      description: "Current run id",
    },
    {
      name: "requestContext",
      type: "RequestContext",
      isOptional: true,
      description:
        "Request Context for dependency injection and contextual information.",
    },
    {
      name: "retryCount",
      type: "number",
      description:
        "The retry count for this specific step, it automatically increases each time the step is retried",
      isOptional: true,
    },
  ]}
/>

## Related

- [Workflow state](/docs/v1/workflows/workflow-state)
- [Control flow](/docs/v1/workflows/control-flow)
- [Using agents and tools](/docs/v1/workflows/agents-and-tools)
