Skip to main content

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
Direct link to Usage example

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,
    }
  },
})

Define schemas
Direct link to Define schemas

You can define the step's inputSchema and outputSchema with any library that supports Standard JSON Schema. This includes libraries like Zod, Valibot, and ArkType.

src/mastra/workflows/test-workflow.ts
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const step1 = createStep({
  id: 'step-1',
  inputSchema: z.object({
    message: z.string(),
  }),
  outputSchema: z.object({
    formatted: z.string(),
  }),
  execute: async ({ inputData }) => {
    const { message } = inputData

    return {
      formatted: message.toUpperCase(),
    }
  },
})

Creating steps from agents
Direct link to 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
Direct link to Basic agent step

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
Direct link to Agent step with structured output

Pass structuredOutput to have the agent return typed structured data:

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
Direct link to Agent step options

structuredOutput:

{ schema: StandardJSONSchemaV1 }
When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.

onFinish:

(result: AgentResult) => void
Callback invoked when the agent completes generation.

Constructor parameters
Direct link to Constructor parameters

id:

string
Unique identifier for the step

description:

string
Optional description of what the step does

inputSchema:

StandardJSONSchemaV1
Standard JSON Schema defining the input structure

outputSchema:

StandardJSONSchemaV1
Standard JSON Schema defining the output structure

resumeSchema:

StandardJSONSchemaV1
Optional Standard JSON Schema for resuming the step

suspendSchema:

StandardJSONSchemaV1
Optional Standard JSON Schema for suspending the step

stateSchema:

StandardJSONSchemaV1
Optional Standard JSON 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'.

requestContextSchema:

StandardJSONSchemaV1
Standard JSON Schema for validating request context values. When provided, the context is validated before the step's execute() runs, failing the step if validation fails.

execute:

(params: ExecuteParams) => Promise<any>
Async function containing step logic
ExecuteParams

inputData:

z.infer<TStepInput>
The input data matching the inputSchema

resumeData:

z.infer<TResumeSchema>
The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.

suspendData:

z.infer<TSuspendSchema>
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.

mastra:

Mastra
Access to Mastra services (agents, tools, etc.)

getStepResult:

(step: Step | string) => any
Function to access results from other steps

getInitData:

() => any
Function to access the initial input data of the workflow in any step

suspend:

(suspendPayload: any, suspendOptions?: { resumeLabel?: string }) => Promise<void>
Function to pause workflow execution

state:

z.infer<TState>
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.

setState:

(state: z.infer<TState>) => void
Function to set the state of the workflow. Inject via reducer-like pattern, such as 'setState({ ...state, ...newState })'

runId:

string
Current run id

requestContext?:

RequestContext
Request Context for dependency injection and contextual information.

retryCount?:

number
The retry count for this specific step, it automatically increases each time the step is retried

metadata:

Record<string, any>
Optional key-value pairs for storing additional step information. Values must be serializable (no functions, circular references, etc.).
On this page