@mastra/mcp-docs-server 0.13.37 → 0.13.39-alpha.0

package/.docs/raw/workflows/control-flow.mdx

@@ -1,265 +1,308 @@
 ---
-title: "Branching, Merging, Conditions | Workflows | Mastra Docs"
+title: "Control Flow | Workflows | Mastra Docs"
 description: "Control flow in Mastra workflows allows you to manage branching, merging, and conditions to construct workflows that meet your logic requirements."
 ---
 
 # Control Flow
 
-When you build a workflow, you typically break down operations into smaller tasks that can be linked and reused. **Steps** provide a structured way to manage these tasks by defining inputs, outputs, and execution logic.
+Workflows run a sequence of predefined tasks, and you can control how that flow is executed. Tasks are divided into **steps**, which can be executed in different ways depending on your requirements. They can run sequentially, in parallel, or follow different paths based on conditions.
 
-- If the schemas match, the `outputSchema` from each step is automatically passed to the `inputSchema` of the next step.
-- If the schemas don't match, use [Input data mapping](./input-data-mapping.mdx) to transform the `outputSchema` into the expected `inputSchema`.
+Each step connects to the next in the workflow through defined schemas that keep data controlled and consistent.
+
+## Core principles
+
+- The first step’s `inputSchema` must match the workflow’s `inputSchema`.
+- The final step’s `outputSchema` must match the workflow’s `outputSchema`.
+- Each step’s `outputSchema` must match the next step’s `inputSchema`.
+  - If it doesn’t, use [Input data mapping](#input-data-mapping) to transform the data into the required shape.
 
 ## Chaining steps with `.then()`
 
-Chain steps to execute sequentially using `.then()`:
+Use `.then()` to run steps in order, allowing each step to access the result of the step before it.
 
-![Chaining steps with .then()](/image/workflows/workflows-control-flow-then.jpg)
+![Chaining steps with .then()](/img/workflows/workflows-control-flow-then.jpg)
 
-```typescript {8-9,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+```typescript {30-31} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  //...
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    formatted: z.string()
+  })
+});
 
-const step1 = createStep({...});
-const step2 = createStep({...});
+const step2 = createStep({
+  // ...
+  inputSchema: z.object({
+    formatted: z.string()
+  }),
+  outputSchema: z.object({
+    emphasized: z.string()
+  })
+});
 
