@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

package/.docs/raw/reference/workflows/step.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Step Class | Workflows"
 description: Documentation for the Step class in Mastra, which defines individual units of work within a workflow.
+packages:
+  - "@mastra/core"
 ---
 
 # Step Class
@@ -10,7 +12,7 @@ It can take either a tool or an agent as a parameter to automatically create a s
 
 ## Usage example
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -32,6 +34,57 @@ const step1 = createStep({
 });
 ```
 
+## Creating steps from agents
+
+You can create a step directly from an agent. The step will use the agent's name as its ID.
+
+### Basic agent step
+
+```typescript title="src/mastra/workflows/test-workflow.ts"
+import { testAgent } from "../agents/test-agent";
+
+const agentStep = createStep(testAgent);
+// inputSchema: { prompt: string }
+// outputSchema: { text: string }
+```
+
+### Agent step with structured output
+
+Pass `structuredOutput` to have the agent return typed structured data:
+
+```typescript title="src/mastra/workflows/test-workflow.ts"
+const articleSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  tags: z.array(z.string()),
+});
+
+const agentStep = createStep(testAgent, {
+  structuredOutput: { schema: articleSchema },
+});
+// inputSchema: { prompt: string }
+// outputSchema: { title: string, summary: string, tags: string[] }
+```
+
+### Agent step options
+
+<PropertiesTable
+  content={[
+    {
+      name: "structuredOutput",
+      type: "{ schema: z.ZodType<any> }",
+      description: "When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.",
+      required: false,
+    },
+    {
+      name: "onFinish",
+      type: "(result: AgentResult) => void",
+      description: "Callback invoked when the agent completes generation.",
+      required: false,
+    },
+  ]}
+/>
+
 ## Constructor Parameters
 
 <PropertiesTable
@@ -155,10 +208,10 @@ const step1 = createStep({
         "Request Context for dependency injection and contextual information.",
     },
     {
-      name: "runCount",
+      name: "retryCount",
       type: "number",
       description:
-        "The run count for this specific step, it automatically increases each time the step runs",
+        "The retry count for this specific step, it automatically increases each time the step is retried",
       isOptional: true,
     },
   ]}

package/.docs/raw/reference/workflows/workflow-methods/branch.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.branch() | Workflows"
 description: Documentation for the `Workflow.branch()` method in workflows, which creates conditional branches between steps.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.branch()
@@ -9,7 +11,7 @@ The `.branch()` method creates conditional branches between workflow steps, allo
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.branch([
   [async ({ context }) => true, step1],
   [async ({ context }) => false, step2],

package/.docs/raw/reference/workflows/workflow-methods/commit.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.commit() | Workflows"
 description: Documentation for the `Workflow.commit()` method in workflows, which finalizes the workflow and returns the final result.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.commit()
@@ -9,7 +11,7 @@ The `.commit()` method finalizes the workflow and returns the final result.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.then(step1).commit();
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.createRun() | Workflows"
 description: Documentation for the `Workflow.createRun()` method in workflows, which creates a new workflow run instance.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.createRun()
@@ -9,7 +11,7 @@ The `.createRun()` method creates a new workflow run instance, allowing you to e
 
 ## Usage example
 
-```typescript copy
+```typescript
 await workflow.createRun();
 ```
 
@@ -23,6 +25,18 @@ await workflow.createRun();
       description: "Optional custom identifier for the workflow run",
       isOptional: true,
     },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Optional identifier to associate the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the workflow run and can be used for filtering and querying runs.",
