Creating Your First Mastra Workflow

Welcome to the first lesson of the "Designing Mastra Workflows" course. In this course, you will learn how to use Mastra to build smart assistants that can automate tasks, such as processing and transforming text.

A workflow in Mastra is a set of steps that process data in a specific order to achieve a goal. For example, you might want to take a string, truncate its content, and return the truncated result. Workflows help you organize and automate these tasks in a clear and reusable way.

By the end of this lesson, you will know how to create a simple workflow that takes a string as input and returns a truncated version of that string.

Before we dive in, let's briefly remind ourselves of a few key concepts:

• Workflow: This is the main structure that defines the sequence of steps to process data.
• Step: Each step is a single action or operation within the workflow, such as truncating text.
• Schema: Schemas define what kind of data goes into and comes out of a workflow or step. They help ensure the data is in the right format.

If any of these terms are new to you, don't worry—we'll see them in action in the next sections.

Let's build a workflow that truncates a string. We'll do this step by step, explaining each part as we go.

First, we need to import the necessary libraries. In most CodeSignal environments, these libraries are already installed, but if you are working on your own device, you may need to install them.

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

• createWorkflow and createStep come from the Mastra library and are used to define workflows and their steps.
• z is from the Zod library, which helps us define and check the structure of our data.

For this lesson, we'll use a simple agent that truncates a string. This agent takes a string as input and returns a truncated string.

const TruncateAgent = {
  generate: async (content: string) => {
    // Simple mock: return the first 20 characters as a "truncated" string
    return content.slice(0, 20) + "...";
  },
};

Note: The .slice(0, 20) method in JavaScript (and TypeScript) safely returns the entire string if it's shorter than 20 characters—it won't throw an error. This means if you pass a string with fewer than 20 characters, you'll get the entire string with "..." added at the end.

Next, we create a step using createStep. This step will use our truncate agent to truncate the string.

const truncateStringStep = createStep({
  id: "truncate-string",
  description: "Truncates the string to the first 20 characters.",
  inputSchema: z.string(),
  outputSchema: z.string(),
  execute: async ({ inputData }) => { 
    const result = await TruncateAgent.generate(inputData);
    return result;
  },
});

• createStep creates a new step with the specified configuration.
• The step has its own id and description.
• inputSchema indicates the step expects a string input.
• outputSchema indicates the step will return a string output.
• The execute function receives the input data, calls the truncate agent, and returns the truncated string.

Now, let's define our workflow using createWorkflow. We'll give it an id, a description, and specify what kind of input and output it expects.

export const TruncateStringWorkflow = createWorkflow({
  id: "truncate-string-workflow",
  description: "Truncates a string to the first 20 characters.",
  inputSchema: z.string(),
  outputSchema: z.string(),
})
  .then(truncateStringStep)
  .commit();

• createWorkflow creates a new workflow with the specified configuration.
• id is a unique name for the workflow.
• description explains what the workflow does.
• inputSchema indicates the workflow expects a string input (the string to be truncated).
• outputSchema indicates the workflow will return a string output (the truncated string).
• .then(truncateStringStep) adds our step to the workflow.
• .commit() finalizes the workflow definition.

Here is the complete workflow definition:

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const TruncateAgent = {
  generate: async (content: string) => {
    // Simple mock: return the first 20 characters as a "truncated" string
    return content.slice(0, 20) + "...";
  },
};

const truncateStringStep = createStep({
  id: "truncate-string",
  description: "Truncates the string to the first 20 characters.",
  inputSchema: z.string(),
  outputSchema: z.string(),
  execute: async ({ inputData }) => { 
    const result = await TruncateAgent.generate(inputData);
    return result;
  },
});

export const TruncateStringWorkflow = createWorkflow({
  id: "truncate-string-workflow",
  description: "Truncates a string to the first 20 characters.",
  inputSchema: z.string(),
  outputSchema: z.string(),
})
  .then(truncateStringStep)
  .commit();

Now, let's see how to run the workflow with some example input and check the output. We'll use the Mastra instance to manage and execute our workflow.

import { Mastra } from "@mastra/core";
import { TruncateStringWorkflow } from "./workflow.js";

export const mastra = new Mastra({
  workflows: { TruncateStringWorkflow },
});

const run = await mastra.getWorkflow("TruncateStringWorkflow").createRunAsync();

const result = await run.start({
  inputData: "This is a long string that should be truncated after 20 characters."
});

console.log(result);

• We create a Mastra instance and register our workflow with it. When we write { TruncateStringWorkflow }, we're using JavaScript shorthand to create an object with the key "TruncateStringWorkflow" and the workflow as its value.
• We retrieve the workflow using getWorkflow("TruncateStringWorkflow"). Important: getWorkflow() uses the registration key (the object key we used when passing the workflow to Mastra), not the workflow's internal id. In this case, the registration key is "TruncateStringWorkflow", while the workflow's internal id is "truncate-string-workflow". These are two different identifiers.
• We create a new run instance using createRunAsync().
• We start the workflow execution with run.start(), passing our input data.
• The result is printed to the console in a formatted JSON structure.

Expected Output:

{
  "outputData": "This is a long strin...",
  "status": "completed"
}

This output shows the truncated string generated by our workflow. In this case, it's just the first 20 characters of the input string, followed by "...".

In this lesson, you learned how to build a simple Mastra workflow that truncates a string. We covered:

• Importing the necessary libraries (createWorkflow, createStep)
• Creating a simple truncate agent
• Defining a step using createStep with input and output schemas
• Creating a workflow using createWorkflow and chaining steps
• Setting up a Mastra instance to manage workflows
• Running the workflow using createRunAsync() and start()

You are now ready to practice these steps on your own. In the next exercises, you'll get hands-on experience building and running Mastra workflows. Good luck!