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

package/.docs/course/04-workflows/17-testing-parallel-performance.md

@@ -0,0 +1,36 @@
+# Testing Parallel Workflow
+
+Let's test your parallel workflow.
+
+## Registering the New Workflow
+
+Update your Mastra configuration to include your new workflow workflows:
+
+```typescript
+// In src/mastra/index.ts
+import { contentWorkflow, aiContentWorkflow, parallelAnalysisWorkflow } from './workflows/content-workflow'
+
+export const mastra = new Mastra({
+  workflows: {
+    contentWorkflow,
+    aiContentWorkflow,
+    parallelAnalysisWorkflow, // Add the parallel workflow
+  },
+  // ... rest of configuration
+})
+```
+
+## Testing the Parallel Workflow
+
+You can now test this new workflow in the Playground. You will notice that it processes the three analysis steps in parallel speeding up execution time.
+
+## When to Use Parallel Execution
+
+Use parallel execution when:
+
+- Steps don't depend on each other's outputs
+- Steps involve I/O operations (API calls, database queries)
+- You want to maximize performance
+- Steps process the same input data
+
+Register your parallel workflow with Mastra to use it in the playground! Next, you'll learn about conditional branching.

package/.docs/course/04-workflows/18-understanding-conditional-branching.md

@@ -0,0 +1,61 @@
+# Understanding Conditional Branching
+
+Learn how to create workflows that take different paths based on data conditions, making your workflows more intelligent and adaptive.
+
+## What is Conditional Branching?
+
+Conditional branching allows workflows to:
+
+- **Make decisions**: Choose different processing paths based on data
+- **Handle variations**: Process different content types differently
+- **Optimize performance**: Skip unnecessary steps for certain inputs
+- **Customize behavior**: Provide different experiences based on conditions
+
+## Real-World Example
+
+Imagine a content processing workflow that:
+
+- **Short content** (< 50 words): Gets quick processing
+- **Medium content** (50-200 words): Gets standard processing
+- **Long content** (> 200 words): Gets detailed processing with extra analysis
+
+## Basic Branching Syntax
+
+```typescript
+.branch([
+  [condition1, step1],
+  [condition2, step2],
+  [condition3, step3]
+])
+```
+
+Where:
+
+- **condition**: An async function that returns `true` or `false`
+- **step**: The step to execute if the condition is `true`
+
+## Condition Functions
+
+Conditions are functions that examine the input data:
+
+```typescript
+// Example condition function
+;async ({ inputData }) => {
+  return inputData.wordCount < 50
+}
+```
+
+## Multiple Paths
+
+- If multiple conditions are `true`, **all matching steps run in parallel**
+- If no conditions are `true`, the workflow continues without executing any branch steps
+- Conditions are evaluated in order, but matching steps run simultaneously
+
+## Benefits
+
+- **Smart routing**: Send data down the most appropriate path
+- **Performance**: Skip expensive operations when not needed
+- **Flexibility**: Handle different scenarios in one workflow
+- **Maintainability**: Clear logic for different processing paths
+
+Next, you'll create a workflow with conditional branches!

package/.docs/course/04-workflows/19-creating-conditional-steps.md