+      isOptional: true,
+    },
+    {
+      name: "disableScorers",
+      type: "boolean",
+      description: "Optional flag to disable scorers for this workflow run",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -41,7 +55,7 @@ await workflow.createRun();
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 const workflow = mastra.getWorkflow("workflow");
 
 const run = await workflow.createRun();
@@ -53,6 +67,29 @@ const result = await run.start({
 });
 ```
 
+## Using resourceId
+
+The `resourceId` parameter associates a workflow run with a specific resource, such as a user or tenant. This is useful for multi-tenant applications or when you need to track which user initiated a workflow.
+
+```typescript
+const workflow = mastra.getWorkflow("workflow");
+
+// Create a run associated with a specific user
+const run = await workflow.createRun({
+  resourceId: "user-123",
+});
+
+const result = await run.start({
+  inputData: {
+    value: 10,
+  },
+});
+
+// Later, retrieve the run and access the resourceId
+const storedRun = await workflow.getWorkflowRunById(run.runId);
+console.log(storedRun.resourceId); // "user-123"
+```
+
 ## Related
 
 - [Run Class](../run)

package/.docs/raw/reference/workflows/workflow-methods/dountil.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.dountil() | Workflows"
 description: Documentation for the `Workflow.dountil()` method in workflows, which creates a loop that executes a step until a condition is met.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.dountil()
@@ -9,7 +11,7 @@ The `.dountil()` method executes a step until a condition is met. It always runs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.dountil(step1, async ({ inputData }) => true);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/dowhile.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.dowhile() | Workflows"
 description: Documentation for the `Workflow.dowhile()` method in workflows, which creates a loop that executes a step while a condition is met.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.dowhile()
@@ -9,7 +11,7 @@ The `.dowhile()` method executes a step while a condition is met. It always runs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.dowhile(step1, async ({ inputData }) => true);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx

@@ -1,15 +1,17 @@
 ---
 title: "Reference: Workflow.foreach() | Workflows"
 description: Documentation for the `Workflow.foreach()` method in workflows, which creates a loop that executes a step for each item in an array.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.foreach()
 
-The `.foreach()` method creates a loop that executes a step for each item in an array.
+The `.foreach()` method creates a loop that executes a step for each item in an array. It always returns an array containing the output from each iteration, preserving the original order.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.foreach(step1, { concurrency: 2 });
 ```
 
@@ -50,11 +52,76 @@ workflow.foreach(step1, { concurrency: 2 });
     {
       name: "workflow",
       type: "Workflow",
-      description: "The workflow instance for method chaining",
+      description: "The workflow instance for method chaining. The output type is an array of the step's output type.",
     },
   ]}
 />
 
