@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-workflows-error-handling.md

@@ -0,0 +1,360 @@
+# Error Handling
+
+Mastra workflows support error handling through result status checks after execution, retry policies for transient failures, and lifecycle callbacks for centralized error logging or alerting.
+
+## Handling workflow results
+
+When you run a workflow, the result object contains the status and any errors that occurred.
+
+### Checking the result status
+
+```typescript
+import { mastra } from './mastra'
+
+const workflow = mastra.getWorkflow('myWorkflow')
+const run = await workflow.createRun()
+const result = await run.start({ inputData: { value: 'test' } })
+
+switch (result.status) {
+  case 'success':
+    console.log('Workflow completed:', result.result)
+    break
+  case 'failed':
+    console.error('Workflow failed:', result.error)
+    break
+  case 'suspended':
+    console.log('Workflow suspended, waiting for resume')
+    break
+}
+```
+
+### Result object structure
+
+The result object contains:
+
+- `status` - The workflow status: `'success'`, `'failed'`, `'suspended'`, or `'tripwire'`
+- `result` - The workflow output (when status is `'success'`)
+- `error` - Error details (when status is `'failed'`)
+- `steps` - Individual step results with their status and output
+
+### Accessing step results
+
+You can inspect individual step results to understand where a failure occurred:
+
+```typescript
+const result = await run.start({ inputData: { value: 'test' } })
+
+if (result.status === 'failed') {
+  // Find which step failed
+  for (const [stepId, stepResult] of Object.entries(result.steps)) {
+    if (stepResult.status === 'failed') {
+      console.error(`Step ${stepId} failed:`, stepResult.error)
+    }
+  }
+}
+```
+
+## Lifecycle callbacks
+
+For scenarios where you need to handle workflow completion without awaiting the result—such as background jobs, fire-and-forget workflows, or centralized logging—you can use lifecycle callbacks.
+
+### onFinish
+
+Called when a workflow completes with any status (success, failed, suspended, or tripwire):
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const orderWorkflow = createWorkflow({
+  id: 'order-processing',
+  inputSchema: z.object({ orderId: z.string() }),
+  outputSchema: z.object({ orderId: z.string(), status: z.string() }),
+  options: {
+    onFinish: async result => {
+      if (result.status === 'success') {
+        await db.updateOrderStatus(result.result.orderId, result.status)
+      }
+      await analytics.track('workflow_completed', {
+        workflowId: 'order-processing',
+        status: result.status,
+      })
+    },
+  },
+})
+```
+
+The `onFinish` callback receives:
+
+- `status` - The workflow status
+- `result` - The workflow output (on success)
+- `error` - Error details (on failure)
+- `steps` - Individual step results
+- `tripwire` - Tripwire info (if status is `'tripwire'`)
+- `runId` - The unique identifier for this workflow run
+- `workflowId` - The workflow's identifier
+- `resourceId` - Optional resource identifier (if provided when creating the run)
+- `getInitData<any>()` - Function that returns the initial input data
+- `mastra` - The Mastra instance (if workflow is registered with Mastra)
+- `requestContext` - Request-scoped context data
+- `logger` - The workflow's logger instance
+- `state` - The workflow's current state object
+
+### onError
+
+Called only when a workflow fails (status is `'failed'` or `'tripwire'`):
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const paymentWorkflow = createWorkflow({
+  id: 'payment-processing',
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.object({ transactionId: z.string() }),
+  options: {
+    onError: async errorInfo => {
+      await alertService.notify({
+        channel: 'payments-alerts',
+        message: `Payment workflow failed: ${errorInfo.error?.message}`,
+      })
+      await errorTracker.capture(errorInfo.error)
+    },
+  },
+})
+```
+
+The `onError` callback receives:
+
+- `status` - Either `'failed'` or `'tripwire'`
+- `error` - Error details
+- `steps` - Individual step results
+- `tripwire` - Tripwire info (if status is `'tripwire'`)
+- `runId` - The unique identifier for this workflow run
+- `workflowId` - The workflow's identifier
+- `resourceId` - Optional resource identifier (if provided when creating the run)
+- `getInitData<any>()` - Function that returns the initial input data
+- `mastra` - The Mastra instance (if workflow is registered with Mastra)
+- `requestContext` - Request-scoped context data
+- `logger` - The workflow's logger instance
+- `state` - The workflow's current state object
+
+### Using both callbacks
+
+You can use both callbacks together:
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const pipelineWorkflow = createWorkflow({
+  id: 'data-pipeline',
+  inputSchema: z.object({ source: z.string() }),
+  outputSchema: z.object({ recordsProcessed: z.number() }),
+  options: {
+    onFinish: async result => {
+      // Always log completion
+      await logger.info('Pipeline completed', { status: result.status })
+    },
+    onError: async errorInfo => {
+      // Alert on failures
+      await pagerDuty.alert('Data pipeline failed', errorInfo.error)
+    },
+  },
+})
+```
+
+### Error handling in callbacks
+
+Errors thrown inside callbacks are caught and logged—they will not affect the workflow result or cause it to fail. This ensures that callback issues don't break your workflows in production.
+
+```typescript
+options: {
+  onFinish: async (result) => {
+    // If this throws, it's logged but the workflow result is unchanged
+    await externalService.notify(result);
+  },
+}
+```
+
+## Retries
+
+Mastra has a retry mechanism for workflows or steps that fail due to transient errors, for example when steps interact with external services or resources that may be temporarily unavailable.
+
+## Workflow-level using `retryConfig`
+
+You can configure retries at the workflow level, which applies to all steps in the workflow:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  retryConfig: {
+    attempts: 5,
+    delay: 2000
+  }
+})
+  .then(step1)
+  .commit();
+```
+
+## Step-level using `retries`
+
+You can configure retries for individual steps using the `retries` property. This overrides the workflow-level retry configuration for that specific step:
+
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const step1 = createStep({
+  execute: async () => {
+    const response = await fetch('example-url')
+
+    if (!response.ok) {
+      throw new Error('Error')
+    }
+
+    return {
+      value: '',
+    }
+  },
+  retries: 3,
+})
+```
+
+## Conditional branching
+
+You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  execute: async () => {
+    try {
+      const response = await fetch('example-url');
+
+      if (!response.ok) {
+        throw new Error('error');
+      }
+
+      return {
+        status: "ok"
+      };
+    } catch (error) {
+      return {
+        status: "error"
+      };
+    }
+  }
+});
+
+const step2 = createStep({...});
+const fallback = createStep({...});
+
+export const testWorkflow = createWorkflow({})
+  .then(step1)
+  .branch([
+    [async ({ inputData: { status } }) => status === "ok", step2],
+    [async ({ inputData: { status } }) => status === "error", fallback]
+  ])
+  .commit();
+```
+
+## Check previous step results
+
+Use `getStepResult()` to inspect a previous step’s results.
+
+```typescript
+import { createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+
+const step2 = createStep({
+  execute: async ({ getStepResult }) => {
+    const step1Result = getStepResult(step1);
+
+    return {
+      value: ""
+    };
+  }
+});
+```
+
+## Exiting early with `bail()`
+
+Use `bail()` in a step to exit early with a successful result. This returns the provided payload as the step output and ends workflow execution.
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+## Exiting early with `Error()`
+
+Use `throw new Error()` in a step to exit with an error.
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async () => {
+    throw new Error('error');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+\## Monitor errors with `stream()`
+
+You can monitor workflows for errors using `stream`:
+
+```typescript
+import { mastra } from '../src/mastra'
+
+const workflow = mastra.getWorkflow('testWorkflow')
+
+const run = await workflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream.stream) {
+  console.log(chunk.payload.output.stats)
+}
+```
+
+## Related
+
+- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)

