@mastra/mcp-docs-server 1.0.0-beta.0 → 1.0.0-beta.10

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

@@ -1,5 +1,5 @@
 ---
-title: "Control Flow | Workflows | Mastra Docs"
+title: "Control Flow | Workflows"
 description: "Control flow in Mastra workflows allows you to manage branching, merging, and conditions to construct workflows that meet your logic requirements."
 ---
 
@@ -112,6 +112,70 @@ export const testWorkflow = createWorkflow({
 
 > 📹 Watch: How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
 
+### Output structure
+
+When steps run in parallel, the output is an object where each key is the step's `id` and the value is that step's output. This allows you to access each parallel step's result independently.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  id: "format-step",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ formatted: z.string() }),
+  execute: async ({ inputData }) => ({
+    formatted: inputData.message.toUpperCase()
+  })
+});
+
+const step2 = createStep({
+  id: "count-step",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ count: z.number() }),
+  execute: async ({ inputData }) => ({
+    count: inputData.message.length
+  })
+});
+
+const step3 = createStep({
+  id: "combine-step",
+  // The inputSchema must match the structure of parallel outputs
+  inputSchema: z.object({
+    "format-step": z.object({ formatted: z.string() }),
+    "count-step": z.object({ count: z.number() })
+  }),
+  outputSchema: z.object({ result: z.string() }),
+  execute: async ({ inputData }) => {
+    // Access each parallel step's output by its id
+    const formatted = inputData["format-step"].formatted;
+    const count = inputData["count-step"].count;
+    return {
+      result: `${formatted} (${count} characters)`
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  id: "parallel-output-example",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ result: z.string() })
+})
+  .parallel([step1, step2])
+  .then(step3)
+  .commit();
+
+// When executed with { message: "hello" }
+// The parallel output structure will be:
+// {
+//   "format-step": { formatted: "HELLO" },
+//   "count-step": { count: 5 }
+// }
+```
+
+**Key points:**
+- Each parallel step's output is keyed by its `id`
+- All parallel steps execute simultaneously
+- The next step receives an object containing all parallel step outputs
+- You must define the `inputSchema` of the following step to match this structure
+
 ## Conditional logic with `.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.
@@ -158,6 +222,85 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
+### Output structure
+
+When using conditional branching, only one branch executes based on which condition evaluates to `true` first. The output structure is similar to `.parallel()`, where the result is keyed by the executed step's `id`.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  id: "initial-step",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ value: z.number() }),
+  execute: async ({ inputData }) => inputData
+});
+
+const highValueStep = createStep({
+  id: "high-value-step",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ result: z.string() }),
+  execute: async ({ inputData }) => ({
+    result: `High value: ${inputData.value}`
+  })
+});
+
+const lowValueStep = createStep({
+  id: "low-value-step",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ result: z.string() }),
+  execute: async ({ inputData }) => ({
+    result: `Low value: ${inputData.value}`
+  })
+});
+
+const finalStep = createStep({
+  id: "final-step",
+  // The inputSchema must account for either branch's output
+  inputSchema: z.object({
+    "high-value-step": z.object({ result: z.string() }).optional(),
+    "low-value-step": z.object({ result: z.string() }).optional()
+  }),
+  outputSchema: z.object({ message: z.string() }),
+  execute: async ({ inputData }) => {
+    // Only one branch will have executed
+    const result = inputData["high-value-step"]?.result || 
+                   inputData["low-value-step"]?.result;
+    return { message: result };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  id: "branch-output-example",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ message: z.string() })
+})
+  .then(step1)
+  .branch([
+    [async ({ inputData }) => inputData.value > 10, highValueStep],
+    [async ({ inputData }) => inputData.value <= 10, lowValueStep]
+  ])
+  .then(finalStep)
+  .commit();
+
+// When executed with { value: 15 }
+// Only the high-value-step executes, output structure:
+// {
+//   "high-value-step": { result: "High value: 15" }
+// }
+
+// When executed with { value: 5 }
+// Only the low-value-step executes, output structure:
+// {
+//   "low-value-step": { result: "Low value: 5" }
+// }
+```
+
+**Key points:**
+- Only one branch executes based on condition evaluation order
+- The output is keyed by the executed step's `id`
+- Subsequent steps should handle all possible branch outputs
+- Use optional fields in the `inputSchema` when the next step needs to handle multiple possible branches
+- Conditions are evaluated in the order they're defined
+
 ## Input data mapping
 
 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.
@@ -188,6 +331,43 @@ The `.map()` method provides additional helper functions for more complex mappin
 - [`getInitData()`](/reference/v1/workflows/workflow-methods/map#using-getinitdata): Access the workflow's initial input data
 - [`mapVariable()`](/reference/v1/workflows/workflow-methods/map#using-mapvariable): Use declarative object syntax to extract and rename fields
 
+### Parallel and Branch outputs
+
+When working with `.parallel()` or `.branch()` outputs, you can use `.map()` to transform the data structure before passing it to the next step. This is especially useful when you need to flatten or restructure the output.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+export const testWorkflow = createWorkflow({...})
+  .parallel([step1, step2])
+  .map(async ({ inputData }) => {
+    // Transform the parallel output structure
+    return {
+      combined: `${inputData["step1"].value} - ${inputData["step2"].value}`
+    };
+  })
+  .then(nextStep)
+  .commit();
+```
+
+You can also use the helper functions provided by `.map()`:
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+export const testWorkflow = createWorkflow({...})
+  .branch([
+    [condition1, stepA],
+    [condition2, stepB]
+  ])
+  .map(async ({ inputData, getStepResult }) => {
+    // Access specific step results
+    const stepAResult = getStepResult("stepA");
+    const stepBResult = getStepResult("stepB");
+    
+    // Return the result from whichever branch executed
+    return stepAResult || stepBResult;
+  })
+  .then(nextStep)
+  .commit();
+```
+
 ## Looping steps
 
 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()`.