+## Behavior
+
+### Execution and waiting
+
+The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
+
+If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](/docs/v1/workflows/control-flow#nested-workflows-inside-foreach) for examples.
+
+### Output structure
+
+`.foreach()` always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.
+
+```typescript
+// Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
+// Step adds 10 to each value
+// Output: [{ value: 11 }, { value: 12 }, { value: 13 }]
+```
+
+### Using `.then()` after `.foreach()`
+
+When you chain `.then()` after `.foreach()`, the next step receives the entire output array as its input. This allows you to aggregate or process all results together.
+
+```typescript
+workflow
+  .foreach(processItemStep)    // Output: array of processed items
+  .then(aggregateStep)         // Input: the entire array
+  .commit();
+```
+
+### Using `.map()` after `.foreach()`
+
+Use `.map()` to transform the array output before passing it to the next step:
+
+```typescript
+workflow
+  .foreach(processItemStep)
+  .map(async ({ inputData }) => ({
+    total: inputData.reduce((sum, item) => sum + item.value, 0),
+    count: inputData.length
+  }))
+  .then(nextStep)
+  .commit();
+```
+
+### Chaining multiple `.foreach()` calls
+
+When you chain `.foreach()` calls, each operates on the array from the previous step:
+
+```typescript
+workflow
+  .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
+  .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
+  .commit();
+```
+
+If a step inside `.foreach()` returns an array, the output becomes an array of arrays. Use `.map()` with `.flat()` to flatten:
+
+```typescript
+workflow
+  .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
+  .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]
+  .foreach(embedStep)
+  .commit();
+```
+
 ## Related
 
-- [Repeating with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)
+- [Looping with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)

package/.docs/raw/reference/workflows/workflow-methods/map.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.map() | Workflows"
 description: Documentation for the `Workflow.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.map()
@@ -9,7 +11,7 @@ The `.map()` method maps output data from a previous step to the input of a subs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.map(async ({ inputData }) => `${inputData.value} - map`
 ```
 
@@ -43,7 +45,7 @@ workflow.map(async ({ inputData }) => `${inputData.value} - map`
 
 Use `inputData` to access the full output of the previous step.
 
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(({ inputData }) => {
     console.log(inputData);
@@ -54,7 +56,7 @@ Use `inputData` to access the full output of the previous step.
 
 Use `getStepResult()` to access the full output of a specific step by referencing the step's instance.
 
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getStepResult }) => {
     console.log(getStepResult(step1));
@@ -65,7 +67,7 @@ Use `getStepResult()` to access the full output of a specific step by referencin
 
 Use `getInitData()` to access the initial input data provided to the workflow.
 
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getInitData }) => {
       console.log(getInitData());
@@ -77,7 +79,7 @@ Use `getInitData()` to access the initial input data provided to the workflow.
 The object form of `.map()` provides an alternative declarative syntax for mapping fields. Instead of writing a function, you define an object where each key is a new field name and each value uses `mapVariable()` to extract data from previous steps or workflow input.
 Import `mapVariable()` from the workflows module:
 
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript filename="src/mastra/workflows/test-workflow.ts"
 import { mapVariable } from "@mastra/core/workflows";
 ```
 
@@ -86,7 +88,7 @@ import { mapVariable } from "@mastra/core/workflows";
 Use `mapVariable()` with `step` to extract a specific field from a step's output and map it to a new field name. The `path` parameter specifies which field to extract.
 In this example, the `value` field from `step1`'s output is extracted and mapped to a new field called `details`:
 
-```typescript {3-6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3-6} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map({
     details: mapVariable({
@@ -101,7 +103,7 @@ In this example, the `value` field from `step1`'s output is extracted and mapped
 Use `mapVariable()` with `initData` to extract a specific field from the workflow's initial input data. This is useful when you need to pass the original workflow input to a later step.
 In this example, the `value` field from the workflow's input is extracted and mapped to a field called `details`:
 
-```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts"
 export const testWorkflow = createWorkflow({...});
 
 testWorkflow

package/.docs/raw/reference/workflows/workflow-methods/parallel.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.parallel() | Workflows"
 description: Documentation for the `Workflow.parallel()` method in workflows, which executes multiple steps in parallel.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.parallel()
@@ -9,7 +11,7 @@ The `.parallel()` method executes multiple steps in parallel.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.parallel([step1, step2]);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/sleep.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.sleep() | Workflows"
 description: Documentation for the `Workflow.sleep()` method in workflows, which pauses execution for a specified number of milliseconds.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.sleep()
@@ -9,7 +11,7 @@ The `.sleep()` method pauses execution for a specified number of milliseconds. I
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.sleep(5000);
 ```
 
@@ -41,7 +43,7 @@ workflow.sleep(5000);
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 
 const step1 = createStep({...});
@@ -56,7 +58,3 @@ export const testWorkflow = createWorkflow({...})
   .then(step2)
   .commit();
 ```
-
-## Related
-
-- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume#sleep--events)

package/.docs/raw/reference/workflows/workflow-methods/sleepUntil.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.sleepUntil() | Workflows"
 description: Documentation for the `Workflow.sleepUntil()` method in workflows, which pauses execution until a specified date.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.sleepUntil()
@@ -9,7 +11,7 @@ The `.sleepUntil()` method pauses execution until a specified date.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.sleepUntil(new Date(Date.now() + 5000));
 ```
 
@@ -41,7 +43,7 @@ workflow.sleepUntil(new Date(Date.now() + 5000));
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 
 const step1 = createStep({...});
@@ -56,7 +58,3 @@ export const testWorkflow = createWorkflow({...})
   .then(step2)
   .commit();
 ```
-
-## Related
-
-- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume#sleep--events)

package/.docs/raw/reference/workflows/workflow-methods/then.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow.then() | Workflows"
 description: Documentation for the `Workflow.then()` method in workflows, which creates sequential dependencies between steps.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow.then()
@@ -9,7 +11,7 @@ The `.then()` method creates a sequential dependency between workflow steps, ens
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.then(step1).then(step2);
 ```