package/dist/docs/references/docs-workflows-human-in-the-loop.md

@@ -0,0 +1,215 @@
+# Human-in-the-loop (HITL)
+
+Some workflows need to pause for human input before continuing. When a workflow is [suspended](https://mastra.ai/docs/workflows/suspend-and-resume), it can return a message explaining why it paused and what’s needed to proceed. The workflow can then either [resume](#resuming-workflows-with-human-input) or [bail](#handling-human-rejection-with-bail) based on the input received. This approach works well for manual approvals, rejections, gated decisions, or any step that requires human oversight.
+
+## Pausing workflows for human input
+
+Human-in-the-loop input works much like [pausing a workflow](https://mastra.ai/docs/workflows/suspend-and-resume) using `suspend()`. The key difference is that when human input is required, you can return `suspend()` with a payload that provides context or guidance to the user on how to continue.
+
+![Pausing a workflow with suspend()](/assets/images/workflows-suspend-4540783670f918109ac35beaf4db914b.jpg)
+
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: z.object({
+    userEmail: z.string(),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean(),
+  }),
+  suspendSchema: z.object({
+    reason: z.string(),
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { userEmail } = inputData
+    const { approved } = resumeData ?? {}
+
+    if (!approved) {
+      return await suspend({
+        reason: 'Human approval required.',
+      })
+    }
+
+    return {
+      output: `Email sent to ${userEmail}`,
+    }
+  },
+})
+
+export const testWorkflow = createWorkflow({
+  id: 'test-workflow',
+  inputSchema: z.object({
+    userEmail: z.string(),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+})
+  .then(step1)
+  .commit()
+```
+
+## Providing user feedback
+
+When a workflow is suspended, you can access the payload returned by `suspend()` by identifying the suspended step and reading its `suspendPayload`.
+
+```typescript
+const workflow = mastra.getWorkflow('testWorkflow')
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: {
+    userEmail: 'alex@example.com',
+  },
+})
+
+if (result.status === 'suspended') {
+  const suspendStep = result.suspended[0]
+  const suspendedPayload = result.steps[suspendStep[0]].suspendPayload
+
+  console.log(suspendedPayload)
+}
+```
+
+### Example output
+
+The data returned by the step can include a reason and help the user understand what's needed to resume the workflow.
+
+```typescript
+{
+  reason: 'Confirm to send email.'
+}
+```
+
+## Resuming workflows with human input
+
+As with [restarting a workflow](https://mastra.ai/docs/workflows/suspend-and-resume), use `resume()` with `resumeData` to continue a workflow after receiving input from a human. The workflow resumes from the step where it was paused.
+
+![Restarting a workflow with resume()](/assets/images/workflows-resume-1e54b4d0c753ff79571f6d6b05109a60.jpg)
+
+```typescript
+const workflow = mastra.getWorkflow('testWorkflow')
+const run = await workflow.createRun()
+
+await run.start({
+  inputData: {
+    userEmail: 'alex@example.com',
+  },
+})
+
+const handleResume = async () => {
+  const result = await run.resume({
+    step: 'step-1',
+    resumeData: { approved: true },
+  })
+}
+```
+
+### Handling human rejection with `bail()`
+
+Use `bail()` to stop workflow execution at a step without triggering an error. This can be useful when a human explicitly rejects an action. The workflow completes with a `success` status, and any logic after the call to `bail()` is skipped.
+
+```typescript
+const step1 = createStep({
+  execute: async ({ inputData, resumeData, suspend, bail }) => {
+    const { userEmail } = inputData
+    const { approved } = resumeData ?? {}
+
+    if (approved === false) {
+      return bail({
+        reason: 'User rejected the request.',
+      })
+    }
+
+    if (!approved) {
+      return await suspend({
+        reason: 'Human approval required.',
+      })
+    }
+
+    return {
+      message: `Email sent to ${userEmail}`,
+    }
+  },
+})
+```
+
+## Multi-turn human input
+
+For workflows that require input at multiple stages, the suspend pattern remains the same. Each step defines a `resumeSchema`, and `suspendSchema` typically with a reason that can be used to provide user feedback.
+
+```typescript
+const step1 = createStep({...});
+
+const step2 = createStep({
+  id: "step-2",
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { message } = inputData;
+    const { approved } = resumeData ?? {};
+
+    if (!approved) {
+      return await suspend({
+        reason: "Human approval required."
+      });
+    }
+
+    return {
+      output: `${message} - Deleted`
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: z.object({
+    userEmail: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  })
+})
+  .then(step1)
+  .then(step2)
+  .commit();
+```
+
+Each step must be resumed in sequence, with a separate call to `resume()` for each suspended step. This approach helps manage multi-step approvals with consistent UI feedback and clear input handling at each stage.
+
+```typescript
+const handleResume = async () => {
+  const result = await run.resume({
+    step: 'step-1',
+    resumeData: { approved: true },
+  })
+}
+
+const handleDelete = async () => {
+  const result = await run.resume({
+    step: 'step-2',
+    resumeData: { approved: true },
+  })
+}
+```
+
+## Related
+
+- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)