@@ -306,3 +486,8 @@ export const testWorkflow = createWorkflow({...})
   })
   .commit();
 ```
+
+## Related
+
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)

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

@@ -1,5 +1,5 @@
 ---
-title: "Error Handling | Workflows | Mastra Docs"
+title: "Error Handling | Workflows"
 description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
 ---
 
@@ -187,6 +187,7 @@ for await (const chunk of stream.stream) {
 
 ## Related
 
-- [Control Flow](./control-flow)
-- [Conditional Branching](./control-flow#conditional-logic-with-branch)
-- [Running Workflows](/docs/v1/workflows/overview)
+- [Control Flow](/docs/v1/workflows/control-flow)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Time Travel](/docs/v1/workflows/time-travel)
+- [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)

package/.docs/raw/workflows/human-in-the-loop.mdx

@@ -1,271 +1,218 @@
 ---
-title: "Human-in-the-loop | Workflows | Mastra Docs"
-description: Example of using Mastra to create workflows with multi-turn human/agent interaction points using suspend/resume and dountil methods.
+title: "Human-in-the-loop (HITL) | Workflows"
+description: "Human-in-the-loop workflows in Mastra allow you to pause execution for manual approvals, reviews, or user input before continuing."
 ---
 
-import GithubLink from "@site/src/components/GithubLink";
+# Human-in-the-loop (HITL)
 
-# Human-in-the-loop
+Some workflows need to pause for human input before continuing. When a workflow is [suspended](/docs/v1/workflows/suspend-and-resume#pausing-a-workflow-with-suspend), it can return a message explaining why it paused and what’s needed to proceed. The workflow can then either [resume](#resuming-workflows-with-human-input) or [bail](#handling-human-rejection-with-bail) based on the input received. This approach works well for manual approvals, rejections, gated decisions, or any step that requires human oversight.
 
-Human-in-the-loop workflows enable ongoing interaction between humans and AI agents, allowing for complex decision-making processes that require multiple rounds of input and response. These workflows can suspend execution at specific points, wait for human input, and continue processing based on the responses received.
+## Pausing workflows for human input
 
-In this example, the multi-turn workflow is used to create a Heads Up game that demonstrates how to create interactive workflows using suspend/resume functionality and conditional logic with `dountil` to repeat a workflow step until a specific condition is met.
+Human-in-the-loop input works much like [pausing a workflow](/docs/v1/workflows/suspend-and-resume) using `suspend()`. The key difference is that when human input is required, you can return `suspend()` with a payload that provides context or guidance to the user on how to continue.
 
-This example consists of three main components:
+![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
 
-1. A [**Famous Person Agent**](#famous-person-agent) that generates a famous person's name.
-2. A [**Game Agent**](#game-agent) that handles the gameplay.
-3. A [**Multi-Turn Workflow**](#multi-turn-workflow) that orchestrates the interaction.
+```typescript {12-17,22-26} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
 
