@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,404 @@
+---
+title: "Suspend & Resume Workflows | Human-in-the-Loop | Mastra Docs"
+description: "Suspend and resume in Mastra workflows allows you to pause execution while waiting for external input or resources."
+---
+
+# Suspend and Resume in Workflows
+
+Complex workflows often need to pause execution while waiting for external input or resources.
+
+Mastra's suspend and resume features let you pause workflow execution at any step, persist the workflow snapshot to storage, and resume execution from the saved snapshot when ready.
+This entire process is automatically managed by Mastra. No config needed, or manual step required from the user.
+
+Storing the workflow snapshot to storage (LibSQL by default) means that the workflow state is permanently preserved across sessions, deployments, and server restarts. This persistence is crucial for workflows that might remain suspended for minutes, hours, or even days while waiting for external input or resources.
+
+## When to Use Suspend/Resume
+
+Common scenarios for suspending workflows include:
+
+- Waiting for human approval or input
+- Pausing until external API resources become available
+- Collecting additional data needed for later steps
+- Rate limiting or throttling expensive operations
+- Handling event-driven processes with external triggers
+
+## Basic Suspend Example
+
+Here's a simple workflow that suspends when a value is too low and resumes when given a higher value:
+
+```typescript
+const stepTwo = new Step({
+  id: "stepTwo",
+  outputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  execute: async ({ context, suspend }) => {
+    if (context.steps.stepOne.status !== "success") {
+      return { incrementedValue: 0 };
+    }
+
+    const currentValue = context.steps.stepOne.output.doubledValue;
+
+    if (currentValue < 100) {
+      await suspend();
+      return { incrementedValue: 0 };
+    }
+    return { incrementedValue: currentValue + 1 };
+  },
+});
+```
+
+## Async/Await Based Flow
+
+The suspend and resume mechanism in Mastra uses an async/await pattern that makes it intuitive to implement complex workflows with suspension points. The code structure naturally reflects the execution flow.
+
+### How It Works
+
+1. A step's execution function receives a `suspend` function in its parameters
+2. When called with `await suspend()`, the workflow pauses at that point
+3. The workflow state is persisted
+4. Later, the workflow can be resumed by calling `workflow.resume()` with the appropriate parameters
+5. Execution continues from the point after the `suspend()` call
+
+### Example with Multiple Suspension Points
+
+Here's an example of a workflow with multiple steps that can suspend:
+
+```typescript
+// Define steps with suspend capability
+const promptAgentStep = new Step({
+  id: "promptAgent",
+  execute: async ({ context, suspend }) => {
+    // Some condition that determines if we need to suspend
+    if (needHumanInput) {
+      // Optionally pass payload data that will be stored with suspended state
+      await suspend({ requestReason: "Need human input for prompt" });
+      // Code after suspend() will execute when the step is resumed
+      return { modelOutput: context.userInput };
+    }
+    return { modelOutput: "AI generated output" };
+  },
+  outputSchema: z.object({ modelOutput: z.string() }),
+});
+
+const improveResponseStep = new Step({
+  id: "improveResponse",
+  execute: async ({ context, suspend }) => {
+    // Another condition for suspension
+    if (needFurtherRefinement) {
+      await suspend();
+      return { improvedOutput: context.refinedOutput };
+    }
+    return { improvedOutput: "Improved output" };
+  },
+  outputSchema: z.object({ improvedOutput: z.string() }),
+});
+
+// Build the workflow
+const workflow = new Workflow({
+  name: "multi-suspend-workflow",
+  triggerSchema: z.object({ input: z.string() }),
+});
+
+workflow
+  .step(getUserInput)
+  .then(promptAgentStep)
+  .then(evaluateTone)
+  .then(improveResponseStep)
+  .then(evaluateImproved)
+  .commit();
+
+// Register the workflow with Mastra
+export const mastra = new Mastra({
+  workflows: { workflow },
+});
+```
+
+### Starting and Resuming the Workflow
+
+```typescript
+// Get the workflow and create a run
+const wf = mastra.getWorkflow("multi-suspend-workflow");
+const run = wf.createRun();
+
+// Start the workflow
+const initialResult = await run.start({
+  triggerData: { input: "initial input" },
+});
+
+let promptAgentStepResult = initialResult.activePaths.get("promptAgent");
+let promptAgentResumeResult = undefined;
+
+// Check if a step is suspended
+if (promptAgentStepResult?.status === "suspended") {
+  console.log("Workflow suspended at promptAgent step");
+
+  // Resume the workflow with new context
+  const resumeResult = await run.resume({
+    stepId: "promptAgent",
+    context: { userInput: "Human provided input" },
+  });
+
+  promptAgentResumeResult = resumeResult;
+}
+
+const improveResponseStepResult =
+  promptAgentResumeResult?.activePaths.get("improveResponse");
+
+if (improveResponseStepResult?.status === "suspended") {
+  console.log("Workflow suspended at improveResponse step");
+
+  // Resume again with different context
+  const finalResult = await run.resume({
+    stepId: "improveResponse",
+    context: { refinedOutput: "Human refined output" },
+  });
+
+  console.log("Workflow completed:", finalResult?.results);
+}
+```
+
+## Event-Based Suspension and Resumption
+
+In addition to manually suspending steps, Mastra provides event-based suspension through the `afterEvent` method. This allows workflows to automatically suspend and wait for a specific event to occur before continuing.
+
+### Using afterEvent and resumeWithEvent
+
+The `afterEvent` method automatically creates a suspension point in your workflow that waits for a specific event to occur. When the event happens, you can use `resumeWithEvent` to continue the workflow with the event data.
+
+Here's how it works:
+
+1. Define events in your workflow configuration
+2. Use `afterEvent` to create a suspension point waiting for that event
+3. When the event occurs, call `resumeWithEvent` with the event name and data
+
+### Example: Event-Based Workflow
+
+```typescript
+// Define steps
+const getUserInput = new Step({
+  id: "getUserInput",
+  execute: async () => ({ userInput: "initial input" }),
+  outputSchema: z.object({ userInput: z.string() }),
+});
+
+const processApproval = new Step({
+  id: "processApproval",
+  execute: async ({ context }) => {
+    // Access the event data from the context
+    const approvalData = context.inputData?.resumedEvent;
+    return {
+      approved: approvalData?.approved,
+      approvedBy: approvalData?.approverName,
+    };
+  },
+  outputSchema: z.object({
+    approved: z.boolean(),
+    approvedBy: z.string(),
+  }),
+});
+
+// Create workflow with event definition
+const approvalWorkflow = new Workflow({
+  name: "approval-workflow",
+  triggerSchema: z.object({ requestId: z.string() }),
+  events: {
+    approvalReceived: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+      }),
+    },
+  },
+});
+
+// Build workflow with event-based suspension
+approvalWorkflow
+  .step(getUserInput)
+  .afterEvent("approvalReceived") // Workflow will automatically suspend here
+  .step(processApproval) // This step runs after the event is received
+  .commit();
+```
+
+### Running an Event-Based Workflow
+
+```typescript
+// Get the workflow
+const workflow = mastra.getWorkflow("approval-workflow");
+const run = workflow.createRun();
+
+// Start the workflow
+const initialResult = await run.start({
+  triggerData: { requestId: "request-123" },
+});
+
+console.log("Workflow started, waiting for approval event");
+console.log(initialResult.results);
+// Output will show the workflow is suspended at the event step:
+// {
+//   getUserInput: { status: 'success', output: { userInput: 'initial input' } },
+//   __approvalReceived_event: { status: 'suspended' }
+// }
+
+// Later, when the approval event occurs:
+const resumeResult = await run.resumeWithEvent("approvalReceived", {
+  approved: true,
+  approverName: "Jane Doe",
+});
+
+console.log("Workflow resumed with event data:", resumeResult.results);
+// Output will show the completed workflow:
+// {
+//   getUserInput: { status: 'success', output: { userInput: 'initial input' } },
+//   __approvalReceived_event: { status: 'success', output: { executed: true, resumedEvent: { approved: true, approverName: 'Jane Doe' } } },
+//   processApproval: { status: 'success', output: { approved: true, approvedBy: 'Jane Doe' } }
+// }
+```
+
+### Key Points About Event-Based Workflows
+
+- The `suspend()` function can optionally take a payload object that will be stored with the suspended state
+- Code after the `await suspend()` call will not execute until the step is resumed
+- When a step is suspended, its status becomes `'suspended'` in the workflow results
+- When resumed, the step's status changes from `'suspended'` to `'success'` once completed
+- The `resume()` method requires the `stepId` to identify which suspended step to resume
+- You can provide new context data when resuming that will be merged with existing step results
+
+- Events must be defined in the workflow configuration with a schema
+- The `afterEvent` method creates a special suspended step that waits for the event
+- The event step is automatically named `__eventName_event` (e.g., `__approvalReceived_event`)
+- Use `resumeWithEvent` to provide event data and continue the workflow
+- Event data is validated against the schema defined for that event
+- The event data is available in the context as `inputData.resumedEvent`
+
+## Storage for Suspend and Resume
+
+When a workflow is suspended using `await suspend()`, Mastra automatically persists the entire workflow state to storage. This is essential for workflows that might remain suspended for extended periods, as it ensures the state is preserved across application restarts or server instances.
+
+### Default Storage: LibSQL
+
+By default, Mastra uses LibSQL as its storage engine:
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+import { DefaultStorage } from "@mastra/core/storage/libsql";
+
+const mastra = new Mastra({
+  storage: new DefaultStorage({
+    config: {
+      url: "file:storage.db", // Local file-based database for development
+      // For production, use a persistent URL:
+      // url: process.env.DATABASE_URL,
+      // authToken: process.env.DATABASE_AUTH_TOKEN, // Optional for authenticated connections
+    },
+  }),
+});
+```
+
+The LibSQL storage can be configured in different modes:
+
+- In-memory database (testing): `:memory:`
+- File-based database (development): `file:storage.db`
+- Remote database (production): URLs like `libsql://your-database.turso.io`
+
+### Alternative Storage Options
+
+#### Upstash (Redis-Compatible)
+
+For serverless applications or environments where Redis is preferred:
+
+```bash
+npm install @mastra/upstash
+```
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+import { UpstashStore } from "@mastra/upstash";
+
+const mastra = new Mastra({
+  storage: new UpstashStore({
+    url: process.env.UPSTASH_URL,
+    token: process.env.UPSTASH_TOKEN,
+  }),
+});
+```
+
+### Storage Considerations
+
+- All storage options support suspend and resume functionality identically
+- The workflow state is automatically serialized and saved when suspended
+- No additional configuration is needed for suspend/resume to work with storage
+- Choose your storage option based on your infrastructure, scaling needs, and existing technology stack
+
+## Watching and Resuming
+
+To handle suspended workflows, use the `watch` method to monitor workflow status per run and `resume` to continue execution:
+
+```typescript
+import { mastra } from "./index";
+
+// Get the workflow
+const myWorkflow = mastra.getWorkflow("myWorkflow");
+const { start, watch, resume } = myWorkflow.createRun();
+
+// Start watching the workflow before executing it
+watch(async ({ activePaths }) => {
+  const isStepTwoSuspended = activePaths.get("stepTwo")?.status === "suspended";
+  if (isStepTwoSuspended) {
+    console.log("Workflow suspended, resuming with new value");
+
+    // Resume the workflow with new context
+    await resume({
+      stepId: "stepTwo",
+      context: { secondValue: 100 },
+    });
+  }
+});
+
+// Start the workflow execution
+await start({ triggerData: { inputValue: 45 } });
+```
+
+### Watching and Resuming Event-Based Workflows
+
+You can use the same watching pattern with event-based workflows:
+
+```typescript
+const { start, watch, resumeWithEvent } = workflow.createRun();
+
+// Watch for suspended event steps
+watch(async ({ activePaths }) => {
+  const isApprovalReceivedSuspended =
+    activePaths.get("__approvalReceived_event")?.status === "suspended";
+  if (isApprovalReceivedSuspended) {
+    console.log("Workflow waiting for approval event");
+
+    // In a real scenario, you would wait for the actual event to occur
+    // For example, this could be triggered by a webhook or user interaction
+    setTimeout(async () => {
+      await resumeWithEvent("approvalReceived", {
+        approved: true,
+        approverName: "Auto Approver",
+      });
+    }, 5000); // Simulate event after 5 seconds
+  }
+});
+
+// Start the workflow
+await start({ triggerData: { requestId: "auto-123" } });
+```
+
+## Further Reading
+
+For a deeper understanding of how suspend and resume works under the hood:
+
+- [Understanding Snapshots in Mastra Workflows](../../reference/workflows/snapshots.mdx) - Learn about the snapshot mechanism that powers suspend and resume functionality
+- [Step Configuration Guide](./steps.mdx) - Learn more about configuring steps in your workflows
+- [Control Flow Guide](./control-flow.mdx) - Advanced workflow control patterns
+- [Event-Driven Workflows](../../reference/workflows/events.mdx) - Detailed reference for event-based workflows
+
+## Related Resources
+
+- See the [Suspend and Resume Example](../../examples/workflows/suspend-and-resume.mdx) for a complete working example
+- Check the [Step Class Reference](../../reference/workflows/step-class.mdx) for suspend/resume API details
+- Review [Workflow Observability](../../reference/observability/otel-config.mdx) for monitoring suspended workflows

package/.docs/raw/workflows/variables.mdx

@@ -0,0 +1,313 @@
+---
+title: "Data Mapping with Workflow Variables | Mastra Docs"
+description: "Learn how to use workflow variables to map data between steps and create dynamic data flows in your Mastra workflows."
+---
+
+# Data Mapping with Workflow Variables
+
+Workflow variables in Mastra provide a powerful mechanism for mapping data between steps, allowing you to create dynamic data flows and pass information from one step to another.
+
+## Understanding Workflow Variables
+
+In Mastra workflows, variables serve as a way to:
+
+- Map data from trigger inputs to step inputs
+- Pass outputs from one step to inputs of another step
+- Access nested properties within step outputs
+- Create more flexible and reusable workflow steps
+
+## Using Variables for Data Mapping
+
+### Basic Variable Mapping
+
+You can map data between steps using the `variables` property when adding a step to your workflow:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+const workflow = new Workflow({
+  name: 'data-mapping-workflow',
+  triggerSchema: z.object({
+    inputData: z.string(),
+  }),
+});
+
+workflow
+  .step(step1, {
+    variables: {
+      // Map trigger data to step input
+      inputData: { step: 'trigger', path: 'inputData' }
+    }
+  })
+  .then(step2, {
+    variables: {
+      // Map output from step1 to input for step2
+      previousValue: { step: step1, path: 'outputField' }
+    }
+  })
+  .commit();
+
+// Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { workflow },
+  });
+```
+
+### Accessing Nested Properties
+
+You can access nested properties using dot notation in the `path` field:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+workflow
+  .step(step1)
+  .then(step2, {
+    variables: {
+      // Access a nested property from step1's output
+      nestedValue: { step: step1, path: 'nested.deeply.value' }
+    }
+  })
+  .commit();
+```
+
+### Mapping Entire Objects
+
+You can map an entire object by using `.` as the path:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+workflow
+  .step(step1, {
+    variables: {
+      // Map the entire trigger data object
+      triggerData: { step: 'trigger', path: '.' }
+    }
+  })
+  .commit();
+```
+
+### Variables in Loops
+
+Variables can also be passed to `while` and `until` loops. This is useful for passing data between iterations or from outside steps:
+
+```typescript showLineNumbers filename="src/mastra/workflows/loop-variables.ts" copy
+// Step that increments a counter
+const incrementStep = new Step({
+  id: 'increment',
+  inputSchema: z.object({
+    // Previous value from last iteration
+    prevValue: z.number().optional(),
+  }),
+  outputSchema: z.object({
+    // Updated counter value
+    updatedCounter: z.number(),
+  }),
+  execute: async ({ context }) => {
+    const { prevValue = 0 } = context.inputData;
+    return { updatedCounter: prevValue + 1 };
+  },
+});
+
+const workflow = new Workflow({
+  name: 'counter'
+});
+
+workflow
+  .step(incrementStep)
+  .while(
+    async ({ context }) => {
+      // Continue while counter is less than 10
+      const result = context.getStepResult(incrementStep);
+      return (result?.updatedCounter ?? 0) < 10;
+    },
+    incrementStep,
+    {
+      // Pass previous value to next iteration
+      prevValue: {
+        step: incrementStep,
+        path: 'updatedCounter'
+      }
+    }
+  );
+```
+
+## Variable Resolution
+
+When a workflow executes, Mastra resolves variables at runtime by:
+
+1. Identifying the source step specified in the `step` property
+2. Retrieving the output from that step
+3. Navigating to the specified property using the `path`
+4. Injecting the resolved value into the target step's context as the `inputData` property
+
+## Examples
+
+### Mapping from Trigger Data
+
+This example shows how to map data from the workflow trigger to a step:
+
+```typescript showLineNumbers filename="src/mastra/workflows/trigger-mapping.ts" copy
+import { Step, Workflow, Mastra } from "@mastra/core";
+import { z } from "zod";
+
+// Define a step that needs user input
+const processUserInput = new Step({
+  id: "processUserInput",
+  execute: async ({ context }) => {
+    // The inputData will be available in context because of the variable mapping
+    const { inputData } = context.inputData;
+
+    return {
+      processedData: `Processed: ${inputData}`
+    };
+  },
+});
+
+// Create the workflow
+const workflow = new Workflow({
+  name: "trigger-mapping",
+  triggerSchema: z.object({
+    inputData: z.string(),
+  }),
+});
+
+// Map the trigger data to the step
+workflow
+  .step(processUserInput, {
+    variables: {
+      inputData: { step: 'trigger', path: 'inputData' },
+    }
+  })
+  .commit();
+
+  // Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { workflow },
+  });
+```
+
+### Mapping Between Steps
+
+This example demonstrates mapping data from one step to another:
+
+```typescript showLineNumbers filename="src/mastra/workflows/step-mapping.ts" copy
+import { Step, Workflow, Mastra } from "@mastra/core";
+import { z } from "zod";
+
+// Step 1: Generate data
+const generateData = new Step({
+  id: "generateData",
+  outputSchema: z.object({
+    nested: z.object({
+      value: z.string(),
+    }),
+  }),
+  execute: async () => {
+    return {
+      nested: {
+        value: "step1-data"
+      }
+    };
+  },
+});
+
+// Step 2: Process the data from step 1
+const processData = new Step({
+  id: "processData",
+  inputSchema: z.object({
+    previousValue: z.string(),
+  }),
+  execute: async ({ context }) => {
+    // previousValue will be available because of the variable mapping
+    const { previousValue } = context.inputData;
+
+    return {
+      result: `Processed: ${previousValue}`
+    };
+  },
+});
+
+// Create the workflow
+const workflow = new Workflow({
+  name: "step-mapping",
+});
+
+// Map data from step1 to step2
+workflow
+  .step(generateData)
+  .then(processData, {
+    variables: {
+      // Map the nested.value property from generateData's output
+      previousValue: { step: generateData, path: 'nested.value' },
+    }
+  })
+  .commit();
+
+  // Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { workflow },
+  });
+```
+
+## Type Safety
+
+Mastra provides type safety for variable mappings when using TypeScript:
+
+```typescript showLineNumbers filename="src/mastra/workflows/type-safe.ts" copy
+import { Step, Workflow, Mastra } from "@mastra/core";
+import { z } from "zod";
+
+// Define schemas for better type safety
+const triggerSchema = z.object({
+  inputValue: z.string(),
+});
+
+type TriggerType = z.infer<typeof triggerSchema>;
+
+// Step with typed context
+const step1 = new Step({
+  id: "step1",
+  outputSchema: z.object({
+    nested: z.object({
+      value: z.string(),
+    }),
+  }),
+  execute: async ({ context }) => {
+    // TypeScript knows the shape of triggerData
+    const triggerData = context.getStepResult<TriggerType>('trigger');
+
+    return {
+      nested: {
+        value: `processed-${triggerData?.inputValue}`
+      }
+    };
+  },
+});
+
+// Create the workflow with the schema
+const workflow = new Workflow({
+  name: "type-safe-workflow",
+  triggerSchema,
+});
+
+workflow.step(step1).commit();
+
+  // Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { workflow },
+  });
+```
+
+## Best Practices
+
+1. **Validate Inputs and Outputs**: Use `inputSchema` and `outputSchema` to ensure data consistency.
+
+2. **Keep Mappings Simple**: Avoid overly complex nested paths when possible.
+
+3. **Consider Default Values**: Handle cases where mapped data might be undefined.
+
+## Comparison with Direct Context Access
+
+While you can access previous step results directly via `context.steps`, using variable mappings offers several advantages:
+
+| Feature | Variable Mapping | Direct Context Access |
+| ------- | --------------- | --------------------- |
+| Clarity | Explicit data dependencies | Implicit dependencies |
+| Reusability | Steps can be reused with different mappings | Steps are tightly coupled |
+| Type Safety | Better TypeScript integration | Requires manual type assertions |