@@ -0,0 +1,124 @@
+# Creating Conditional Steps
+
+Let's create two processing steps for different types of content: one for short and simple content, and one for everything else.
+
+## Assessment Step
+
+First, create a step that analyzes content to determine which path to take:
+
+```typescript
+const assessContentStep = createStep({
+  id: 'assess-content',
+  description: 'Assesses content to determine processing path',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+    wordCount: z.number(),
+    complexity: z.enum(['simple', 'moderate', 'complex']),
+    category: z.enum(['short', 'medium', 'long']),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type } = inputData
+    const words = content.trim().split(/\s+/)
+    const wordCount = words.length
+
+    // Determine category by length
+    let category: 'short' | 'medium' | 'long' = 'short'
+    if (wordCount >= 50) category = 'medium'
+    if (wordCount >= 200) category = 'long'
+
+    // Determine complexity by average word length
+    const avgWordLength = words.reduce((sum, word) => sum + word.length, 0) / wordCount
+    let complexity: 'simple' | 'moderate' | 'complex' = 'simple'
+    if (avgWordLength > 5) complexity = 'moderate'
+    if (avgWordLength > 7) complexity = 'complex'
+
+    console.log(`📋 Assessment: ${category} content, ${complexity} complexity`)
+
+    return {
+      content,
+      type,
+      wordCount,
+      complexity,
+      category,
+    }
+  },
+})
+```
+
+## Quick Processing Step
+
+For short, simple content:
+
+```typescript
+const quickProcessingStep = createStep({
+  id: 'quick-processing',
+  description: 'Quick processing for short and simple content',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+    wordCount: z.number(),
+    complexity: z.enum(['simple', 'moderate', 'complex']),
+    category: z.enum(['short', 'medium', 'long']),
+  }),
+  outputSchema: z.object({
+    processedContent: z.string(),
+    processingType: z.string(),
+    recommendations: z.array(z.string()),
+  }),
+  execute: async ({ inputData }) => {
+    console.log('⚡ Quick processing for short and simple content...')
+
+    return {
+      processedContent: inputData.content,
+      processingType: 'quick',
+      recommendations: ['Content is concise', 'Consider expanding for more detail'],
+    }
+  },
+})
+```
+
+## General Processing Step
+
+For all other content (not short and simple):
+
+```typescript
+const generalProcessingStep = createStep({
+  id: 'general-processing',
+  description: 'General processing for all other content',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+    wordCount: z.number(),
+    complexity: z.enum(['simple', 'moderate', 'complex']),
+    category: z.enum(['short', 'medium', 'long']),
+  }),
+  outputSchema: z.object({
+    processedContent: z.string(),
+    processingType: z.string(),
+    recommendations: z.array(z.string()),
+  }),
+  execute: async ({ inputData }) => {
+    console.log('📝 General processing for non-short/simple content...')
+
+    // Simulate more involved processing
+    await new Promise(resolve => setTimeout(resolve, 500))
+
+    return {
+      processedContent: inputData.content,
+      processingType: 'general',
+      recommendations: [
+        'Consider simplifying content',
+        'Break up long paragraphs',
+        'Add examples or explanations if needed',
+      ],
+    }
+  },
+})
+```
+
+These two steps will be used in different branches based on the content assessment. Next, you'll create the conditional workflow!

package/.docs/course/04-workflows/20-building-conditional-workflow.md

@@ -0,0 +1,55 @@
+# Building Conditional Workflow
+
+Now you'll create a workflow that uses conditional branching to route content through two different processing paths.
+
+## Creating the Conditional Workflow
+
+Add this workflow to your file:
+
+```typescript
+export const conditionalWorkflow = createWorkflow({
+  id: 'conditional-workflow',
+  description: 'Content processing with conditional branching',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    processedContent: z.string(),
+    processingType: z.string(),
+    recommendations: z.array(z.string()),
+  }),
+})
+  .then(assessContentStep)
+  .branch([
+    // Branch 1: Short and simple content
+    [async ({ inputData }) => inputData.category === 'short' && inputData.complexity === 'simple', quickProcessingStep],
+    // Branch 2: Everything else
+    [
+      async ({ inputData }) => !(inputData.category === 'short' && inputData.complexity === 'simple'),
+      generalProcessingStep,
+    ],
+  ])
+  .commit()
+```
+
+## Understanding the Conditions
+
+1. **Short + Simple**: Quick processing with minimal recommendations
+2. **Everything Else**: General processing with more suggestions
+
+## Multiple Conditions
+
+You can combine conditions using logical operators:
+
+- **`&&`**: AND - both conditions must be true
+- **`||`**: OR - either condition can be true
+- **`!`**: NOT - condition must be false
+
+## Condition Evaluation
+
+- Conditions are checked in order
+- Multiple conditions can be true (steps run in parallel)
+- If no conditions match, the branch is skipped
+
+Next, you'll test this conditional workflow with different types of content!

package/.docs/course/04-workflows/21-testing-conditional-logic.md

