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

package/.docs/raw/workflows/dynamic-workflows.mdx

@@ -0,0 +1,236 @@
+---
+title: "Dynamic Workflows | Mastra Docs"
+description: "Learn how to create dynamic workflows within workflow steps, allowing for flexible workflow creation based on runtime conditions."
+---
+
+# Dynamic Workflows
+
+This guide demonstrates how to create dynamic workflows within a workflow step. This advanced pattern allows you to create and execute workflows on the fly based on runtime conditions.
+
+## Overview
+
+Dynamic workflows are useful when you need to create workflows based on runtime data.
+
+## Implementation
+
+The key to creating dynamic workflows is accessing the Mastra instance from within a step's `execute` function and using it to create and run a new workflow.
+
+### Basic Example
+
+```typescript
+import { Mastra, Step, Workflow } from '@mastra/core';
+import { z } from 'zod';
+
+const isMastra = (mastra: any): mastra is Mastra => {
+  return mastra && typeof mastra === 'object' && mastra instanceof Mastra;
+};
+
+// Step that creates and runs a dynamic workflow
+const createDynamicWorkflow = new Step({
+  id: 'createDynamicWorkflow',
+  outputSchema: z.object({
+    dynamicWorkflowResult: z.any(),
+  }),
+  execute: async ({ context, mastra }) => {
+    if (!mastra) {
+      throw new Error('Mastra instance not available');
+    }
+
+    if (!isMastra(mastra)) {
+      throw new Error('Invalid Mastra instance');
+    }
+
+    const inputData = context.triggerData.inputData;
+
+    // Create a new dynamic workflow
+    const dynamicWorkflow = new Workflow({
+      name: 'dynamic-workflow',
+      mastra, // Pass the mastra instance to the new workflow
+      triggerSchema: z.object({
+        dynamicInput: z.string(),
+      }),
+    });
+
+    // Define steps for the dynamic workflow
+    const dynamicStep = new Step({
+      id: 'dynamicStep',
+      execute: async ({ context }) => {
+        const dynamicInput = context.triggerData.dynamicInput;
+        return {
+          processedValue: `Processed: ${dynamicInput}`,
+        };
+      },
+    });
+
+    // Build and commit the dynamic workflow
+    dynamicWorkflow.step(dynamicStep).commit();
+
+    // Create a run and execute the dynamic workflow
+    const run = dynamicWorkflow.createRun();
+    const result = await run.start({
+      triggerData: {
+        dynamicInput: inputData,
+      },
+    });
+
+    let dynamicWorkflowResult;
+
+    if (result.results['dynamicStep']?.status === 'success') {
+      dynamicWorkflowResult = result.results['dynamicStep']?.output.processedValue;
+    } else {
+      throw new Error('Dynamic workflow failed');
+    }
+
+    // Return the result from the dynamic workflow
+    return {
+      dynamicWorkflowResult,
+    };
+  },
+});
+
+// Main workflow that uses the dynamic workflow creator
+const mainWorkflow = new Workflow({
+  name: 'main-workflow',
+  triggerSchema: z.object({
+    inputData: z.string(),
+  }),
+  mastra: new Mastra(),
+});
+
+mainWorkflow.step(createDynamicWorkflow).commit();
+
+// Register the workflow with Mastra
+export const mastra = new Mastra({
+  workflows: { mainWorkflow },
+});
+
+const run = mainWorkflow.createRun();
+const result = await run.start({
+  triggerData: {
+    inputData: 'test',
+  },
+});
+```
+
+## Advanced Example: Workflow Factory
+
+You can create a workflow factory that generates different workflows based on input parameters:
+
+```typescript
+
+const isMastra = (mastra: any): mastra is Mastra => {
+  return mastra && typeof mastra === 'object' && mastra instanceof Mastra;
+};
+
+const workflowFactory = new Step({
+  id: 'workflowFactory',
+  inputSchema: z.object({
+    workflowType: z.enum(['simple', 'complex']),
+    inputData: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.any(),
+  }),
+  execute: async ({ context, mastra }) => {
+    if (!mastra) {
+      throw new Error('Mastra instance not available');
+    }
+
+    if (!isMastra(mastra)) {
+      throw new Error('Invalid Mastra instance');
+    }
+
+    // Create a new dynamic workflow based on the type
+    const dynamicWorkflow = new Workflow({
+      name: `dynamic-${context.workflowType}-workflow`,
+      mastra,
+      triggerSchema: z.object({
+        input: z.string(),
+      }),
+    });
+
+    if (context.workflowType === 'simple') {
+      // Simple workflow with a single step
+      const simpleStep = new Step({
+        id: 'simpleStep',
+        execute: async ({ context }) => {
+          return {
+            result: `Simple processing: ${context.triggerData.input}`,
+          };
+        },
+      });
+
+      dynamicWorkflow.step(simpleStep).commit();
+    } else {
+      // Complex workflow with multiple steps
+      const step1 = new Step({
+        id: 'step1',
+        outputSchema: z.object({
+          intermediateResult: z.string(),
+        }),
+        execute: async ({ context }) => {
+          return {
+            intermediateResult: `First processing: ${context.triggerData.input}`,
+          };
+        },
+      });
+
+      const step2 = new Step({
+        id: 'step2',
+        execute: async ({ context }) => {
+          const intermediate = context.getStepResult(step1).intermediateResult;
+          return {
+            finalResult: `Second processing: ${intermediate}`,
+          };
+        },
+      });
+
+      dynamicWorkflow.step(step1).then(step2).commit();
+    }
+
+    // Execute the dynamic workflow
+    const run = dynamicWorkflow.createRun();
+    const result = await run.start({
+      triggerData: {
+        input: context.inputData,
+      },
+    });
+
+    // Return the appropriate result based on workflow type
+    if (context.workflowType === 'simple') {
+      return {
+        // @ts-ignore
+        result: result.results['simpleStep']?.output,
+      };
+    } else {
+      return {
+        // @ts-ignore
+        result: result.results['step2']?.output,
+      };
+    }
+  },
+});
+```
+
+## Important Considerations
+
+1. **Mastra Instance**: The `mastra` parameter in the `execute` function provides access to the Mastra instance, which is essential for creating dynamic workflows.
+
+2. **Error Handling**: Always check if the Mastra instance is available before attempting to create a dynamic workflow.
+
+3. **Resource Management**: Dynamic workflows consume resources, so be mindful of creating too many workflows in a single execution.
+
+4. **Workflow Lifecycle**: Dynamic workflows are not automatically registered with the main Mastra instance. They exist only for the duration of the step execution unless you explicitly register them.
+
+5. **Debugging**: Debugging dynamic workflows can be challenging. Consider adding detailed logging to track their creation and execution.
+
+## Use Cases
+
+- **Conditional Workflow Selection**: Choose different workflow patterns based on input data
+- **Parameterized Workflows**: Create workflows with dynamic configurations
+- **Workflow Templates**: Use templates to generate specialized workflows
+- **Multi-tenant Applications**: Create isolated workflows for different tenants
+
+## Conclusion
+
+Dynamic workflows provide a powerful way to create flexible, adaptable workflow systems. By leveraging the Mastra instance within step execution, you can create workflows that respond to runtime conditions and requirements.

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

