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

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/overview.mdx

@@ -0,0 +1,203 @@
+---
+title: "Handling Complex LLM Operations | Workflows | Mastra"
+description: "Workflows in Mastra help you orchestrate complex sequences of operations with features like branching, parallel execution, resource suspension, and more."
+---
+
+# Handling Complex LLM Operations with Workflows
+
+Workflows in Mastra help you orchestrate complex sequences of operations with features like branching, parallel execution, resource suspension, and more.
+
+## When to use workflows
+
+Most AI applications need more than a single call to a language model. You may want to run multiple steps, conditionally skip certain paths, or even pause execution altogether until you receive user input. Sometimes your agent tool calling is not accurate enough.
+
+Mastra's workflow system provides:
+
+- A standardized way to define steps and link them together.
+- Support for both simple (linear) and advanced (branching, parallel) paths.
+- Debugging and observability features to track each workflow run.
+
+## Example
+
+To create a workflow, you define one or more steps, link them, and then commit the workflow before starting it.
+
+### Breaking Down the Workflow
+
+Let's examine each part of the workflow creation process:
+
+#### 1. Creating the Workflow
+
+Here's how you define a workflow in Mastra. The `name` field determines the workflow's API endpoint (`/workflows/$NAME/`), while the `triggerSchema` defines the structure of the workflow's trigger data:
+
+```ts filename="src/mastra/workflow/index.ts"
+const myWorkflow = new Workflow({
+  name: "my-workflow",
+  triggerSchema: z.object({
+    inputValue: z.number(),
+  }),
+});
+```
+
+#### 2. Defining Steps
+
+Now, we'll define the workflow's steps. Each step can have its own input and output schemas. Here, `stepOne` doubles an input value, and `stepTwo` increments that result if `stepOne` was successful. (To keep things simple, we aren't making any LLM calls in this example):
+
+```ts filename="src/mastra/workflow/index.ts"
+const stepOne = new Step({
+  id: "stepOne",
+  outputSchema: z.object({
+    doubledValue: z.number(),
+  }),
+  execute: async ({ context }) => {
+    const doubledValue = context.triggerData.inputValue * 2;
+    return { doubledValue };
+  },
+});
+
+const stepTwo = new Step({
+  id: "stepTwo",
+  execute: async ({ context }) => {
+    const doubledValue = context.getStepResult(stepOne)?.doubledValue;
+    if (!doubledValue) {
+      return { incrementedValue: 0 };
+    }
+    return {
+      incrementedValue: doubledValue + 1,
+    };
+  },
+});
+```
+
+#### 3. Linking Steps
+
+Now, let's create the control flow, and "commit" (finalize the workflow). In this case, `stepOne` runs first and is followed by `stepTwo`.
+
+```ts filename="src/mastra/workflow/index.ts"
+myWorkflow.step(stepOne).then(stepTwo).commit();
+```
+
+### Register the Workflow
+
+Register your workflow with Mastra to enable logging and telemetry:
+
+```ts showLineNumbers filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  workflows: { myWorkflow },
+});
+```
+
+The workflow can also have the mastra instance injected into the context in the case where you need to create dynamic workflows:
+
+```ts filename="src/mastra/workflow/index.ts"
+import { Mastra } from "@mastra/core";
+
+const mastra = new Mastra();
+
+const myWorkflow = new Workflow({
+  name: "my-workflow",
+  mastra,
+});
+```
+
+### Executing the Workflow
+
+Execute your workflow programmatically or via API:
+
+```ts showLineNumbers filename="src/mastra/run-workflow.ts" copy
+import { mastra } from "./index";
+
+// Get the workflow
+const myWorkflow = mastra.getWorkflow("myWorkflow");
+const { runId, start } = myWorkflow.createRun();
+
+// Start the workflow execution
+await start({ triggerData: { inputValue: 45 } });
+```
+
+Or use the API (requires running `mastra dev`):
+
+// Create workflow run
+
+```bash
+curl --location 'http://localhost:4111/api/workflows/myWorkflow/start-async' \
+     --header 'Content-Type: application/json' \
+     --data '{
+       "inputValue": 45
+     }'
+```
+
+This example shows the essentials: define your workflow, add steps, commit the workflow, then execute it.
+
+## Defining Steps
+
+The basic building block of a workflow [is a step](./steps.mdx). Steps are defined using schemas for inputs and outputs, and can fetch prior step results.
+
+## Control Flow
+
+Workflows let you define a [control flow](./control-flow.mdx) to chain steps together in with parallel steps, branching paths, and more.
+
+## Workflow Variables
+
+When you need to map data between steps or create dynamic data flows, [workflow variables](./variables.mdx) provide a powerful mechanism for passing information from one step to another and accessing nested properties within step outputs.
+
+## Suspend and Resume
+
+When you need to pause execution for external data, user input, or asynchronous events, Mastra [supports suspension at any step](./suspend-and-resume.mdx), persisting the state of the workflow so you can resume it later.
+
+## Observability and Debugging
+
+Mastra workflows automatically [log the input and output of each step within a workflow run](../../reference/observability/otel-config.mdx), allowing you to send this data to your preferred logging, telemetry, or observability tools.
+
+You can:
+
+- Track the status of each step (e.g., `success`, `error`, or `suspended`).
+- Store run-specific metadata for analysis.
+- Integrate with third-party observability platforms like Datadog or New Relic by forwarding logs.
+
+## Injecting Request/User-Specific Variables
+
+We support dependency injection for tools and workflows. You can pass a container directly to your `start` or `resume` function calls, or inject it using [server middleware](/docs/deployment/server#Middleware).
+
+```ts showLineNumbers filename="src/mastra/run-workflow.ts" copy
+import { mastra } from "./index";
+
+const stepTwo = new Step({
+  id: "stepTwo",
+  execute: async ({ context, container }) => {
+    const multiplier = (container.get("multiplier");
+    const doubledValue = context.getStepResult(stepOne)?.doubledValue;
+    if (!doubledValue) {
+      return { incrementedValue: 0 };
+    }
+
+    return {
+      incrementedValue: doubledValue * multiplier,
+    };
+  },
+});
+
+// Get the workflow
+const myWorkflow = mastra.getWorkflow("myWorkflow");
+const { runId, start, resume } = myWorkflow.createRun();
+
+type MyContainer = { multiplier; number };
+
+const container = new Container<MyContainer>();
+container.set("multiplier", 5);
+
+// Start the workflow execution
+await start({ triggerData: { inputValue: 45 }, container });
+await resume({ stepId: "stepTwo", container });
+```
+
+## More Resources
+
+- 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)
+- [Workflow Variables example](../../examples/workflows/workflow-variables.mdx)
+- [Cyclical Dependencies workflow example](../../examples/workflows/cyclical-dependencies.mdx)
+- [Suspend and Resume workflow example](../../examples/workflows/suspend-and-resume.mdx)

package/.docs/raw/workflows/steps.mdx

@@ -0,0 +1,108 @@
+---
+title: "Creating Steps and Adding to Workflows | Mastra Docs"
+description: "Steps in Mastra workflows provide a structured way to manage operations by defining inputs, outputs, and execution logic."
+---
+
+# Defining Steps in a Workflow
+
+When you build a workflow, you typically break down operations into smaller tasks that can be linked and reused. Steps provide a structured way to manage these tasks by defining inputs, outputs, and execution logic.
+
+The code below shows how to define these steps inline or separately.
+
+## Inline Step Creation
+
+You can create steps directly within your workflow using `.step()` and `.then()`. This code shows how to define, link, and execute two steps in sequence.
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+import { Step, Workflow, Mastra } from "@mastra/core";
+import { z } from "zod";
+
+export const myWorkflow = new Workflow({
+  name: "my-workflow",
+  triggerSchema: z.object({
+    inputValue: z.number(),
+  }),
+});
+
+myWorkflow
+  .step(
+    new Step({
+      id: "stepOne",
+      outputSchema: z.object({
+        doubledValue: z.number(),
+      }),
+      execute: async ({ context }) => ({
+        doubledValue: context.triggerData.inputValue * 2,
+      }),
+    }),
+  )
+  .then(
+    new Step({
+      id: "stepTwo",
+      outputSchema: z.object({
+        incrementedValue: z.number(),
+      }),
+      execute: async ({ context }) => {
+        if (context.steps.stepOne.status !== "success") {
+          return { incrementedValue: 0 };
+        }
+
+        return { incrementedValue: context.steps.stepOne.output.doubledValue + 1 };
+      },
+    }),
+  ).commit();
+
+  // Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { myWorkflow },
+  });
+```
+
+## Creating Steps Separately
+
+If you prefer to manage your step logic in separate entities, you can define steps outside and then add them to your workflow. This code shows how to define steps independently and link them afterward.
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+import { Step, Workflow, Mastra } from "@mastra/core";
+import { z } from "zod";
+
+// Define steps separately
+const stepOne = new Step({
+  id: "stepOne",
+  outputSchema: z.object({
+    doubledValue: z.number(),
+  }),
+  execute: async ({ context }) => ({
+    doubledValue: context.triggerData.inputValue * 2,
+  }),
+});
+
+const stepTwo = new Step({
+  id: "stepTwo",
+  outputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  execute: async ({ context }) => {
+    if (context.steps.stepOne.status !== "success") {
+      return { incrementedValue: 0 };
+    }
+    return { incrementedValue: context.steps.stepOne.output.doubledValue + 1 };
+  },
+});
+
+// Build the workflow
+const myWorkflow = new Workflow({
+  name: "my-workflow",
+  triggerSchema: z.object({
+    inputValue: z.number(),
+  }),
+});
+
+myWorkflow.step(stepOne).then(stepTwo);
+myWorkflow.commit();
+
+// Register the workflow with Mastra
+export const mastra = new Mastra({
+  workflows: { myWorkflow },
+});
+```