@@ -0,0 +1,58 @@
+# Testing Conditional Logic
+
+Let's test your conditional workflow with different types of content to see how it routes to different processing paths.
+
+## Registering the New Workflow
+
+Update your Mastra configuration to include your new workflow workflows:
+
+```typescript
+// In src/mastra/index.ts
+import {
+  contentWorkflow,
+  aiContentWorkflow,
+  parallelAnalysisWorkflow,
+  conditionalWorkflow,
+} from './workflows/content-workflow'
+
+export const mastra = new Mastra({
+  workflows: {
+    contentWorkflow,
+    aiContentWorkflow,
+    parallelAnalysisWorkflow,
+    conditionalWorkflow, // Add the conditional workflow
+  },
+  // ... rest of configuration
+})
+```
+
+## Testing the conditional workflow
+
+You can now test this new conditional workflow in the playground. Be sure to test different content lengths and content types.
+
+## Understanding the Flow
+
+1. **Assessment step** analyzes content and determines category/complexity
+2. **Branch conditions** are evaluated against the assessment results
+3. **Matching step** executes based on which condition(s) are true
+4. **Results** show which processing path was taken
+
+## Debugging Conditions
+
+If a condition isn't working as expected:
+
+- Check the assessment step output
+- Verify condition logic matches your expectations
+- Test individual conditions in isolation
+- Add console.log statements to track condition evaluation
+
+## Branch Benefits
+
+Conditional workflows provide:
+
+- **Intelligent routing**: Right processing for right content
+- **Performance optimization**: Skip heavy processing for simple content
+- **Customized experience**: Different handling for different scenarios
+- **Scalable logic**: Easy to add new conditions and processing paths
+
+Next, you'll learn about streaming workflow results for better user experience!

package/.docs/docs/agents/adding-voice.md

