@mastra/mcp-docs-server 0.13.37 → 0.13.39-alpha.0

package/.docs/raw/workflows/overview.mdx

@@ -1,22 +1,21 @@
 ---
-title: "Handling Complex LLM Operations | Workflows | Mastra"
+title: "Workflows overview | Workflows | Mastra Docs"
 description: "Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more."
 ---
 
-import { Steps, Callout, Tabs } from "nextra/components";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 # Workflows overview
 
 Workflows let you define complex sequences of tasks using clear, structured steps rather than relying on the reasoning of a single agent. They give you full control over how tasks are broken down, how data moves between them, and what gets executed when.
 
-![Workflows overview](/image/workflows/workflows-overview.jpg)
+![Workflows overview](/img/workflows/workflows-overview.jpg)
 
 ## When to use workflows
 
 Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
 
-
-
 > **📹 Watch**:  → An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
 ## Core principles
@@ -33,7 +32,7 @@ Steps are the building blocks of workflows. Create a step using `createStep()` w
 
 The `execute` function defines what the step does. Use it to call functions in your codebase, external APIs, agents, or tools.
 
-```typescript {6,9,15} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {6,9,15} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createStep } from "@mastra/core/workflows";
 
 const step1 = createStep({
@@ -54,17 +53,17 @@ const step1 = createStep({
 });
 ```
 
-> See the [Step Class](../../reference/workflows/step.mdx) for a full list of configuration options.
+> See the [Step Class](/reference/workflows/step) for a full list of configuration options.
 
 ### Using agents and tools
 
-Workflow steps can also call registered agents or import and execute tools directly, visit the [Agents and Tools](./agents-and-tools.mdx) page for more information.
+Workflow steps can also call registered agents or import and execute tools directly, visit the [Using Tools](/docs/agents/using-tools) page for more information.
 
 ## Creating a workflow
 
 Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. Add steps using `.then()` and complete the workflow with `.commit()`.
 
-```typescript {9,12,15,16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {9,12,15,16} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -81,42 +80,93 @@ export const testWorkflow = createWorkflow({
 })
   .then(step1)
   .commit();
-
 ```
 
-> See the [Workflow Class](../../reference/workflows/workflow.mdx) for a full list of configuration options.
+> See the [Workflow Class](/reference/workflows/workflow) for a full list of configuration options.
 
 ### Understanding control flow
 
-Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured. Visit the [Control Flow](./control-flow.mdx) page for more information.
+Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured. Visit the [Control Flow](/docs/workflows/control-flow) page for more information.
 
-#### Composing workflow steps
+## Workflow state
 
-When using `.then()`, steps run sequentially. Each step’s `inputSchema` must match the `outputSchema` of the previous step. The final step’s `outputSchema` should match the workflow’s `outputSchema` to ensure end-to-end type safety.
+Workflow state lets you share values across steps without passing them through every step’s inputSchema and outputSchema. All state values are defined in the workflow’s stateSchema, but each step only declares the values it needs. To set initial values, use initialState when running the workflow.
 