-export const testWorkflow = createWorkflow({...})
+export const testWorkflow = createWorkflow({
+  // ...
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    emphasized: z.string()
+  })
+})
   .then(step1)
   .then(step2)
   .commit();
 ```
 
-This does what you'd expect: it executes `step1`, then it executes `step2`.
-
 ## Simultaneous steps with `.parallel()`
 
-Execute steps simultaneously using `.parallel()`:
+Use `.parallel()` to run steps at the same time. Each step's `id` is used when defining a following step's `inputSchema` and becomes the key on the `inputData` object used to access the previous step's values. The outputs of parallel steps can then be referenced or combined by a following step.
 
-![Concurrent steps with .parallel()](/image/workflows/workflows-control-flow-parallel.jpg)
+![Concurrent steps with .parallel()](/img/workflows/workflows-control-flow-parallel.jpg)
 
-```typescript {9,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+```typescript {42} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  id: "step-1",
+  // ...
+});
 
-const step1 = createStep({...});
-const step2 = createStep({...});
-const step3 = createStep({...});
+const step2 = createStep({
+  id: "step-2",
+  // ...
+});
 
-export const testWorkflow = createWorkflow({...})
+const step3 = createStep({
+  id: "step-3",
+  inputSchema: z.object({
+    "step-1": z.object({
+      formatted: z.string()
+    }),
+    "step-2": z.object({
+      emphasized: z.string()
+    })
+  }),
+  outputSchema: z.object({
+    combined: z.string()
+  }),
+  execute: async ({ inputData }) => {
+    const { formatted } = inputData["step-1"];
+    const { emphasized } = inputData["step-2"];
+    return {
+      combined: `${formatted} | ${emphasized}`
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  // ...
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    combined: z.string()
+  })
+})
   .parallel([step1, step2])
   .then(step3)
   .commit();
 ```
 
-This executes `step1` and `step2` concurrently, then continues to `step3` after both complete.
-
-> See [Parallel Execution with Steps](../../examples/workflows/parallel-steps.mdx) for more information.
-
 > 📹 Watch: How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
 
 ## Conditional logic with `.branch()`
 
-Execute steps conditionally using `.branch()`:
+Use `.branch()` to choose which step to run based on a condition. All steps in a branch need the same `inputSchema` and `outputSchema` because branching requires consistent schemas so workflows can follow different paths.
+
+![Conditional branching with .branch()](/img/workflows/workflows-control-flow-branch.jpg)
 
-![Conditional branching with .branch()](/image/workflows/workflows-control-flow-branch.jpg)
+```typescript {33-36} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...})
 
-```typescript {8-11,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+const stepA = createStep({
+  // ...
+  inputSchema: z.object({
+    value: z.number()
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  })
+});
 
-const lessThanStep = createStep({...});
-const greaterThanStep = createStep({...});
+const stepB = createStep({
+  // ...
+  inputSchema: z.object({
+    value: z.number()
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  })
+});
 
-export const testWorkflow = createWorkflow({...})
+export const testWorkflow = createWorkflow({
+  // ...
+  inputSchema: z.object({
+    value: z.number()
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  })
+})
+  .then(step1)
   .branch([
-    [async ({ inputData: { value } }) => value <= 10, lessThanStep],
-    [async ({ inputData: { value } }) => value > 10, greaterThanStep]
+    [async ({ inputData: { value } }) => value > 10, stepA],
+    [async ({ inputData: { value } }) => value <= 10, stepB]
   ])
   .commit();
 ```
 
-Branch conditions are evaluated sequentially, but steps with matching conditions are executed in parallel.
-
-> See [Workflow with Conditional Branching](../../examples/workflows/conditional-branching.mdx) for more information.
-
-## Looping steps
-
-Workflows support two types of loops. When looping a step, or any step-compatible construct like a nested workflow, the initial `inputData` is sourced from the output of the previous step.
+## Input data mapping
 
-To ensure compatibility, the loop’s initial input must either match the shape of the previous step’s output, or be explicitly transformed using the `map` function.
+When using `.then()`, `.parallel()`, or `.branch()`, it is sometimes necessary to transform the output of a previous step to match the input of the next. In these cases you can use `.map()` to access the `inputData` and transform it to create a suitable data shape for the next step.
 
-- Match the shape of the previous step’s output, or
-- Be explicitly transformed using the `map` function.
+![Mapping with .map()](/img/workflows/workflows-data-mapping-map.jpg)
 
-### Repeating with `.dowhile()`
-
-Executes step repeatedly while a condition is true.
-
-![Repeating with .dowhile()](/image/workflows/workflows-control-flow-dowhile.jpg)
-
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const counterStep = createStep({...});
+```typescript {9} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...});
+const step2 = createStep({...});
 
 export const testWorkflow = createWorkflow({...})
