@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

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

@@ -1,298 +0,0 @@
----
-title: "Suspend & Resume Workflows | Human-in-the-Loop | Mastra Docs"
-description: "Suspend and resume in Mastra workflows allows you to pause execution while waiting for external input or resources."
----
-
-# Suspend & Resume
-
-Workflows can be paused at any step, with their current state persisted as a [snapshot](./snapshots.mdx) in storage. Execution can then be resumed from this saved snapshot when ready. Persisting the snapshot ensures the workflow state is maintained across sessions, deployments, and server restarts, essential for workflows that may remain suspended while awaiting external input or resources.
-
-Common scenarios for suspending workflows include:
-
-- Waiting for human approval or input
-- Pausing until external API resources become available
-- Collecting additional data needed for later steps
-- Rate limiting or throttling expensive operations
-- Handling event-driven processes with external triggers
-
-> **New to suspend and resume?** Watch these official video tutorials:
->
-> - **[Mastering Human-in-the-Loop with Suspend & Resume](https://youtu.be/aORuNG8Tq_k)** - Learn how to suspend workflows and accept user inputs
-> - **[Building Multi-Turn Chat Interfaces with React](https://youtu.be/UMVm8YZwlxc)** - Implement multi-turn human-involved interactions with a React chat interface
-
-## Workflow status types
-
-When running a workflow, its `status` can be one of the following:
-
-- `running` - The workflow is currently running
-- `suspended` - The workflow is suspended
-- `success` - The workflow has completed
-- `failed` - The workflow has failed
-
-## Suspending a workflow with `suspend()`
-
-To pause execution at a specific step until user input is received, use the `⁠suspend` function to temporarily halt the workflow, allowing it to resume only when the necessary data is provided.
-
-![Suspending a workflow with suspend()](/image/workflows/workflows-suspend-resume-suspend.jpg)
-
-```typescript {16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-  resumeSchema: z.object({
-    city: z.string()
-  }),
-  execute: async ({ resumeData, suspend }) => {
-    const { city } = resumeData ?? {};
-
-    if (!city) {
-      return await suspend({});
-    }
-
-    return { output: "" };
-  }
-});
-
-export const testWorkflow = createWorkflow({
-  // ...
-})
-  .then(step1)
-  .commit();
-```
-
-> For more details, check out the [Suspend workflow example](../../examples/workflows/human-in-the-loop.mdx#suspend-workflow).
-
-### Identifying suspended steps
-
-To resume a suspended workflow, inspect the `suspended` array in the result to determine which step needs input:
-
-```typescript {15} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
-
-const result = await run.start({
-  inputData: {
-    city: "London"
-  }
-});
-
-console.log(JSON.stringify(result, null, 2));
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: result.suspended[0],
-    resumeData: {
-      city: "Berlin"
-    }
-  });
-}
-```
-
-In this case, the logic resumes the first step listed in the `suspended` array. A `step` can also be defined using it's `id`, for example: 'step-1'.
-
-```json
-{
-  "status": "suspended",
-  "steps": {
-    // ...
-    "step-1": {
-      // ...
-      "status": "suspended",
-    }
-  },
-  "suspended": [
-    [
-      "step-1"
-    ]
-  ]
-}
-```
-
-> See [Run Workflow Results](./overview.mdx#run-workflow-results) for more details.
-
-## Providing user feedback with suspend
-
-When a workflow is suspended, feedback can be surfaced to the user through the `suspendSchema`. Include a reason in the `suspend` payload to explain why the workflow paused.
-
-```typescript {13,23} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({
-    value: z.string()
-  }),
-  resumeSchema: z.object({
-    confirm: z.boolean()
-  }),
-  suspendSchema: z.object({
-    reason: z.string()
-  }),
-  outputSchema: z.object({
-    value: z.string()
-  }),
-  execute: async ({ resumeData, suspend }) => {
-    const { confirm } = resumeData ?? {};
-
-    if (!confirm) {
-      return await suspend({
-        reason: "Confirm to continue"
-      });
-    }
-
-    return { value: "" };
-  }
-});
-
-export const testWorkflow = createWorkflow({
-  // ...
-})
-  .then(step1)
-  .commit();
-
-```
-
-In this case, the reason provided explains that the user must confirm to continue.
-
-```json
-{
-  "step-1": {
-    // ...
-    "status": "suspended",
-    "suspendPayload": {
-      "reason": "Confirm to continue"
-    },
-  }
-}
-```
-
-> See [Run Workflow Results](./overview.mdx#run-workflow-results) for more details.
-
-## Resuming a workflow with `resume()`
-
-A workflow can be resumed by calling `resume` and providing the required `resumeData`. You can either explicitly specify which step to resume from, or when exactly one step is suspended, omit the `step` parameter and the workflow will automatically resume that step.
-
-```typescript {16-18} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
-
-const result = await run.start({
-   inputData: {
-    city: "London"
-  }
-});
-
-console.log(JSON.stringify(result, null, 2));
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: 'step-1',
-    resumeData: {
-      city: "Berlin"
-    }
-  });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
-}
-```
-
-You can also omit the `step` parameter when exactly one step is suspended:
-
-```typescript {5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const resumedResult = await run.resume({
-  resumeData: {
-    city: "Berlin"
-  },
-  // step parameter omitted - automatically resumes the single suspended step
-});
-```
-
-You can pass `runtimeContext` as an argument to both the `start` and `resume` commands.
-
-```typescript filename="src/mastra/workflows/test-workflow.ts"
-import { RuntimeContext } from "@mastra/core/runtime-context";
-
-const runtimeContext = new RuntimeContext();
-
-const result = await run.start({
-  step: 'step-1',
-  inputData: {
-    city: "London"
-  },
-  runtimeContext
-});
-
-const resumedResult = await run.resume({
-  step: 'step-1',
-  resumeData: {
-    city: "New York"
-  },
-  runtimeContext
-});
-```
-
-> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
-
-### Resuming nested workflows
-
-To resume a suspended nested workflow pass the workflow instance to the `step` parameter of the `resume` function.
-
-```typescript {33-34} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const dowhileWorkflow = createWorkflow({
-  id: 'dowhile-workflow',
-  inputSchema: z.object({ value: z.number() }),
-  outputSchema: z.object({ value: z.number() }),
-})
-  .dountil(
-    createWorkflow({
-      id: 'simple-resume-workflow',
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      steps: [incrementStep, resumeStep],
-    })
-      .then(incrementStep)
-      .then(resumeStep)
-      .commit(),
-    async ({ inputData }) => inputData.value >= 10,
-  )
-  .then(
-    createStep({
-      id: 'final',
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      execute: async ({ inputData }) => ({ value: inputData.value }),
-    }),
-  )
-  .commit();
-
-const run = await dowhileWorkflow.createRunAsync();
-const result = await run.start({ inputData: { value: 0 } });
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    resumeData: { value: 2 },
-    step: ['simple-resume-workflow', 'resume'],
-  });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
-}
-```
-
-## Sleep & Events
-
-Workflows can also pause execution for timed delays or external events. These methods set the workflow status to `waiting` rather than `suspended`, and are useful for polling, delayed retries, or event-driven processes.
-
-**Available methods:**
-
-- [`.sleep()`](../../reference/workflows/workflow-methods/sleep.mdx): Pause for a specified number of milliseconds
-- [`.sleepUntil()`](../../reference/workflows/workflow-methods/sleepUntil.mdx) : Pause until a specific date
-- [`.waitForEvent()`](../../reference/workflows/workflow-methods/waitForEvent.mdx): Pause until an external event is received
-- [`.sendEvent()`](../../reference/workflows/workflow-methods/sendEvent.mdx) : Send an event to resume a waiting workflow

package/.docs/raw/workflows/using-with-agents-and-tools.mdx

@@ -1,350 +0,0 @@
----
-title: "Using Workflows with Agents and Tools | Workflows | Mastra Docs"
-description: "Steps in Mastra workflows provide a structured way to manage operations by defining inputs, outputs, and execution logic."
----
-
-# Agents and Tools
-
-Workflow steps are composable and typically run logic directly within the `execute` function. However, there are cases where calling an agent or tool is more appropriate. This pattern is especially useful when:
-
-- Generating natural language responses from user input using an LLM.
-- Abstracting complex or reusable logic into a dedicated tool.
-- Interacting with third-party APIs in a structured or reusable way.
-
-Workflows can use Mastra agents or tools directly as steps, for example: `createStep(testAgent)` or `createStep(testTool)`.
-
-## Using agents in workflows
-
-To include an agent in a workflow, define it in the usual way, then either add it directly to the workflow using `createStep(testAgent)` or, invoke it from within a step's `execute` function using `.generate()`.
-
-### Example agent
-
-This agent uses OpenAI to generate a fact about a city, country, and timezone.
-
-```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-
-export const testAgent = new Agent({
-  name: "test-agent",
-  description: "Create facts for a country based on the city",
-  instructions: `Return an interesting fact about the country based on the city provided`,
-  model: openai("gpt-4o")
-});
-```
-
-### Adding an agent as a step
-
-In this example, `step1` uses the `testAgent` to generate an interesting fact about the country based on a given city.
-
-The `.map` method transforms the workflow input into a `prompt` string compatible with the `testAgent`.
-
-The step is composed into the workflow using `.then()`, allowing it to receive the mapped input and return the agent's structured output. The workflow is finalized with `.commit()`.
-
-
-![Agent as step](/image/workflows/workflows-agent-tools-agent-step.jpg)
-
-
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
-
-const step1 = createStep(testAgent);
-
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  })
-})
-  .map(({ inputData }) => {
-    const { input } = inputData;
-    return {
-      prompt: `Provide facts about the city: ${input}`
-    };
-  })
-  .then(step1)
-  .commit();
-```
-
-### Calling an agent with `.generate()`
-
-In this example, the `step1` builds a prompt using the provided `input` and passes it to the `testAgent`, which returns a plain-text response containing facts about the city and its country.
-
-The step is added to the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output. The workflow is finalized with `.commit()`.
-
-```typescript {1,18, 29} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
-
-const step1 = createStep({
-  id: "step-1",
-  description: "Create facts for a country based on the city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-
-  execute: async ({ inputData }) => {
-    const { input } = inputData;
-
-    const  prompt = `Provide facts about the city: ${input}`
-
-    const { text } = await testAgent.generate([
-      { role: "user", content: prompt }
-    ]);
-
-    return {
-      output: text
-    };
-  }
-});
-
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-
-## Using tools in workflows
-
-To use a tool within a workflow, define it in the usual way, then either add it directly to the workflow using `createStep(testTool)` or, invoke it from within a step's `execute` function using `.execute()`.
-
-### Example tool
-
-The example below uses the Open Meteo API to retrieve geolocation details for a city, returning its name, country, and timezone.
-
-```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
-import { createTool } from "@mastra/core";
-import { z } from "zod";
-
-export const testTool = createTool({
-  id: "test-tool",
-  description: "Gets country for a city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    country_name: z.string()
-  }),
-  execute: async ({ context }) => {
-    const { input } = context;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${input}`);
-    const geocodingData = await geocodingResponse.json();
-
-    const { country } = geocodingData.results[0];
-
-    return {
-      country_name: country
-    };
-  }
-});
-```
-
-### Adding a tool as a step
-
-In this example, `step1` uses the `testTool`, which performs a geocoding lookup using the provided `city` and returns the resolved `country`.
-
-The step is added to the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output. The workflow is finalized with `.commit()`.
-
-![Tool as step](/image/workflows/workflows-agent-tools-tool-step.jpg)
-
-```typescript {1,3,6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testTool } from "../tools/test-tool";
-
-const step1 = createStep(testTool);
-
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-
-### Calling a tool with `.execute()`
-
-In this example, `step1` directly invokes `testTool` using its `.execute()` method. The tool performs a geocoding lookup with the provided `city` and returns the corresponding `country`.
-
-The result is returned as structured output from the step. The step is composed into the workflow using `.then()`, enabling it to process workflow input and produce typed output. The workflow is finalized with `.commit()`
-
-```typescript {3,20,32} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { RuntimeContext } from "@mastra/core/di";
-
-import { testTool } from "../tools/test-tool";
-
-const runtimeContext = new RuntimeContext();
-
-const step1 = createStep({
-  id: "step-1",
-  description: "Gets country for a city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-
-  execute: async ({ inputData }) => {
-    const { input } = inputData;
-
-    const { country_name } = await testTool.execute({
-      context: { input },
-      runtimeContext
-    });
-
-    return {
-      output: country_name
-    };
-  }
-});
-
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-
-## Using workflows as tools
-
-In this example the `cityStringWorkflow` workflow has been added to the main Mastra instance.
-
-
-```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-
-import { testWorkflow, cityStringWorkflow } from "./workflows/test-workflow";
-
-export const mastra = new Mastra({
-  ...
-  workflows: { testWorkflow, cityStringWorkflow },
-});
-```
-
-Once a workflow has been registered it can be referenced using `getWorkflow` from withing a tool.
-
-```typescript {10,17-27} filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
-export const cityCoordinatesTool = createTool({
-  id: "city-tool",
-  description: "Convert city details",
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  }),
-  execute: async ({ context, mastra }) => {
-    const { city } = context;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}`);
-    const geocodingData = await geocodingResponse.json();
-
-    const { name, country, timezone } = geocodingData.results[0];
-
-    const workflow = mastra?.getWorkflow("cityStringWorkflow");
-
-    const run = await workflow?.createRunAsync();
-
-    const { result } = await run?.start({
-      inputData: {
-        city_name: name,
-        country_name: country,
-        country_timezone: timezone
-      }
-    });
-
-    return {
-      outcome: result.outcome
-    };
-  }
-});
-```
-
-## Using workflows in agents
-
-You can also use Workflows in Agents. This agent is able to choose between using the test tool or the test workflow.
-
-```typescript
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { testTool } from "../tools/test-tool";
-import { testWorkflow } from "../workflows/test-workflow";
-
-export const testAgent = new Agent({
-  name: "test-agent",
-  description: "Create facts for a country based on the city",
-  instructions: `Return an interesting fact about the country based on the city provided`,
-  model: openai("gpt-4o"),
-  workflows: {
-    test_workflow: testWorkflow
-  },
-  tools: {
-    test_tool: testTool
-  },
-});
-```
-
-
-## Exposing workflows with `MCPServer`
-
-You can convert your workflows into tools by passing them into an instance of a Mastra `MCPServer`. This allows any MCP-compatible client to access your workflow.
-
-The workflow description becomes the tool description and the input schema becomes the tool's input schema.
-
-When you provide workflows to the server, each workflow is automatically exposed as a callable tool for example:
-
-- `run_testWorkflow`.
-
-```typescript filename="src/test-mcp-server.ts" showLineNumbers copy
-import { MCPServer } from "@mastra/mcp";
-
-import { testAgent } from "./mastra/agents/test-agent";
-import { testTool } from "./mastra/tools/test-tool";
-import { testWorkflow } from "./mastra/workflows/test-workflow";
-
-async function startServer() {
-  const server = new MCPServer({
-    name: "test-mcp-server",
-    version: "1.0.0",
-    workflows: {
-      testWorkflow
-    }
-  });
-
-  await server.startStdio();
-  console.log("MCPServer started on stdio");
-}
-
-startServer().catch(console.error);
-```
-
-To verify that your workflow is available on the server, you can connect with an MCPClient.
-
-```typescript filename="src/test-mcp-client.ts" showLineNumbers copy
-import { MCPClient } from "@mastra/mcp";
-
-async function main() {
-  const mcp = new MCPClient({
-    servers: {
-      local: {
-        command: "npx",
-        args: ["tsx", "src/test-mcp-server.ts"]
-      }
-    }
-  });
-
-  const tools = await mcp.getTools();
-  console.log(tools);
-}
-
-main().catch(console.error);
-```
-
-Run the client script to see your workflow tool.
-
-```bash
-npx tsx src/test-mcp-client.ts
-```
-
-## More resources
-
-- [MCPServer reference documentation](/reference/tools/mcp-server).
-- [MCPClient reference documentation](/reference/tools/mcp-client).