@mastra/mcp-docs-server 0.0.5 → 0.0.6-alpha.2

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

@@ -0,0 +1,352 @@
+# Nested Workflows
+
+Mastra allows you to use workflows as steps within other workflows, enabling you to create modular and reusable workflow components. This feature helps in organizing complex workflows into smaller, manageable pieces and promotes code reuse.
+
+It is also visually easier to understand the flow of a workflow when you can see the nested workflows as steps in the parent workflow.
+
+## Basic Usage
+
+You can use a workflow as a step directly in another workflow using the `step()` method:
+
+```typescript
+// Create a nested workflow
+const nestedWorkflow = new Workflow({ name: "nested-workflow" })
+  .step(stepA)
+  .then(stepB)
+  .commit();
+
+// Use the nested workflow in a parent workflow
+const parentWorkflow = new Workflow({ name: "parent-workflow" })
+  .step(nestedWorkflow, {
+    variables: {
+      city: {
+        step: "trigger",
+        path: "myTriggerInput",
+      },
+    },
+  })
+  .then(stepC)
+  .commit();
+```
+
+When a workflow is used as a step:
+
+- It is automatically converted to a step using the workflow's name as the step ID
+- The workflow's results are available in the parent workflow's context
+- The nested workflow's steps are executed in their defined order
+
+## Accessing Results
+
+Results from a nested workflow are available in the parent workflow's context under the nested workflow's name. The results include all step outputs from the nested workflow:
+
+```typescript
+const { results } = await parentWorkflow.start();
+// Access nested workflow results
+const nestedWorkflowResult = results["nested-workflow"];
+if (nestedWorkflowResult.status === "success") {
+  const nestedResults = nestedWorkflowResult.output.results;
+}
+```
+
+## Control Flow with Nested Workflows
+
+Nested workflows support all the control flow features available to regular steps:
+
+### Parallel Execution
+
+Multiple nested workflows can be executed in parallel:
+
+```typescript
+parentWorkflow
+  .step(nestedWorkflowA)
+  .step(nestedWorkflowB)
+  .after([nestedWorkflowA, nestedWorkflowB])
+  .step(finalStep);
+```
+
+Or using `step()` with an array of workflows:
+
+```typescript
+parentWorkflow.step([nestedWorkflowA, nestedWorkflowB]).then(finalStep);
+```
+
+In this case, `then()` will implicitly wait for all the workflows to finish before executing the final step.
+
+### If-Else Branching
+
+Nested workflows can be used in if-else branches using the new syntax that accepts both branches as arguments:
+
+```typescript
+// Create nested workflows for different paths
+const workflowA = new Workflow({ name: "workflow-a" })
+  .step(stepA1)
+  .then(stepA2)
+  .commit();
+
+const workflowB = new Workflow({ name: "workflow-b" })
+  .step(stepB1)
+  .then(stepB2)
+  .commit();
+
+// Use the new if-else syntax with nested workflows
+parentWorkflow
+  .step(initialStep)
+  .if(
+    async ({ context }) => {
+      // Your condition here
+      return someCondition;
+    },
+    workflowA, // if branch
+    workflowB, // else branch
+  )
+  .then(finalStep)
+  .commit();
+```
+
+The new syntax is more concise and clearer when working with nested workflows. When the condition is:
+
+- `true`: The first workflow (if branch) is executed
+- `false`: The second workflow (else branch) is executed
+
+The skipped workflow will have a status of `skipped` in the results:
+
+The `.then(finalStep)` call following the if-else block will merge the if and else branches back into a single execution path.
+
+### Looping
+
+Nested workflows can use `.until()` and `.while()` loops same as any other step. One interesting new pattern is to pass a workflow directly as the loop-back argument to keep executing that nested workflow until something is true about its results:
+
+```typescript
+parentWorkflow
+  .step(firstStep)
+  .while(
+    ({ context }) =>
+      context.getStepResult("nested-workflow").output.results.someField ===
+      "someValue",
+    nestedWorkflow,
+  )
+  .step(finalStep)
+  .commit();
+```
+
+## Watching Nested Workflows
+
+You can watch the state changes of nested workflows using the `watch` method on the parent workflow. This is useful for monitoring the progress and state transitions of complex workflows:
+
+```typescript
+const parentWorkflow = new Workflow({ name: "parent-workflow" })
+  .step([nestedWorkflowA, nestedWorkflowB])
+  .then(finalStep)
+  .commit();
+
+const run = parentWorkflow.createRun();
+const unwatch = parentWorkflow.watch((state) => {
+  console.log("Current state:", state.value);
+  // Access nested workflow states in state.context
+});
+
+await run.start();
+unwatch(); // Stop watching when done
+```
+
+## Suspending and Resuming
+
+Nested workflows support suspension and resumption, allowing you to pause and continue workflow execution at specific points. You can suspend either the entire nested workflow or specific steps within it:
+
+```typescript
+// Define a step that may need to suspend
+const suspendableStep = new Step({
+  id: "other",
+  description: "Step that may need to suspend",
+  execute: async ({ context, suspend }) => {
+    if (!wasSuspended) {
+      wasSuspended = true;
+      await suspend();
+    }
+    return { other: 26 };
+  },
+});
+
+// Create a nested workflow with suspendable steps
+const nestedWorkflow = new Workflow({ name: "nested-workflow-a" })
+  .step(startStep)
+  .then(suspendableStep)
+  .then(finalStep)
+  .commit();
+
+// Use in parent workflow
+const parentWorkflow = new Workflow({ name: "parent-workflow" })
+  .step(beginStep)
+  .then(nestedWorkflow)
+  .then(lastStep)
+  .commit();
+
+// Start the workflow
+const run = parentWorkflow.createRun();
+const { runId, results } = await run.start({ triggerData: { startValue: 1 } });
+
+// Check if a specific step in the nested workflow is suspended
+if (results["nested-workflow-a"].output.results.other.status === "suspended") {
+  // Resume the specific suspended step using dot notation
+  const resumedResults = await run.resume({
+    stepId: "nested-workflow-a.other",
+    context: { startValue: 1 },
+  });
+
+  // The resumed results will contain the completed nested workflow
+  expect(resumedResults.results["nested-workflow-a"].output.results).toEqual({
+    start: { output: { newValue: 1 }, status: "success" },
+    other: { output: { other: 26 }, status: "success" },
+    final: { output: { finalValue: 27 }, status: "success" },
+  });
+}
+```
+
+When resuming a nested workflow:
+
+- Use the nested workflow's name as the `stepId` when calling `resume()` to resume the entire workflow
+- Use dot notation (`nested-workflow.step-name`) to resume a specific step within the nested workflow
+- The nested workflow will continue from the suspended step with the provided context
+- You can check the status of specific steps in the nested workflow's results using `results["nested-workflow"].output.results`
+
+## Result Schemas and Mapping
+
+Nested workflows can define their result schema and mapping, which helps in type safety and data transformation. This is particularly useful when you want to ensure the nested workflow's output matches a specific structure or when you need to transform the results before they're used in the parent workflow.
+
+```typescript
+// Create a nested workflow with result schema and mapping
+const nestedWorkflow = new Workflow({
+  name: "nested-workflow",
+  result: {
+    schema: z.object({
+      total: z.number(),
+      items: z.array(
+        z.object({
+          id: z.string(),
+          value: z.number(),
+        }),
+      ),
+    }),
+    mapping: {
+      // Map values from step results using variables syntax
+      total: { step: "step-a", path: "count" },
+      items: { step: "step-b", path: "items" },
+    },
+  },
+})
+  .step(stepA)
+  .then(stepB)
+  .commit();
+
+// Use in parent workflow with type-safe results
+const parentWorkflow = new Workflow({ name: "parent-workflow" })
+  .step(nestedWorkflow)
+  .then(async ({ context }) => {
+    const result = context.getStepResult("nested-workflow");
+    // TypeScript knows the structure of result
+    console.log(result.total); // number
+    console.log(result.items); // Array<{ id: string, value: number }>
+    return { success: true };
+  })
+  .commit();
+```
+
+## Best Practices
+
+1. **Modularity**: Use nested workflows to encapsulate related steps and create reusable workflow components.
+2. **Naming**: Give nested workflows descriptive names as they will be used as step IDs in the parent workflow.
+3. **Error Handling**: Nested workflows propagate their errors to the parent workflow, so handle errors appropriately.
+4. **State Management**: Each nested workflow maintains its own state but can access the parent workflow's context.
+5. **Suspension**: When using suspension in nested workflows, consider the entire workflow's state and handle resumption appropriately.
+
+## Example
+
+Here's a complete example showing various features of nested workflows:
+
+```typescript
+const workflowA = new Workflow({
+  name: "workflow-a",
+  result: {
+    schema: z.object({
+      activities: z.string(),
+    }),
+    mapping: {
+      activities: {
+        step: planActivities,
+        path: "activities",
+      },
+    },
+  },
+})
+  .step(fetchWeather)
+  .then(planActivities)
+  .commit();
+
+const workflowB = new Workflow({
+  name: "workflow-b",
+  result: {
+    schema: z.object({
+      activities: z.string(),
+    }),
+    mapping: {
+      activities: {
+        step: planActivities,
+        path: "activities",
+      },
+    },
+  },
+})
+  .step(fetchWeather)
+  .then(planActivities)
+  .commit();
+
+const weatherWorkflow = new Workflow({
+  name: "weather-workflow",
+  triggerSchema: z.object({
+    cityA: z.string().describe("The city to get the weather for"),
+    cityB: z.string().describe("The city to get the weather for"),
+  }),
+  result: {
+    schema: z.object({
+      activitiesA: z.string(),
+      activitiesB: z.string(),
+    }),
+    mapping: {
+      activitiesA: {
+        step: workflowA,
+        path: "result.activities",
+      },
+      activitiesB: {
+        step: workflowB,
+        path: "result.activities",
+      },
+    },
+  },
+})
+  .step(workflowA, {
+    variables: {
+      city: {
+        step: "trigger",
+        path: "cityA",
+      },
+    },
+  })
+  .step(workflowB, {
+    variables: {
+      city: {
+        step: "trigger",
+        path: "cityB",
+      },
+    },
+  });
+
+weatherWorkflow.commit();
+```
+
+In this example:
+
+1. We define schemas for type safety across all workflows
+2. Each step has proper input and output schemas
+3. The nested workflows have their own trigger schemas and result mappings
+4. Data is passed through using variables syntax in the `.step()` calls
+5. The main workflow combines data from both nested workflows

