@mastra/mcp-docs-server 1.0.0-beta.2 → 1.0.0-beta.3

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-resume-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.createRunAsync();
+
+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-suspend-resume-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.createRunAsync();
 
-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)

package/.docs/raw/workflows/inngest-workflow.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Inngest Workflow | Workflows | Mastra Docs"
+title: "Inngest Workflow | Workflows"
 description: "Inngest workflow allows you to run Mastra workflows with Inngest"
 ---
 

package/.docs/raw/workflows/input-data-mapping.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Input Data Mapping | Workflows | Mastra Docs"
+title: "Input Data Mapping | Workflows"
 description: "Learn how to use workflow input mapping to create more dynamic data flows in your Mastra workflows."
 ---
 

package/.docs/raw/workflows/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Workflows overview | Workflows | Mastra Docs"
+title: "Workflows overview | Workflows"
 description: "Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more."
 ---
 
@@ -260,7 +260,12 @@ for await (const chunk of result.stream) {
   </TabItem>
 </Tabs>
 
-## Workflow output
+
+### Workflow status types
+
+When running a workflow, its `status` can be `running`, `suspended`, `success`, or `failed`.
+
+### Workflow output
 
 The workflow output includes the full execution lifecycle, showing the input and output for each step. It also includes the status of each step, the overall workflow status, and the final result. This gives you clear insight into how data moved through the workflow, what each step produced, and how the workflow completed.
 
@@ -330,3 +335,6 @@ Use [Studio](/docs/v1/getting-started/studio) to easily run workflows with diffe
 
 For a closer look at workflows, see our [Workflow Guide](/guides/v1/guide/ai-recruiter), which walks through the core concepts with a practical example.
 
+- [Control Flow](/docs/v1/workflows/control-flow)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Error Handling](/docs/v1/workflows/error-handling)

package/.docs/raw/workflows/snapshots.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Snapshots | Workflows | Mastra Docs"
+title: "Snapshots | Workflows"
 description: "Learn how to save and resume workflow execution state with snapshots in Mastra"
 ---
 
@@ -266,5 +266,6 @@ if (result.status === "suspended") {
 
 ## Related
 
-- [Suspend and resume](/docs/v1/workflows/suspend-and-resume)
-- [Human in the loop example](/docs/v1/workflows/human-in-the-loop)
+- [Control Flow](/docs/v1/workflows/control-flow)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)