-  .dowhile(counterStep, async ({ inputData: { number } }) => number < 10)
+  .then(step1)
+  .map(async ({ inputData }) => {
+    const { foo } = inputData;
+    return {
+      bar: `new ${foo}`,
+    };
+  })
+  .then(step2)
   .commit();
 ```
 
-### Repeating with `.dountil()`
-
-Executes step repeatedly until a condition becomes true.
+The `.map()` method provides additional helper functions for more complex mapping scenarios.
 
-![Repeating with .dountil()](/image/workflows/workflows-control-flow-dountil.jpg)
+**Available helper functions:**
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const counterStep = createStep({...});
-
-export const testWorkflow = createWorkflow({...})
-  .dountil(counterStep, async ({ inputData: { number } }) => number > 10)
-  .commit();
-```
-
-### Loop management
-
-Loop conditions can be implemented in different ways depending on how you want the loop to end. Common patterns include checking values returned in `inputData`, setting a maximum number of iterations, or aborting execution when a limit is reached.
+- [`getStepResult()`](/reference/workflows/workflow-methods/map#using-getstepresult): Access a specific step's full output
+- [`getInitData()`](/reference/workflows/workflow-methods/map#using-getinitdata): Access the workflow's initial input data
+- [`mapVariable()`](/reference/workflows/workflow-methods/map#using-mapvariable): Use declarative object syntax to extract and rename fields
 
-#### Conditional loops
-
-The `inputData` for a loop step is the output of a previous step. Use the values in `inputData` to determine whether the loop should continue or stop.
-
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+## Looping steps
 
-const counterStep = createStep({...});
+Workflows support different looping methods that let you repeat steps until or while a condition is met, or iterate over arrays. Loops can be combined with other control methods like `.then()`.
 
-export const testWorkflow = createWorkflow({...})
-.dountil(nestedWorkflowStep, async ({ inputData: { userResponse } }) => userResponse === "yes")
-.commit();
-```
+### Looping with `.dountil()`
 
-#### Limiting loops
+Use `.dountil()` to run a step repeatedly until a condition becomes true.
 
-The `iterationCount` tracks how many times the loop step has run. You can use this to limit the number of iterations and prevent infinite loops. Combine it with `inputData` values to stop the loop after a set number of attempts.
+![Repeating with .dountil()](/img/workflows/workflows-control-flow-dountil.jpg)
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+```typescript {17} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...});
 
-const counterStep = createStep({...});
+const step2 = createStep({
+  // ...
+  execute: async ({ inputData }) => {
+    const { number } = inputData;
+    return {
+      number: number + 1
+    };
+  }
+});
 
-export const testWorkflow = createWorkflow({...})
-.dountil(nestedWorkflowStep, async ({ inputData: { userResponse, iterationCount } }) => userResponse === "yes" || iterationCount >= 10)
-.commit();
+export const testWorkflow = createWorkflow({
+  // ...
+})
+  .then(step1)
+  .dountil(step2, async ({ inputData: { number } }) => number > 10)
+  .commit();
 ```
 
-#### Aborting loops
+### Looping with `.dowhile()`
 
-Use `iterationCount` to limit how many times a loop runs. If the count exceeds your threshold, throw an error to fail the step and stop the workflow.
+Use `.dowhile()` to run a step repeatedly while a condition remains true.
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+![Repeating with .dowhile()](/img/workflows/workflows-control-flow-dowhile.jpg)
 
-const counterStep = createStep({...});
+```typescript {17} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...});
 