-```typescript {4,7,14,17,24,27} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
-  //...
-  inputSchema: z.object({
-    message: z.string()
+  // ...
+  stateSchema: z.object({
+    processedItems: z.array(z.string()),
   }),
-  outputSchema: z.object({
-    formatted: z.string()
-  })
+  execute: async ({ inputData, state, setState }) => {
+    const { message } = inputData;
+    const { processedItems } = state;
+
+    setState({
+      ...state,
+      processedItems: [...processedItems, "item-1", "item-2"],
+    });
+
+    return {
+      formatted: message.toUpperCase(),
+    };
+  },
 });
 
 const step2 = createStep({
   // ...
+  stateSchema: z.object({
+    metadata: z.object({
+      processedBy: z.string(),
+    }),
+  }),
+  execute: async ({ inputData, state }) => {
+    const { formatted } = inputData;
+    const { metadata } = state;
+
+    return {
+      emphasized: `${formatted}!! ${metadata.processedBy}`,
+    };
+  },
+});
+
+export const testWorkflow = createWorkflow({
+  // ...
+  stateSchema: z.object({
+    processedItems: z.array(z.string()),
+    metadata: z.object({
+      processedBy: z.string(),
+    }),
+  }),
+})
+  .then(step1)
+  .then(step2)
+  .commit();
+```
+
+## Workflows as steps
+
+Use a workflow as a step to reuse its logic within a larger composition. Input and output follow the same schema rules described in [Core principles](/docs/workflows/control-flow).
+
+```typescript {26} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+const childWorkflow = createWorkflow({
+  id: "child-workflow",
   inputSchema: z.object({
-    formatted: z.string()
+    message: z.string()
   }),
   outputSchema: z.object({
     emphasized: z.string()
   })
-});
+})
+  .then(step1)
+  .then(step2)
+  .commit();
 
 export const testWorkflow = createWorkflow({
-  // ...
+  id: "test-workflow",
   inputSchema: z.object({
     message: z.string()
   }),
@@ -124,16 +174,33 @@ export const testWorkflow = createWorkflow({
     emphasized: z.string()
   })
 })
+  .then(childWorkflow)
+  .commit();
+```
+
+### Cloning a workflow
+
+Clone a workflow using `cloneWorkflow()` when you want to reuse its logic but track it separately under a new ID. Each clone runs independently and appears as a distinct workflow in logs and observability tools.
+
+```typescript {6} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { cloneWorkflow } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+
+const parentWorkflow = createWorkflow({...})
+const clonedWorkflow = cloneWorkflow(parentWorkflow, { id: "cloned-workflow" });
+
+export const testWorkflow = createWorkflow({...})
   .then(step1)
-  .then(step2)
+  .then(clonedWorkflow)
   .commit();
 ```
 
-### Registering a workflow
+## Registering a workflow
 
 Register your workflow in the Mastra instance to make it available throughout your application. Once registered, it can be called from agents or tools and has access to shared resources such as logging and observability features:
 
-```typescript {6} filename="src/mastra/index.ts" showLineNumbers copy
+```typescript {6} title="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
 import { testWorkflow } from "./workflows/test-workflow";
 
@@ -150,20 +217,16 @@ You can run workflows from agents, tools, the Mastra Client, or the command line
 ```typescript showLineNumbers copy
 const testWorkflow = mastra.getWorkflow("testWorkflow");
 ```
-<Callout type="info">
-  <p>
-    `mastra.getWorkflow()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
-  </p>
-</Callout>
-
-> See [Running Workflows](../../examples/workflows/running-workflows.mdx) for more information.
+:::info
+`mastra.getWorkflow()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
+:::
 
 ## Running workflows
 
 Workflows can be run in two modes: start waits for all steps to complete before returning, and stream emits events during execution. Choose the approach that fits your use case: start when you only need the final result, and stream when you want to monitor progress or trigger actions as steps complete.
 
-<Tabs items={["Start", "Stream"]}>
-  <Tabs.Tab>
+<Tabs>
+  <TabItem value="start" label="Start">
 Create a workflow run instance using `createRunAsync()`, then call `.start()` with `inputData` matching the workflow's `inputSchema`. The workflow executes all steps and returns the final result.
 
 ```typescript showLineNumbers copy
@@ -177,8 +240,8 @@ const result = await run.start({
 
 console.log(result);
 ```
-  </Tabs.Tab>
-  <Tabs.Tab>
+  </TabItem>
+  <TabItem value="stream" label="Stream">
 Create a workflow run instance using `.createRunAsync()`, then call `.stream()` with `inputData` matching the workflow's `inputSchema`. The workflow emits events as each step executes, which you can iterate over to track progress.
 
 ```typescript showLineNumbers copy
@@ -194,7 +257,7 @@ for await (const chunk of result.stream) {
   console.log(chunk);
 }
 ```
-  </Tabs.Tab>
+  </TabItem>
 </Tabs>
 
 ## Workflow output
@@ -236,9 +299,9 @@ The workflow output includes the full execution lifecycle, showing the input and
 
 ## Using `RuntimeContext`
 