-## Prerequisites
+const step1 = createStep({
+  id: "step-1",
+  inputSchema: z.object({
+    userEmail: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { userEmail } = inputData;
+    const { approved } = resumeData ?? {};
 
-This example uses the `openai` model. Make sure to add the following to your `.env` file:
+    if (!approved) {
+      return await suspend({
+        reason: "Human approval required."
+      });
+    }
 
-```bash title=".env" copy
-OPENAI_API_KEY=<your-api-key>
-```
+    return {
+      output: `Email sent to ${userEmail}`
+    };
+  }
+});
 
-## Famous person agent
-
-The `famousPersonAgent` generates a unique name each time the game is played, using semantic memory to avoid repeating suggestions.
-
-```typescript title="src/mastra/agents/example-famous-person-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLVector } from "@mastra/libsql";
-
-export const famousPersonAgent = new Agent({
-  id: "famous-person-generator",
-  name: "Famous Person Generator",
-  instructions: `You are a famous person generator for a "Heads Up" guessing game.
-
-Generate the name of a well-known famous person who:
-- Is recognizable to most people
-- Has distinctive characteristics that can be described with yes/no questions
-- Is appropriate for all audiences
-- Has a clear, unambiguous name
-
-IMPORTANT: Use your memory to check what famous people you've already suggested and NEVER repeat a person you've already suggested.
-
-Examples: Albert Einstein, Beyoncé, Leonardo da Vinci, Oprah Winfrey, Michael Jordan
-
-Return only the person's name, nothing else.`,
-  model: openai("gpt-4o"),
-  memory: new Memory({
-    vector: new LibSQLVector({
-      id: 'workflow-vector',
-      connectionUrl: "file:../mastra.db",
-    }),
-    embedder: openai.embedding("text-embedding-3-small"),
-    options: {
-      lastMessages: 5,
-      semanticRecall: {
-        topK: 10,
-        messageRange: 1,
-      },
-    },
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: z.object({
+    userEmail: z.string()
   }),
-});
+  outputSchema: z.object({
+    output: z.string()
+  })
+})
+  .then(step1)
+  .commit();
 ```
 
-> See [Agent](/reference/v1/agents/agent) for a full list of configuration options.
+## Providing user feedback
+
+When a workflow is suspended, you can access the payload returned by `suspend()` by identifying the suspended step and reading its `suspendPayload`.
+
+```typescript {12} title="src/test-workflow.ts" showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRun();
+
+const result = await run.start({
+  inputData: {
+    userEmail: "alex@example.com"
+  }
+});
 
-## Game agent
+if (result.status === "suspended") {
+  const suspendStep = result.suspended[0];
+  const suspendedPayload = result.steps[suspendStep[0]].suspendPayload;
 
-The `gameAgent` handles user interactions by responding to questions and validating guesses.
+  console.log(suspendedPayload);
+}
+```
+**Example output**
 
-```typescript title="src/mastra/agents/example-game-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
+The data returned by the step can include a reason and help the user understand what’s needed to resume the workflow.
 