package/.docs/raw/workflows/{00-overview.mdx → overview.mdx}

@@ -162,7 +162,7 @@ You can:
 
 ## More Resources
 
-- The [Workflow Guide](../guides/04-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
+- The [Workflow Guide](../guides/ai-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
 - [Sequential Steps workflow example](../../examples/workflows/sequential-steps.mdx)
 - [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)
 - [Branching Paths workflow example](../../examples/workflows/branching-paths.mdx)

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

@@ -67,36 +67,36 @@ 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',
+  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' });
+      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' };
+    return { modelOutput: "AI generated output" };
   },
   outputSchema: z.object({ modelOutput: z.string() }),
 });
 
 const improveResponseStep = new Step({
-  id: 'improveResponse',
+  id: "improveResponse",
   execute: async ({ context, suspend }) => {
     // Another condition for suspension
     if (needFurtherRefinement) {
       await suspend();
       return { improvedOutput: context.refinedOutput };
     }
-    return { improvedOutput: 'Improved output' };
+    return { improvedOutput: "Improved output" };
   },
   outputSchema: z.object({ improvedOutput: z.string() }),
 });
 
 // Build the workflow
 const workflow = new Workflow({
-  name: 'multi-suspend-workflow',
+  name: "multi-suspend-workflow",
   triggerSchema: z.object({ input: z.string() }),
 });
 
