mastra-workflow-creation

ffMathy's avatarfrom ffMathy

Guide for creating Mastra workflows with agent-as-step and tool-as-step patterns. Use this when creating new workflows or workflow steps.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive architectural guide and factory patterns for building Mastra workflows. It enables developers to create sophisticated AI orchestrations by integrating agents and tools as modular steps, managing complex state transitions, and implementing conditional branching for robust agentic applications.

Use Cases

  • Designing multi-agent systems where specialized agents are chained together to solve complex, multi-step tasks using the agent-as-step pattern.
  • Building deterministic automation pipelines by wrapping existing APIs and functions as 'tool-as-step' components for faster and more precise execution.
  • Developing enterprise-grade AI workflows that require precise state management and context sharing across multiple processing stages.
  • Standardizing agent development workflows within a team using factory patterns to ensure code maintainability and architectural consistency.
namemastra-workflow-creation
descriptionGuide for creating Mastra workflows with agent-as-step and tool-as-step patterns. Use this when creating new workflows or workflow steps.

Creating Mastra Workflows

Use the Hey Jarvis factory pattern for creating workflows and leverage modern patterns.

Factory Functions

CRITICAL: ALWAYS use these factories:

  • createWorkflow() - Create workflows
  • createStep() - Create custom steps
  • createAgentStep() - Use agent as step
  • createToolStep() - Use tool as step

All from ../../utils/workflow-factory

Basic Workflow Pattern

import { createWorkflow, createStep } from '../../utils/workflow-factory';
import { z } from 'zod';

const myStep = createStep({
  id: 'my-step',
  description: 'What this step does',
  inputSchema: z.object({ input: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  execute: async ({ context }) => {
    return { result: context.input };
  },
});

export const myWorkflow = createWorkflow({
  id: 'myWorkflow',
  inputSchema: z.object({ input: z.string() }),
  outputSchema: z.object({ result: z.string() }),
}).then(myStep);

Agent-as-Step Pattern

Use existing agents directly as workflow steps:

const weatherStep = createAgentStep({
  id: 'weather-check',
  description: 'Get weather using weather agent',
  agentName: 'weather',
  inputSchema: z.object({ location: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  prompt: ({ context }) => `Get weather for ${context.location}`,
});

Benefits:

  • Leverages existing agent intelligence
  • Consistent with standalone agent behavior
  • Automatic tool access
  • Memory integration

Tool-as-Step Pattern

Use existing tools directly as workflow steps:

const getCurrentWeatherStep = createToolStep({
  id: 'get-current-weather',
  description: 'Get current weather for a city',
  tool: getCurrentWeatherByCity,
  inputSchema: z.object({ location: z.string() }),
  inputTransform: ({ location }) => ({ cityName: location }),
});

Benefits:

  • Direct tool execution (faster)
  • Precise input/output transformation
  • Better for deterministic operations

When to Use Each Pattern

Use Agent-as-Step when:

  • Need natural language processing
  • Require tool calling capabilities
  • Want conversation context
  • Need flexible, intelligent responses

Use Tool-as-Step when:

  • Have deterministic operations
  • Need direct API calls
  • Want precise input/output control
  • Prefer faster execution

Use Custom Steps when:

  • Need complex data transformation
  • Require workflow-specific logic
  • Must combine multiple operations
  • Need conditional branching

Workflow State Management

The One-Step Rule: Only use state for values that need to travel across more than one step.

✅ Use context for immediate data flow (adjacent steps) ✅ Use state for long-distance data sharing (2+ steps away)

// NO state needed - values flow through context
const step1 = createAgentStep()({
  outputSchema: z.object({ result: z.string() }),
});

const step2 = createStep()({
  inputSchema: z.object({ result: z.string() }),  // From step1 context
  execute: async ({ context }) => ({ data: context.result }),
});

export const workflow = createWorkflow({
  // No stateSchema needed
}).then(step1).then(step2);
// State needed - value used multiple steps later
const stateSchema = z.object({
  persistedValue: z.string(),
});

const storeStep = createStep<typeof stateSchema>()({
  execute: async ({ context, workflow }) => {
    workflow.setState({ persistedValue: context.data });
    return {};
  },
});

const useStep = createStep<typeof stateSchema>()({
  execute: async ({ workflow }) => {
    return { data: workflow.state.persistedValue };
  },
});

Workflow Chaining

export const myWorkflow = createWorkflow({
  id: 'myWorkflow',
  inputSchema: z.object({}),
  outputSchema: z.object({}),
})
  .then(step1)
  .then(step2)
  .branch({
    when: ({ context }) => context.shouldBranch,
    thenWorkflow: branchWorkflow,
    elseWorkflow: defaultWorkflow,
  });

What NOT to Do

❌ Never import from @mastra/core/workflows directly ❌ Never store in state what can flow through context ❌ Never create custom steps when agent/tool-as-step works ❌ Never skip input/output schemas