@@ -0,0 +1,349 @@
+# Voice
+
+Mastra agents can be enhanced with voice capabilities, allowing them to speak responses and listen to user input. You can configure an agent to use either a single voice provider or combine multiple providers for different operations.
+
+## Basic usage
+
+The simplest way to add voice to an agent is to use a single provider for both speaking and listening:
+
+```typescript
+import { createReadStream } from 'fs'
+import path from 'path'
+import { Agent } from '@mastra/core/agent'
+import { OpenAIVoice } from '@mastra/voice-openai'
+
+// Initialize the voice provider with default settings
+const voice = new OpenAIVoice()
+
+// Create an agent with voice capabilities
+export const agent = new Agent({
+  id: 'voice-agent',
+  name: 'Voice Agent',
+  instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
+  model: 'openai/gpt-5.1',
+  voice,
+})
+
+// The agent can now use voice for interaction
+const audioStream = await agent.voice.speak("Hello, I'm your AI assistant!", {
+  filetype: 'm4a',
+})
+
+playAudio(audioStream!)
+
+try {
+  const transcription = await agent.voice.listen(audioStream)
+  console.log(transcription)
+} catch (error) {
+  console.error('Error transcribing audio:', error)
+}
+```
+
+## Working with Audio Streams
+
+The `speak()` and `listen()` methods work with Node.js streams. Here's how to save and load audio files:
+
+### Saving Speech Output
+
+The `speak` method returns a stream that you can pipe to a file or speaker.
+
+```typescript
+import { createWriteStream } from 'fs'
+import path from 'path'
+
+// Generate speech and save to file
+const audio = await agent.voice.speak('Hello, World!')
+const filePath = path.join(process.cwd(), 'agent.mp3')
+const writer = createWriteStream(filePath)
+
+audio.pipe(writer)
+
+await new Promise<void>((resolve, reject) => {
+  writer.on('finish', () => resolve())
+  writer.on('error', reject)
+})
+```
+
+### Transcribing Audio Input
+
+The `listen` method expects a stream of audio data from a microphone or file.
+
+```typescript
+import { createReadStream } from 'fs'
+import path from 'path'
+
+// Read audio file and transcribe
+const audioFilePath = path.join(process.cwd(), '/agent.m4a')
+const audioStream = createReadStream(audioFilePath)
+
+try {
+  console.log('Transcribing audio file...')
+  const transcription = await agent.voice.listen(audioStream, {
+    filetype: 'm4a',
+  })
+  console.log('Transcription:', transcription)
+} catch (error) {
+  console.error('Error transcribing audio:', error)
+}
+```
+
+## Speech-to-Speech Voice Interactions
+
+For more dynamic and interactive voice experiences, you can use real-time voice providers that support speech-to-speech capabilities:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { getMicrophoneStream } from '@mastra/node-audio'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { search, calculate } from '../tools'
+
+// Initialize the realtime voice provider
+const voice = new OpenAIRealtimeVoice({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-5.1-realtime',
+  speaker: 'alloy',
+})
+
+// Create an agent with speech-to-speech voice capabilities
+export const agent = new Agent({
+  id: 'speech-to-speech-agent',
+  name: 'Speech-to-Speech Agent',
+  instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
+  model: 'openai/gpt-5.1',
+  tools: {
+    // Tools configured on Agent are passed to voice provider
+    search,
+    calculate,
+  },
+  voice,
+})
+
+// Establish a WebSocket connection
+await agent.voice.connect()
+
+// Start a conversation
+agent.voice.speak("Hello, I'm your AI assistant!")
+
+// Stream audio from a microphone
+const microphoneStream = getMicrophoneStream()
+agent.voice.send(microphoneStream)
+
+// When done with the conversation
+agent.voice.close()
+```
+
+### Event System
+
+The realtime voice provider emits several events you can listen for:
+
+```typescript
+// Listen for speech audio data sent from voice provider
+agent.voice.on('speaking', ({ audio }) => {
+  // audio contains ReadableStream or Int16Array audio data
+})
+
+// Listen for transcribed text sent from both voice provider and user
+agent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role} said: ${text}`)
+})
+
+// Listen for errors
+agent.voice.on('error', error => {
+  console.error('Voice error:', error)
+})
+```
+
+## Examples
+
+### End-to-end voice interaction
+
+This example demonstrates a voice interaction between two agents. The hybrid voice agent, which uses multiple providers, speaks a question, which is saved as an audio file. The unified voice agent listens to that file, processes the question, generates a response, and speaks it back. Both audio outputs are saved to the `audio` directory.
+
+The following files are created:
+
+- **hybrid-question.mp3** – Hybrid agent's spoken question.
+- **unified-response.mp3** – Unified agent's spoken response.
+
+```typescript
+import 'dotenv/config'
+
+import path from 'path'
+import { createReadStream } from 'fs'
+import { Agent } from '@mastra/core/agent'
+import { CompositeVoice } from '@mastra/core/voice'
+import { OpenAIVoice } from '@mastra/voice-openai'
+import { Mastra } from '@mastra/core'
+
+// Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
+export const saveAudioToFile = async (
+  audio: NodeJS.ReadableStream,
+  filename: string,
+): Promise<void> => {
+  const audioDir = path.join(process.cwd(), 'audio')
+  const filePath = path.join(audioDir, filename)
+
+  await fs.promises.mkdir(audioDir, { recursive: true })
+
+  const writer = createWriteStream(filePath)
+  audio.pipe(writer)
+  return new Promise((resolve, reject) => {
+    writer.on('finish', resolve)
+    writer.on('error', reject)
+  })
+}
+
+// Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
+export const convertToText = async (input: string | NodeJS.ReadableStream): Promise<string> => {
+  if (typeof input === 'string') {
+    return input
+  }
+
+  const chunks: Buffer[] = []
+  return new Promise((resolve, reject) => {
+    inputData.on('data', chunk => chunks.push(Buffer.from(chunk)))
+    inputData.on('error', reject)
+    inputData.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')))
+  })
+}
+
+export const hybridVoiceAgent = new Agent({
+  id: 'hybrid-voice-agent',
+  name: 'Hybrid Voice Agent',
+  model: 'openai/gpt-5.1',
+  instructions: 'You can speak and listen using different providers.',
+  voice: new CompositeVoice({
+    input: new OpenAIVoice(),
+    output: new OpenAIVoice(),
+  }),
+})
+
+export const unifiedVoiceAgent = new Agent({
+  id: 'unified-voice-agent',
+  name: 'Unified Voice Agent',
+  instructions: 'You are an agent with both STT and TTS capabilities.',
+  model: 'openai/gpt-5.1',
+  voice: new OpenAIVoice(),
+})
+
+export const mastra = new Mastra({
+  agents: { hybridVoiceAgent, unifiedVoiceAgent },
+})
+
+const hybridVoiceAgent = mastra.getAgent('hybridVoiceAgent')
+const unifiedVoiceAgent = mastra.getAgent('unifiedVoiceAgent')
+
+const question = 'What is the meaning of life in one sentence?'
+
+const hybridSpoken = await hybridVoiceAgent.voice.speak(question)
+
+await saveAudioToFile(hybridSpoken!, 'hybrid-question.mp3')
+
+const audioStream = createReadStream(path.join(process.cwd(), 'audio', 'hybrid-question.mp3'))
+const unifiedHeard = await unifiedVoiceAgent.voice.listen(audioStream)
+
+const inputText = await convertToText(unifiedHeard!)
+
+const unifiedResponse = await unifiedVoiceAgent.generate(inputText)
+const unifiedSpoken = await unifiedVoiceAgent.voice.speak(unifiedResponse.text)
+
+await saveAudioToFile(unifiedSpoken!, 'unified-response.mp3')
+```
+
+### Using Multiple Providers
+
+For more flexibility, you can use different providers for speaking and listening using the CompositeVoice class:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CompositeVoice } from '@mastra/core/voice'
+import { OpenAIVoice } from '@mastra/voice-openai'
+import { PlayAIVoice } from '@mastra/voice-playai'
+
+export const agent = new Agent({
+  id: 'voice-agent',
+  name: 'Voice Agent',
+  instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
+  model: 'openai/gpt-5.1',
+
+  // Create a composite voice using OpenAI for listening and PlayAI for speaking
+  voice: new CompositeVoice({
+    input: new OpenAIVoice(),
+    output: new PlayAIVoice(),
+  }),
+})
+```
+
+### Using AI SDK
+
+Mastra supports using AI SDK's transcription and speech models directly in `CompositeVoice`, giving you access to a wide range of providers through the AI SDK ecosystem:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CompositeVoice } from '@mastra/core/voice'
+import { openai } from '@ai-sdk/openai'
+import { elevenlabs } from '@ai-sdk/elevenlabs'
+import { groq } from '@ai-sdk/groq'
+
+export const agent = new Agent({
+  id: 'aisdk-voice-agent',
+  name: 'AI SDK Voice Agent',
+  instructions: `You are a helpful assistant with voice capabilities.`,
+  model: 'openai/gpt-5.1',
+
+  // Pass AI SDK models directly to CompositeVoice
+  voice: new CompositeVoice({
+    input: openai.transcription('whisper-1'), // AI SDK transcription model
+    output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech model
+  }),
+})
+
+// Use voice capabilities as usual
+const audioStream = await agent.voice.speak('Hello!')
+const transcribedText = await agent.voice.listen(audioStream)
+```
+
+#### Mix and Match Providers
+
+You can mix AI SDK models with Mastra voice providers:
+
+```typescript
+import { CompositeVoice } from '@mastra/core/voice'
+import { PlayAIVoice } from '@mastra/voice-playai'
+import { openai } from '@ai-sdk/openai'
+
+// Use AI SDK for transcription and Mastra provider for speech
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'), // AI SDK
+  output: new PlayAIVoice(), // Mastra provider
+})
+```
+
+For the complete list of supported AI SDK providers and their capabilities:
+
+- [Transcription](https://ai-sdk.dev/docs/providers/openai/transcription)
+- [Speech](https://ai-sdk.dev/docs/providers/elevenlabs/speech)
+
+## Supported Voice Providers
+
+Mastra supports multiple voice providers for text-to-speech (TTS) and speech-to-text (STT) capabilities:
+
+| Provider        | Package                         | Features                  | Reference                                                          |
+| --------------- | ------------------------------- | ------------------------- | ------------------------------------------------------------------ |
+| OpenAI          | `@mastra/voice-openai`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
+| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
+| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
+| PlayAI          | `@mastra/voice-playai`          | TTS                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
+| Google          | `@mastra/voice-google`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/google)          |
+| Deepgram        | `@mastra/voice-deepgram`        | STT                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
+| Murf            | `@mastra/voice-murf`            | TTS                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
+| Speechify       | `@mastra/voice-speechify`       | TTS                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
+| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
+| Azure           | `@mastra/voice-azure`           | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+
+## Next Steps
+
+- [Voice API Reference](https://mastra.ai/reference/voice/mastra-voice) - Detailed API documentation for voice capabilities
+- [Text to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/text-to-speech) - Interactive story generator and other TTS implementations
+- [Speech to Text Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-text) - Voice memo app and other STT implementations
+- [Speech to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-speech) - Real-time voice conversation with call analysis