@@ -108,50 +108,53 @@ workflow
   .then(evaluateImproved)
   .commit();
 
-  // Register the workflow with Mastra
-  export const mastra = new Mastra({
-    workflows: { workflow },
-  });
+// 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 wf = mastra.getWorkflow("multi-suspend-workflow");
 const run = wf.createRun();
 
 // Start the workflow
-const initialResult = await run.start({ triggerData: { input: 'initial input' } });
+const initialResult = await run.start({
+  triggerData: { input: "initial input" },
+});
 
-let promptAgentStepResult = initialResult.activePaths.get('promptAgent');
+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');
+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' }
+    stepId: "promptAgent",
+    context: { userInput: "Human provided input" },
   });
 
   promptAgentResumeResult = resumeResult;
 }
 
-const improveResponseStepResult = promptAgentResumeResult?.activePaths.get('improveResponse');
+const improveResponseStepResult =
+  promptAgentResumeResult?.activePaths.get("improveResponse");
 
-if (improveResponseStepResult?.status === 'suspended') {
-  console.log('Workflow suspended at improveResponse step');
+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' }
+    stepId: "improveResponse",
+    context: { refinedOutput: "Human refined output" },
   });
 
-  console.log('Workflow completed:', finalResult?.results);
+  console.log("Workflow completed:", finalResult?.results);
 }
 ```
 
@@ -174,30 +177,30 @@ Here's how it works:
 ```typescript
 // Define steps
 const getUserInput = new Step({
-  id: 'getUserInput',
-  execute: async () => ({ userInput: 'initial input' }),
+  id: "getUserInput",
+  execute: async () => ({ userInput: "initial input" }),
   outputSchema: z.object({ userInput: z.string() }),
 });
 
 const processApproval = new Step({
-  id: 'processApproval',
+  id: "processApproval",
   execute: async ({ context }) => {
     // Access the event data from the context
     const approvalData = context.inputData?.resumedEvent;
     return {
       approved: approvalData?.approved,
-      approvedBy: approvalData?.approverName
+      approvedBy: approvalData?.approverName,
     };
   },
   outputSchema: z.object({
     approved: z.boolean(),
-    approvedBy: z.string()
+    approvedBy: z.string(),
   }),
 });
 
 // Create workflow with event definition
 const approvalWorkflow = new Workflow({
-  name: 'approval-workflow',
+  name: "approval-workflow",
   triggerSchema: z.object({ requestId: z.string() }),
   events: {
     approvalReceived: {
@@ -212,8 +215,8 @@ const approvalWorkflow = new Workflow({
 // 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
+  .afterEvent("approvalReceived") // Workflow will automatically suspend here
+  .step(processApproval) // This step runs after the event is received
   .commit();
 ```
 
@@ -221,15 +224,15 @@ approvalWorkflow
 
 ```typescript
 // Get the workflow
-const workflow = mastra.getWorkflow('approval-workflow');
+const workflow = mastra.getWorkflow("approval-workflow");
 const run = workflow.createRun();
 
 // Start the workflow
 const initialResult = await run.start({
-  triggerData: { requestId: 'request-123' }
+  triggerData: { requestId: "request-123" },
 });
 
-console.log('Workflow started, waiting for approval event');
+console.log("Workflow started, waiting for approval event");
 console.log(initialResult.results);
 // Output will show the workflow is suspended at the event step:
 // {
@@ -238,12 +241,12 @@ console.log(initialResult.results);
 // }
 
 // Later, when the approval event occurs:
-const resumeResult = await run.resumeWithEvent('approvalReceived', {
+const resumeResult = await run.resumeWithEvent("approvalReceived", {
   approved: true,
-  approverName: 'Jane Doe'
+  approverName: "Jane Doe",
 });
 
-console.log('Workflow resumed with event data:', resumeResult.results);
+console.log("Workflow resumed with event data:", resumeResult.results);
 // Output will show the completed workflow:
 // {
 //   getUserInput: { status: 'success', output: { userInput: 'initial input' } },
@@ -277,8 +280,8 @@ When a workflow is suspended using `await suspend()`, Mastra automatically persi
 By default, Mastra uses LibSQL as its storage engine:
 
 ```typescript
-import { Mastra } from '@mastra/core/mastra';
-import { DefaultStorage } from '@mastra/core/storage/libsql';
+import { Mastra } from "@mastra/core/mastra";
+import { DefaultStorage } from "@mastra/core/storage/libsql";
 
 const mastra = new Mastra({
   storage: new DefaultStorage({
@@ -287,12 +290,13 @@ const mastra = new Mastra({
       // 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`
@@ -308,7 +312,7 @@ npm install @mastra/upstash
 ```
 
 ```typescript
-import { Mastra } from '@mastra/core/mastra';
+import { Mastra } from "@mastra/core/mastra";
 import { UpstashStore } from "@mastra/upstash";
 
 const mastra = new Mastra({
@@ -318,6 +322,7 @@ const mastra = new Mastra({
   }),
 });
 ```
+
 ### Storage Considerations
 
 - All storage options support suspend and resume functionality identically
@@ -333,24 +338,22 @@ To handle suspended workflows, use the `watch` method to monitor workflow status
 import { mastra } from "./index";
 
 // Get the workflow
-const myWorkflow = mastra.getWorkflow('myWorkflow');
+const myWorkflow = mastra.getWorkflow("myWorkflow");
 const { start, watch, resume } = myWorkflow.createRun();
 
 // Start watching the workflow before executing it
-watch(async ({ context, activePaths }) => {
-  for (const _path of activePaths) {
-    const stepTwoStatus = context.steps?.stepTwo?.status;
-    if (stepTwoStatus === 'suspended') {
-      console.log("Workflow suspended, resuming with new value");
-
-      // Resume the workflow with new context
-      await resume({
-        stepId: 'stepTwo',
-        context: { secondValue: 100 },
-      });
-    }
+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 } });
@@ -364,25 +367,25 @@ You can use the same watching pattern with event-based workflows:
 const { start, watch, resumeWithEvent } = workflow.createRun();
 
 // Watch for suspended event steps
-watch(async ({ context, activePaths }) => {
-  for (const path of activePaths) {
-    if (path.stepId === '__approvalReceived_event' && path.status === 'suspended') {
-      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
-    }
+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' } });
+await start({ triggerData: { requestId: "auto-123" } });
 ```
 
 ## Further Reading