Documentation Index Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt
Use this file to discover all available pages before exploring further.
Overview Steps are the building blocks of workflows. Each step represents a discrete unit of work with typed inputs and outputs, error handling, and suspend/resume capabilities.
Creating Steps createStep (from params) createStep < TStepId , TStateSchema , TInputSchema , TOutputSchema , TResumeSchema , TSuspendSchema , TRequestContextSchema >( params : StepParams ): Step
Creates a step from explicit parameters.
Step configuration Unique identifier for the step
Optional description of what the step does
Zod schema defining the input structure
Zod schema defining the output structure
Zod schema for step-specific state
Zod schema for resume data when step is suspended
Zod schema for suspend data
Zod schema for request context validation
Function that performs the step’s operations
scorers
MastraScorers | DynamicArgument<MastraScorers>
Scorers to evaluate step execution
Number of retry attempts on failure
Additional metadata for the step
A step that can be added to a workflow
createStep (from agent) createStep < TStepId >( agent : Agent < TStepId > , agentOptions ?: AgentStepOptions ): Step < TStepId , unknown , { prompt: string }, { text: string } >
Creates a step from an agent (defaults to { text: string } output).
The agent to wrap as a step
Agent execution options Enable structured output from the agent
scorers
MastraScorers | DynamicArgument<MastraScorers>
Scorers for the step
A step that executes the agent
createStep < TSchemaIn , TSuspend , TResume , TSchemaOut , TContext , TId , TRequestContext >( tool : Tool < TSchemaIn , TSchemaOut , TSuspend , TResume , TContext , TId , TRequestContext > , toolOptions ?: { retries? : number ; scorers ?: MastraScorers ; metadata ?: StepMetadata } ): Step < TId , unknown , TSchemaIn , TSchemaOut , TSuspend , TResume >
Creates a step from a tool.
The tool to wrap as a step
Tool step options scorers
MastraScorers | DynamicArgument<MastraScorers>
Scorers for the step
A step that executes the tool
createStep (from processor) createStep < TProcessorId >( processor : Processor < TProcessorId > ): Step < `processor: ${ TProcessorId } ` , unknown , ProcessorStepInput , ProcessorStepOutput >
Creates a step from a processor.
The processor to wrap as a step. Processor must have at least one processor method (processInput, processInputStep, processOutputStream, processOutputResult, or processOutputStep).
A step that executes the processor
Step Properties Unique identifier for the step
Optional description of the step
Schema for validating input
Schema for validating output
stateSchema
SchemaWithValidation | undefined
Schema for step state
resumeSchema
SchemaWithValidation | undefined
Schema for resume data
suspendSchema
SchemaWithValidation | undefined
Schema for suspend data
requestContextSchema
SchemaWithValidation | undefined
Schema for request context
scorers
MastraScorers | DynamicArgument<MastraScorers> | undefined
Scorers for evaluating execution
Component type (e.g., ‘AGENT’, ‘TOOL’, ‘PROCESSOR’)
Execute Function The execute function is the core of a step. It receives typed inputs and context, performs operations, and returns typed outputs.
Parameters The input data for the step (validated against inputSchema)
Execution context Request context for dependency injection
Function to update workflow state
suspend
(data: TSuspend, options?: SuspendOptions) => void
Function to suspend execution
Data from resume (if step was previously suspended)
tracingContext
ObservabilityContext | undefined
Tracing context for observability
Signal to abort execution
Function to abort execution
Function to write output chunks (for streaming)
Return Value The execute function should return:
The step output (validated against outputSchema)
A Promise that resolves to the output
Suspend and Resume Steps can suspend execution to wait for external events (e.g., user input, webhook, scheduled time).
Suspending execute : async ({ inputData , suspend }) => { // Request user approval suspend ({ approvalId: '123' , timestamp: Date . now () }, { label: 'approval' , resumeLabel: 'approved' }); }
Resuming execute : async ({ inputData , resumeData }) => { if ( resumeData ) { // Execution is resuming from suspension console . log ( 'Resumed with:' , resumeData ); } // Continue execution }
Example import { createStep } from '@mastra/core/workflows' ; import { z } from 'zod' ; // Create a simple step const validateStep = createStep ({ id: 'validate' , description: 'Validate user input' , inputSchema: z . object ({ email: z . string (). email (), age: z . number (). min ( 18 ) }), outputSchema: z . object ({ valid: z . boolean (), message: z . string () }), execute : async ({ inputData }) => { return { valid: true , message: 'Validation passed' }; } }); // Create a step with state const counterStep = createStep ({ id: 'counter' , description: 'Increment counter' , stateSchema: z . object ({ count: z . number () }), inputSchema: z . object ({}), outputSchema: z . object ({ newCount: z . number () }), execute : async ({ state , setState }) => { const newCount = ( state ?. count || 0 ) + 1 ; setState ({ count: newCount }); return { newCount }; } }); // Create a step that can suspend const approvalStep = createStep ({ id: 'approval' , description: 'Wait for approval' , inputSchema: z . object ({ requestId: z . string () }), outputSchema: z . object ({ approved: z . boolean () }), suspendSchema: z . object ({ requestId: z . string () }), resumeSchema: z . object ({ approved: z . boolean () }), execute : async ({ inputData , suspend , resumeData }) => { if ( ! resumeData ) { // First execution - suspend and wait suspend ({ requestId: inputData . requestId }, { label: 'waiting-approval' }); return { approved: false }; } // Resumed after approval return { approved: resumeData . approved }; } });