-export const testWorkflow = createWorkflow({...})
-.dountil(nestedWorkflowStep, async ({ inputData: { userResponse, iterationCount } }) => {
-  if (iterationCount >= 10) {
-    throw new Error("Maximum iterations reached");
+const step2 = createStep({
+  // ...
+  execute: async ({ inputData }) => {
+    const { number } = inputData;
+    return {
+      number: number + 1
+    };
   }
-  return userResponse === "yes";
+});
+
+export const testWorkflow = createWorkflow({
+  // ...
 })
-.commit();
+  .then(step1)
+  .dowhile(step2, async ({ inputData: { number } }) => number < 10)
+  .commit();
 ```
 
-### Repeating with `.foreach()`
+### Looping with `.foreach()`
 
-Sequentially executes the same step for each item from the `inputSchema`.
+Use `.foreach()` to run the same step for each item in an array. The input must be of type `array` so the loop can iterate over its values, applying the step’s logic to each one.
 
-![Repeating with .foreach()](/image/workflows/workflows-control-flow-foreach.jpg)
+![Repeating with .foreach()](/img/workflows/workflows-control-flow-foreach.jpg)
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+```typescript {17} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  // ...
+  inputSchema: z.string(),
+  outputSchema: z.string(),
+  execute: async ({ inputData }) => {
+    return inputData.toUpperCase();
+  }
+});
 
-const mapStep = createStep({...});
+const step2 = createStep({...});
 
-export const testWorkflow = createWorkflow({...})
-  .foreach(mapStep)
+export const testWorkflow = createWorkflow({
+  // ...
+  inputSchema: z.array(z.string()),
+  outputSchema: z.array(z.string())
+})
+  .foreach(step1)
+  .then(step2)
   .commit();
 ```
 
-#### Setting concurrency limits
-
-Use `concurrency` to execute steps in parallel with a limit on the number of concurrent executions.
+#### Concurrency limits
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+Use `concurrency` to control the number of array items processed at the same time. The default is `1`, which runs steps sequentially. Increasing the value allows `.foreach()` to process multiple items simultaneously.
 
-const mapStep = createStep({...})
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...})
 
 export const testWorkflow = createWorkflow({...})
-  .foreach(mapStep, { concurrency: 2 })
+  .foreach(step1, { concurrency: 4 })
   .commit();
 ```
 
-## Using a nested workflow
-
-Use a nested workflow as a step by passing it to `.then()`. This runs each of its steps in sequence as part of the parent workflow.
-
-```typescript {4,7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-export const nestedWorkflow = createWorkflow({...})
+## Loop management
 
-export const testWorkflow = createWorkflow({...})
-  .then(nestedWorkflow)
-  .commit();
-```
-
-## Cloning a workflow
+Loop conditions can be implemented in different ways depending on how you want the loop to end. Common patterns include checking values returned in `inputData`, setting a maximum number of iterations, or aborting execution when a limit is reached.
 
-Use `cloneWorkflow` to duplicate an existing workflow. This lets you reuse its structure while overriding parameters like `id`.
+### Aborting loops
 
-```typescript {6,10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep, cloneWorkflow } from "@mastra/core/workflows";
-import { z } from "zod";
+Use `iterationCount` to limit how many times a loop runs. If the count exceeds your threshold, throw an error to fail the step and stop the workflow.
 
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({...});
-const parentWorkflow = createWorkflow({...})
-const clonedWorkflow = cloneWorkflow(parentWorkflow, { id: "cloned-workflow" });
 
 export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .then(clonedWorkflow)
+  .dountil(step1, async ({ inputData: { userResponse, iterationCount } }) => {
+    if (iterationCount >= 10) {
+      throw new Error("Maximum iterations reached");
+    }
+    return userResponse === "yes";
+  })
   .commit();
 ```
-
-## Example Run Instance
-
-The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
-
-```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
-
-const result = await run.start({
-  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]
-});
-```
-
-To execute this run from your terminal:
-
-```bash copy
-npx tsx src/test-workflow.ts
-```

package/.docs/raw/workflows/error-handling.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Error Handling in Workflows | Workflows | Mastra Docs"
+title: "Error Handling | Workflows | Mastra Docs"
 description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
 ---
 
@@ -11,7 +11,7 @@ Mastra provides a built-in retry mechanism for workflows or steps that fail due
 
 You can configure retries at the workflow level, which applies to all steps in the workflow:
 
-```typescript {8-11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {8-11} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -32,7 +32,7 @@ export const testWorkflow = createWorkflow({
 
 You can configure retries for individual steps using the `retries` property. This overrides the workflow-level retry configuration for that specific step:
 
-```typescript {17} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {17} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -57,7 +57,7 @@ const step1 = createStep({
 
 You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
 
-```typescript {15,19,33-34} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {15,19,33-34} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -100,7 +100,7 @@ export const testWorkflow = createWorkflow({
 
 Use `getStepResult()` to inspect a previous step’s results.
 
-```typescript {10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {10} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -123,7 +123,7 @@ const step2 = createStep({
 
 Use `bail()` in a step to exit early with a successful result. This returns the provided payload as the step output and ends workflow execution.
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -145,7 +145,7 @@ export const testWorkflow = createWorkflow({...})
 
 Use `throw new Error()` in a step to exit with an error.
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -167,7 +167,7 @@ export const testWorkflow = createWorkflow({...})
 
 You can monitor workflows for errors using the `watch` method:
 
-```typescript {11} filename="src/test-workflow.ts" showLineNumbers copy
+```typescript {11} title="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "../src/mastra";
 
 const workflow = mastra.getWorkflow("testWorkflow");
@@ -175,19 +175,18 @@ const run = await workflow.createRunAsync();
 
 run.watch((event) => {
   const {
-    payload: { currentStep }
+    payload: { currentStep },
   } = event;
 
   console.log(currentStep?.payload?.status);
 });
-
 ```
 
 ## Monitor errors with `stream()`
 
 You can monitor workflows for errors using `stream`:
 
-```typescript {11} filename="src/test-workflow.ts" showLineNumbers copy
+```typescript {11} title="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "../src/mastra";
 
 const workflow = mastra.getWorkflow("testWorkflow");
@@ -196,18 +195,17 @@ const run = await workflow.createRunAsync();
 
 const stream = await run.stream({
   inputData: {
-    value: "initial data"
-  }
+    value: "initial data",
+  },
 });
 
 for await (const chunk of stream.stream) {
   console.log(chunk.payload.output.stats);
 }
-
 ```
 
 ## Related
 
-- [Control Flow](./control-flow.mdx)
-- [Conditional Branching](./control-flow.mdx#conditional-logic-with-branch)
-- [Running Workflows](../../examples/workflows/running-workflows.mdx)
+- [Control Flow](./control-flow)
+- [Conditional Branching](./control-flow#conditional-logic-with-branch)
+- [Running Workflows](/examples/workflows_legacy/creating-a-workflow)