-Use [RuntimeContext](../server-db/runtime-context.mdx) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+Use [RuntimeContext](/docs/server-db/runtime-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
@@ -257,23 +320,12 @@ const step1 = createStep({
 });
 ```
 
-> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
+> See [Runtime Context](/docs/server-db/runtime-context) for more information.
 
-## Testing with Mastra Playground
+## Testing with Studio
 
-Use the Mastra [Playground](../server-db/local-dev-playground.mdx) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
+Use [Studio](/docs/getting-started/studio) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
 
 ## Related
 
-For a closer look at workflows, see our [Workflow Guide](../../guides/guide/ai-recruiter.mdx), which walks through the core concepts with a practical example.
-
-- [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)
-- [Conditional Branching workflow example](../../examples/workflows/conditional-branching.mdx)
-- [Inngest workflow example](../../examples/workflows/inngest-workflow.mdx)
-- [Suspend and Resume workflow example](../../examples/workflows/human-in-the-loop.mdx)
-
-
-## Workflows (Legacy)
-
-For legacy workflow documentation, see [Workflows (Legacy)](../workflows-legacy/overview.mdx).
-
+For a closer look at workflows, see our [Workflow Guide](/guides/guide/ai-recruiter), which walks through the core concepts with a practical example.

package/.docs/raw/workflows/snapshots.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Snapshots | Mastra Docs"
+title: "Snapshots | Workflows | Mastra Docs"
 description: "Learn how to save and resume workflow execution state with snapshots in Mastra"
 ---
 
@@ -33,19 +33,30 @@ This mechanism provides a powerful way to implement human-in-the-loop workflows,
 
 Each snapshot includes the `runId`, input, step status (`success`, `suspended`, etc.), any suspend and resume payloads, and the final output. This ensures full context is available when resuming execution.
 
-
 ```json
 {
   "runId": "34904c14-e79e-4a12-9804-9655d4616c50",
   "status": "success",
   "value": {},
   "context": {
-    "input": { "value": 100, "user": "Michael", "requiredApprovers": ["manager", "finance"] },
+    "input": {
+      "value": 100,
+      "user": "Michael",
+      "requiredApprovers": ["manager", "finance"]
+    },
     "approval-step": {
-      "payload": { "value": 100, "user": "Michael", "requiredApprovers": ["manager", "finance"] },
+      "payload": {
+        "value": 100,
+        "user": "Michael",
+        "requiredApprovers": ["manager", "finance"]
+      },
       "startedAt": 1758027577955,
       "status": "success",
-      "suspendPayload": { "message": "Workflow suspended", "requestedBy": "Michael", "approvers": ["manager", "finance"] },
+      "suspendPayload": {
+        "message": "Workflow suspended",
+        "requestedBy": "Michael",
+        "approvers": ["manager", "finance"]
+      },
       "suspendedAt": 1758027578065,
       "resumePayload": { "confirm": true, "approver": "manager" },
       "resumedAt": 1758027578517,
@@ -54,7 +65,15 @@ Each snapshot includes the `runId`, input, step status (`success`, `suspended`,
     }
   },
   "activePaths": [],
-  "serializedStepGraph": [{ "type": "step", "step": { "id": "approval-step", "description": "Accepts a value, waits for confirmation" } }],
+  "serializedStepGraph": [
+    {
+      "type": "step",
+      "step": {
+        "id": "approval-step",
+        "description": "Accepts a value, waits for confirmation"
+      }
+    }
+  ],
   "suspendedPaths": {},
   "waitingPaths": {},
   "result": { "value": 100, "approved": true },
@@ -68,10 +87,10 @@ Each snapshot includes the `runId`, input, step status (`success`, `suspended`,
 Snapshots are saved to the configured storage system. By default, they use LibSQL, but you can configure Upstash or PostgreSQL instead. Each snapshot is saved in the `workflow_snapshots` table and identified by the workflow’s `runId`.
 
 Read more about:
-- [LibSQL Storage](../../reference/storage/libsql.mdx)
-- [Upstash Storage](../../reference/storage/upstash.mdx)
-- [PostgreSQL Storage](../../reference/storage/postgresql.mdx)
 
+- [LibSQL Storage](/reference/storage/libsql)
+- [Upstash Storage](/reference/storage/upstash)
+- [PostgreSQL Storage](/reference/storage/postgresql)
 
 ### Saving snapshots
 
@@ -93,13 +112,12 @@ When a workflow is resumed, Mastra retrieves the persisted snapshot with these s
 4. The workflow execution is recreated with the snapshot state
 5. The suspended step is resumed, and execution continues
 
-
 ```typescript
 const storage = mastra.getStorage();
 
 const snapshot = await storage!.loadWorkflowSnapshot({
   runId: "<run-id>",
-  workflowName: "<workflow-id>"
+  workflowName: "<workflow-id>",
 });
 
 console.log(snapshot);
@@ -113,15 +131,15 @@ Snapshots are persisted using a `storage` instance configured on the `Mastra` cl
 
 This example demonstrates how to use snapshots with LibSQL.
 
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
   // ...
   storage: new LibSQLStore({
-    url: ":memory:"
-  })
+    url: ":memory:",
+  }),
 });
 ```
 
@@ -129,7 +147,7 @@ export const mastra = new Mastra({
 
 This example demonstrates how to use snapshots with Upstash.
 
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
 import { UpstashStore } from "@mastra/upstash";
 
@@ -137,24 +155,24 @@ export const mastra = new Mastra({
   // ...
   storage: new UpstashStore({
     url: "<upstash-redis-rest-url>",
-    token: "<upstash-redis-rest-token>"
-  })
-})
+    token: "<upstash-redis-rest-token>",
+  }),
+});
 ```
 
 ### Postgres `@mastra/pg`
 
 This example demonstrates how to use snapshots with PostgreSQL.
 
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
 import { PostgresStore } from "@mastra/pg";
 
 export const mastra = new Mastra({
   // ...
   storage: new PostgresStore({
-    connectionString: "<database-url>"
-  })
+    connectionString: "<database-url>",
+  }),
 });
 ```
 
@@ -170,7 +188,7 @@ export const mastra = new Mastra({
 
 You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
 
-```typescript {30-34} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {30-34} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -180,20 +198,20 @@ const approvalStep = createStep({
   inputSchema: z.object({
     value: z.number(),
     user: z.string(),
-    requiredApprovers: z.array(z.string())
+    requiredApprovers: z.array(z.string()),
   }),
   suspendSchema: z.object({
     message: z.string(),
     requestedBy: z.string(),
-    approvers: z.array(z.string())
+    approvers: z.array(z.string()),
   }),
   resumeSchema: z.object({
     confirm: z.boolean(),
-    approver: z.string()
+    approver: z.string(),
   }),
   outputSchema: z.object({
     value: z.number(),
-    approved: z.boolean()
+    approved: z.boolean(),
   }),
   execute: async ({ inputData, resumeData, suspend }) => {
     const { value, user, requiredApprovers } = inputData;
@@ -203,15 +221,15 @@ const approvalStep = createStep({
       return await suspend({
         message: "Workflow suspended",
         requestedBy: user,
-        approvers: [...requiredApprovers]
+        approvers: [...requiredApprovers],
       });
     }
 
     return {
       value,
-      approved: confirm
+      approved: confirm,
     };
-  }
+  },
 });
 ```
 
@@ -228,8 +246,8 @@ const result = await run.start({
   inputData: {
     value: 100,
     user: "Michael",
-    requiredApprovers: ["manager", "finance"]
-  }
+    requiredApprovers: ["manager", "finance"],
+  },
 });
 
 if (result.status === "suspended") {
@@ -237,14 +255,14 @@ if (result.status === "suspended") {
     step: "approval-step",
     resumeData: {
       confirm: true,
-      approver: "manager"
-    }
+      approver: "manager",
+    },
   });
 }
 ```
 
 ## Related
 
-- [Suspend and resume](../../docs/workflows/suspend-and-resume.mdx)
-- [Human in the loop example](../../examples/workflows/human-in-the-loop.mdx)
-- [WorkflowRun.watch()](../../reference/workflows/run-methods/watch.mdx)
+- [Suspend and resume](/docs/workflows/suspend-and-resume)
+- [Human in the loop example](/examples/workflows_legacy/human-in-the-loop)
+- [WorkflowRun.watch()](/reference/workflows/run-methods/watch)