@@ -0,0 +1,183 @@
+---
+title: "Error Handling in Workflows | Mastra Docs"
+description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
+---
+
+# Error Handling in Workflows
+
+Robust error handling is essential for production workflows. Mastra provides several mechanisms to handle errors gracefully, allowing your workflows to recover from failures or gracefully degrade when necessary.
+
+## Overview
+
+Error handling in Mastra workflows can be implemented using:
+
+1. **Step Retries** - Automatically retry failed steps
+2. **Conditional Branching** - Create alternative paths based on step success or failure
+3. **Error Monitoring** - Watch workflows for errors and handle them programmatically
+4. **Result Status Checks** - Check the status of previous steps in subsequent steps
+
+## Step Retries
+
+Mastra provides a built-in retry mechanism for steps that fail due to transient errors. This is particularly useful for steps that interact with external services or resources that might experience temporary unavailability.
+
+### Basic Retry Configuration
+
+You can configure retries at the workflow level or for individual steps:
+
+```typescript
+// Workflow-level retry configuration
+const workflow = new Workflow({
+  name: 'my-workflow',
+  retryConfig: {
+    attempts: 3,    // Number of retry attempts
+    delay: 1000,    // Delay between retries in milliseconds
+  },
+});
+
+// Step-level retry configuration (overrides workflow-level)
+const apiStep = new Step({
+  id: 'callApi',
+  execute: async () => {
+    // API call that might fail
+  },
+  retryConfig: {
+    attempts: 5,    // This step will retry up to 5 times
+    delay: 2000,    // With a 2-second delay between retries
+  },
+});
+```
+
+For more details about step retries, see the [Step Retries](../reference/workflows/step-retries.mdx) reference.
+
+## Conditional Branching
+
+You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
+
+```typescript
+// Create a workflow with conditional branching
+const workflow = new Workflow({
+  name: 'error-handling-workflow',
+});
+
+workflow
+  .step(fetchDataStep)
+  .then(processDataStep, {
+    // Only execute processDataStep if fetchDataStep was successful
+    when: ({ context }) => {
+      return context.steps.fetchDataStep?.status === 'success';
+    },
+  })
+  .then(fallbackStep, {
+    // Execute fallbackStep if fetchDataStep failed
+    when: ({ context }) => {
+      return context.steps.fetchDataStep?.status === 'failed';
+    },
+  })
+  .commit();
+```
+
+## Error Monitoring
+
+You can monitor workflows for errors using the `watch` method:
+
+```typescript
+const { start, watch } = workflow.createRun();
+
+watch(async ({ results }) => {
+  // Check for any failed steps
+  const failedSteps = Object.entries(results)
+    .filter(([_, step]) => step.status === "failed")
+    .map(([stepId]) => stepId);
+
+  if (failedSteps.length > 0) {
+    console.error(`Workflow has failed steps: ${failedSteps.join(', ')}`);
+    // Take remedial action, such as alerting or logging
+  }
+});
+
+await start();
+```
+
+## Handling Errors in Steps
+
+Within a step's execution function, you can handle errors programmatically:
+
+```typescript
+const robustStep = new Step({
+  id: 'robustStep',
+  execute: async ({ context }) => {
+    try {
+      // Attempt the primary operation
+      const result = await someRiskyOperation();
+      return { success: true, data: result };
+    } catch (error) {
+      // Log the error
+      console.error('Operation failed:', error);
+
+      // Return a graceful fallback result instead of throwing
+      return {
+        success: false,
+        error: error.message,
+        fallbackData: 'Default value'
+      };
+    }
+  },
+});
+```
+
+## Checking Previous Step Results
+
+You can make decisions based on the results of previous steps:
+
+```typescript
+const finalStep = new Step({
+  id: 'finalStep',
+  execute: async ({ context }) => {
+    // Check results of previous steps
+    const step1Success = context.steps.step1?.status === 'success';
+    const step2Success = context.steps.step2?.status === 'success';
+
+    if (step1Success && step2Success) {
+      // All steps succeeded
+      return { status: 'complete', result: 'All operations succeeded' };
+    } else if (step1Success) {
+      // Only step1 succeeded
+      return { status: 'partial', result: 'Partial completion' };
+    } else {
+      // Critical failure
+      return { status: 'failed', result: 'Critical steps failed' };
+    }
+  },
+});
+```
+
+## Best Practices for Error Handling
+
+1. **Use retries for transient failures**: Configure retry policies for steps that might experience temporary issues.
+
+2. **Provide fallback paths**: Design workflows with alternative paths for when critical steps fail.
+
+3. **Be specific about error scenarios**: Use different handling strategies for different types of errors.
+
+4. **Log errors comprehensively**: Include context information when logging errors to aid in debugging.
+
+5. **Return meaningful data on failure**: When a step fails, return structured data about the failure to help downstream steps make decisions.
+
+6. **Consider idempotency**: Ensure steps can be safely retried without causing duplicate side effects.
+
+7. **Monitor workflow execution**: Use the `watch` method to actively monitor workflow execution and detect errors early.
+
+## Advanced Error Handling
+
+For more complex error handling scenarios, consider:
+
+- **Implementing circuit breakers**: If a step fails repeatedly, stop retrying and use a fallback strategy
+- **Adding timeout handling**: Set time limits for steps to prevent workflows from hanging indefinitely
+- **Creating dedicated error recovery workflows**: For critical workflows, create separate recovery workflows that can be triggered when the main workflow fails
+
+## Related
+
+- [Step Retries Reference](../../reference/workflows/step-retries.mdx)
+- [Watch Method Reference](../../reference/workflows/watch.mdx)
+- [Step Conditions](../../reference/workflows/step-condition.mdx)
+- [Control Flow](./control-flow.mdx)