-export const gameAgent = new Agent({
-  id: "game-agent",
-  name: "Game Agent",
-  instructions: `You are a helpful game assistant for a "Heads Up" guessing game.
+```typescript
+{ reason: 'Confirm to send email.' }
+```
 
-CRITICAL: You know the famous person's name but you must NEVER reveal it in any response.
+## Resuming workflows with human input
 
-When a user asks a question about the famous person:
-- Answer truthfully based on the famous person provided
-- Keep responses concise and friendly
-- NEVER mention the person's name, even if it seems natural
-- NEVER reveal gender, nationality, or other characteristics unless specifically asked about them
-- Answer yes/no questions with clear "Yes" or "No" responses
-- Be consistent - same question asked differently should get the same answer
-- Ask for clarification if a question is unclear
-- If multiple questions are asked at once, ask them to ask one at a time
+As with [restarting a workflow](/docs/v1/workflows/suspend-and-resume#restarting-a-workflow-with-resume), use `resume()` with `resumeData` to continue a workflow after receiving input from a human. The workflow resumes from the step where it was paused.
 
-When they make a guess:
-- If correct: Congratulate them warmly
-- If incorrect: Politely correct them and encourage them to try again
+![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
 
-Encourage players to make a guess when they seem to have enough information.
+```typescript {13} showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRun();
 
-You must return a JSON object with:
-- response: Your response to the user
-- gameWon: true if they guessed correctly, false otherwise`,
-  model: openai("gpt-4o"),
+await run.start({
+  inputData: {
+    userEmail: "alex@example.com"
+  }
 });
+
+const handleResume = async () => {
+  const result = await run.resume({
+    step: "step-1",
+    resumeData: { approved: true }
+  });
+};
 ```
 
-## Multi-turn workflow
+### Handling human rejection with `bail()`
 
-The workflow coordinates the full interaction using `suspend`/`resume` to pause for human input and `dountil` to repeat the game loop until a condition is met.
+Use `bail()` to stop workflow execution at a step without triggering an error. This can be useful when a human explicitly rejects an action. The workflow completes with a `success` status, and any logic after the call to `bail()` is skipped.
 
-The `startStep` generates a name using the `famousPersonAgent`, while the `gameStep` runs the interaction through the `gameAgent`, which handles both questions and guesses and produces structured output that includes a `gameWon` boolean.
+```typescript {7-11} showLineNumbers copy
+const step1 = createStep({
+  // ...
+  execute: async ({ inputData, resumeData, suspend, bail }) => {
+    const { userEmail } = inputData;
+    const { approved } = resumeData ?? {};
 
-```typescript title="src/mastra/workflows/example-heads-up-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+    if (approved === false) {
+      return bail({
+        reason: "User rejected the request."
+      });
+    }
 
-const startStep = createStep({
-  id: "start-step",
-  description: "Get the name of a famous person",
-  inputSchema: z.object({
-    start: z.boolean(),
-  }),
-  outputSchema: z.object({
-    famousPerson: z.string(),
-    guessCount: z.number(),
-  }),
-  execute: async ({ mastra }) => {
-    const agent = mastra.getAgent("famousPersonAgent");
-    const response = await agent.generate("Generate a famous person's name", {
-      temperature: 1.2,
-      topP: 0.9,
-      memory: {
-        resource: "heads-up-game",
-        thread: "famous-person-generator",
-      },
-    });
-    const famousPerson = response.text.trim();
-    return { famousPerson, guessCount: 0 };
-  },
+    if (!approved) {
+      return await suspend({
+        reason: "Human approval required."
+      });
+    }
+
+    return {
+      message: `Email sent to ${userEmail}`
+    };
+  }
 });
