@mastra/mcp-docs-server 0.13.17-alpha.4 → 0.13.17-alpha.5

package/.docs/raw/workflows/suspend-and-resume.mdx

@@ -30,17 +30,15 @@ To pause execution at a specific step until user input is received, use the `⁠
 
 ![Suspending a workflow with suspend()](/image/workflows/workflows-suspend-resume-suspend.jpg)
 
-```typescript {18} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
   id: "step-1",
-  description: "Test suspend",
   inputSchema: z.object({
     input: z.string()
   }),
   outputSchema: z.object({
     output: z.string()
   }),
-  suspendSchema: z.object({}),
   resumeSchema: z.object({
     city: z.string()
   }),
@@ -48,15 +46,16 @@ const step1 = createStep({
     const { city } = resumeData ?? {};
 
     if (!city) {
-      await suspend({});
-      return { output: "" };
+      return await suspend({});
     }
 
     return { output: "" };
   }
 });
 
-export const testWorkflow = createWorkflow({})
+export const testWorkflow = createWorkflow({
+  // ...
+})
   .then(step1)
   .commit();
 ```
@@ -88,9 +87,10 @@ if (result.status === "suspended") {
     }
   });
 }
-
 ```
 
+> See [Run Workflow Results](/docs/workflows/overview#run-workflow-results) for more details.
+
 In this case, the logic resumes the first step listed in the `suspended` array. A `step` can also be defined using it's `id`, for example: 'step-1'.
 
 ```json
@@ -111,6 +111,63 @@ In this case, the logic resumes the first step listed in the `suspended` array.
 }
 ```
 
+## Providing user feedback with suspend
+
+When a workflow is suspended, feedback can be surfaced to the user through the `suspendSchema`. Include a reason in the `suspend` payload to explain why the workflow paused.
+
+```typescript {13,23} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: "step-1",
+  inputSchema: z.object({
+    value: z.string()
+  }),
+  resumeSchema: z.object({
+    confirm: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  outputSchema: z.object({
+    value: z.string()
+  }),
+  execute: async ({ resumeData, suspend }) => {
+    const { confirm } = resumeData ?? {};
+
+    if (!confirm) {
+      return await suspend({
+        reason: "Confirm to continue"
+      });
+    }
+
+    return { value: "" };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  // ...
+})
+  .then(step1)
+  .commit();
+
+```
+
+In this case, the reason provided explains that the user must confirm to continue.
+
+```json
+{
+  "step-1": {
+    // ...
+    "status": "suspended",
+    "suspendPayload": {
+      "reason": "Confirm to continue"
+    },
+  }
+}
+```
+
 > See [Run Workflow Results](/docs/workflows/overview#run-workflow-results) for more details.
 
 ## Resuming a workflow with `resume()`