Workflow state
Workflow state lets you share values across steps without passing them through every step's inputSchema and outputSchema. This is useful for tracking progress or accumulating results, or alternatively sharing configuration across the entire workflow.
State vs step input/outputDirect link to State vs step input/output
It's important to understand the difference between state and step input/output:
- Step input/output: Data flows sequentially between steps. Each step receives the previous step's output as its
inputData, and returns an output for the next step. - State: A shared store that all steps can read and update via
stateandsetState. State persists across the entire workflow run, including suspend/resume cycles.
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'
const step1 = createStep({
id: 'step-1',
inputSchema: z.object({ workflowInput: z.string() }),
outputSchema: z.object({ step1Output: z.string() }),
stateSchema: z.object({ sharedCounter: z.number() }),
execute: async ({ inputData, state, setState }) => {
// inputData comes from workflow input or previous step's output
console.log(inputData.workflowInput)
// state is the shared workflow state
console.log(state.sharedCounter)
// Update state for subsequent steps
await setState({ sharedCounter: state.sharedCounter + 1 })
// Return output that flows to next step's inputData
return { step1Output: 'processed' }
},
})
Defining state schemasDirect link to Defining state schemas
Define a stateSchema on both the workflow and individual steps. The workflow's stateSchema is the master schema containing all possible state values, while each step declares only the subset it needs:
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'
const step1 = createStep({
stateSchema: z.object({
processedItems: z.array(z.string()),
}),
execute: async ({ inputData, state, setState }) => {
const { message } = inputData
const { processedItems } = state
await setState({
processedItems: [...processedItems, 'item-1', 'item-2'],
})
return {
formatted: message.toUpperCase(),
}
},
})
const step2 = createStep({
stateSchema: z.object({
metadata: z.object({
processedBy: z.string(),
}),
}),
execute: async ({ inputData, state }) => {
const { formatted } = inputData
const { metadata } = state
return {
emphasized: `${formatted}!! ${metadata.processedBy}`,
}
},
})
export const testWorkflow = createWorkflow({
stateSchema: z.object({
processedItems: z.array(z.string()),
metadata: z.object({
processedBy: z.string(),
}),
}),
})
.then(step1)
.then(step2)
.commit()
Updating stateDirect link to Updating state
Steps write state with setState or updateState.
setState takes the whole state and is validated on its own against the step's stateSchema, so it has to contain every field that schema requires. Keys you leave out keep their current value, and a second call in the same step replaces the first:
execute: async ({ getState, setState }) => {
const state = await getState()
await setState({ ...state, status: 'done' })
return {}
}
On the evented engine, setState instead merges the keys you pass into the state without validating them. A partial state works there, and a second call adds to the first.
updateState takes only the keys that change. It merges them into the state the step sees and validates the merged result, so a partial update is fine, and keys other steps changed stay as they are. A key set to undefined is removed:
execute: async ({ updateState }) => {
await updateState({ status: 'done', count: 1 })
return {}
}
Both return a promise. Await them: the update is applied before the step returns, and a value that fails stateSchema fails the step.
On runs stored with storageVersion: 2, reading state throws. Use await getState(), optionally with top-level keys, to read the state including this step's own updates.
Setting initial stateDirect link to Setting initial state
Pass initialState when starting a workflow run to set the starting values:
const run = await workflow.createRun()
const result = await run.start({
inputData: { message: 'Hello' },
initialState: {
processedItems: [],
metadata: { processedBy: 'system' },
},
})
The initialState object should match the structure defined in the workflow's stateSchema.
State persistence across suspend/resumeDirect link to State persistence across suspend/resume
State automatically persists across suspend and resume cycles. When a workflow suspends and later resumes, all state updates made before the suspension are preserved:
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'
const step1 = createStep({
id: 'step-1',
inputSchema: z.object({}),
outputSchema: z.object({}),
stateSchema: z.object({ count: z.number(), items: z.array(z.string()) }),
resumeSchema: z.object({ proceed: z.boolean() }),
execute: async ({ state, setState, suspend, resumeData }) => {
if (!resumeData) {
// First run: update state and suspend
await setState({ count: state.count + 1, items: [...state.items, 'item-1'] })
await suspend({})
return {}
}
// After resume: state changes are preserved (count: 1, items: ["item-1"])
return {}
},
})
State in nested workflowsDirect link to State in nested workflows
When using nested workflows, state propagates from parent to child. Changes made by the parent workflow before calling a nested workflow are visible to steps inside the nested workflow:
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'
const nestedStep = createStep({
id: 'nested-step',
inputSchema: z.object({}),
outputSchema: z.object({ result: z.string() }),
stateSchema: z.object({ sharedValue: z.string() }),
execute: async ({ state }) => {
// Receives state modified by parent workflow
return { result: `Received: ${state.sharedValue}` }
},
})
const nestedWorkflow = createWorkflow({
id: 'nested-workflow',
inputSchema: z.object({}),
outputSchema: z.object({ result: z.string() }),
stateSchema: z.object({ sharedValue: z.string() }),
})
.then(nestedStep)
.commit()
const parentStep = createStep({
id: 'parent-step',
inputSchema: z.object({}),
outputSchema: z.object({}),
stateSchema: z.object({ sharedValue: z.string() }),
execute: async ({ state, setState }) => {
// Modify state before nested workflow runs
await setState({ sharedValue: 'modified-by-parent' })
return {}
},
})
const parentWorkflow = createWorkflow({
id: 'parent-workflow',
inputSchema: z.object({}),
outputSchema: z.object({ result: z.string() }),
stateSchema: z.object({ sharedValue: z.string() }),
})
.then(parentStep)
.then(nestedWorkflow)
.commit()