+```
 
-const gameStep = createStep({
-  id: "game-step",
-  description: "Handles the question-answer-continue loop",
+## Multi-turn human input
+
+For workflows that require input at multiple stages, the suspend pattern remains the same. Each step defines a `resumeSchema`, and `suspendSchema` typically with a reason that can be used to provide user feedback.
+
+```typescript {11-16,21-25} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...});
+
+const step2 = createStep({
+  id: "step-2",
   inputSchema: z.object({
-    famousPerson: z.string(),
-    guessCount: z.number(),
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
   }),
   resumeSchema: z.object({
-    userMessage: z.string(),
+    approved: z.boolean()
   }),
   suspendSchema: z.object({
-    suspendResponse: z.string(),
-  }),
-  outputSchema: z.object({
-    famousPerson: z.string(),
-    gameWon: z.boolean(),
-    agentResponse: z.string(),
-    guessCount: z.number(),
+    reason: z.string()
   }),
-  execute: async ({ inputData, mastra, resumeData, suspend }) => {
-    let { famousPerson, guessCount } = inputData;
-    const { userMessage } = resumeData ?? {};
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { message } = inputData;
+    const { approved } = resumeData ?? {};
 
-    if (!userMessage) {
+    if (!approved) {
       return await suspend({
-        suspendResponse:
-          "I'm thinking of a famous person. Ask me yes/no questions to figure out who it is!",
+        reason: "Human approval required."
       });
     }
 
-    const agent = mastra.getAgent("gameAgent");
-    const response = await agent.generate(
-      `
-        The famous person is: ${famousPerson}
-        The user said: "${userMessage}"
-        Please respond appropriately. If this is a guess, tell me if it's correct.
-      `,
-      {
-        structuredOutput: {
-          schema: z.object({
-            response: z.string(),
-            gameWon: z.boolean(),
-          }),
-        },
-      },
-    );
-
-    const { response: agentResponse, gameWon } = response.object;
-
-    guessCount++;
-
-    return { famousPerson, gameWon, agentResponse, guessCount };
-  },
+    return {
+      output: `${message} - Deleted`
+    };
+  }
 });
 
-const winStep = createStep({
-  id: "win-step",
-  description: "Handle game win logic",
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
   inputSchema: z.object({
-    famousPerson: z.string(),
-    gameWon: z.boolean(),
-    agentResponse: z.string(),
-    guessCount: z.number(),
+    userEmail: z.string()
   }),
   outputSchema: z.object({
-    famousPerson: z.string(),
-    gameWon: z.boolean(),
-    guessCount: z.number(),
-  }),
-  execute: async ({ inputData }) => {
-    const { famousPerson, gameWon, guessCount } = inputData;
-
-    console.log("famousPerson: ", famousPerson);
-    console.log("gameWon: ", gameWon);
-    console.log("guessCount: ", guessCount);
-
-    return { famousPerson, gameWon, guessCount };
-  },
-});
-
-export const headsUpWorkflow = createWorkflow({
-  id: "heads-up-workflow",
-  inputSchema: z.object({
-    start: z.boolean(),
-  }),
-  outputSchema: z.object({
-    famousPerson: z.string(),
-    gameWon: z.boolean(),
-    guessCount: z.number(),
-  }),
+    output: z.string()
+  })
 })
-  .then(startStep)
-  .dountil(gameStep, async ({ inputData: { gameWon } }) => gameWon)
-  .then(winStep)
+  .then(step1)
+  .then(step2)
   .commit();
 ```
 
-> See [Workflow](/reference/v1/workflows/workflow) for a full list of configuration options.
-
-## Registering the agents and workflow
-
-To use a workflow or an agent, register them in your main Mastra instance.
-
-```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
-
-import { headsUpWorkflow } from "./workflows/example-heads-up-workflow";
-import { famousPersonAgent } from "./agents/example-famous-person-agent";
-import { gameAgent } from "./agents/example-game-agent";
-
-export const mastra = new Mastra({
-  workflows: { headsUpWorkflow },
-  agents: { famousPersonAgent, gameAgent },
-});
+Each step must be resumed in sequence, with a separate call to `resume()` for each suspended step. This approach helps manage multi-step approvals with consistent UI feedback and clear input handling at each stage.
+
+```typescript {4,11} showLineNumbers copy
+const handleResume = async () => {
+  const result = await run.resume({
+    step: "step-1",
+    resumeData: { approved: true }
+  });
+};
+
+const handleDelete = async () => {
+  const result = await run.resume({
+    step: "step-2",
+    resumeData: { approved: true }
+  });
+};
 ```
 
-<GithubLink
-  marginTop="mt-16"
-  link="https://github.com/mastra-ai/mastra/blob/main/examples/heads-up-game/"
-/>
-
 ## Related
 
-- [Running Workflows](./overview#running-workflows)
 - [Control Flow](/docs/v1/workflows/control-flow)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)