@mastra/mcp-docs-server 1.0.0-beta.3 → 1.0.0-beta.4

package/.docs/raw/reference/agents/generate.mdx

@@ -3,6 +3,8 @@ title: "Reference: Agent.generate() | Agents"
 description: "Documentation for the `Agent.generate()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.generate()
 
 The `.generate()` method enables non-streaming response generation from an agent, with enhanced capabilities and flexible output formats. It accepts messages and optional generation options, supporting both Mastra’s native format and AI SDK v5 compatibility.
@@ -17,6 +19,14 @@ const mastraResult = await agent.generate("message for agent");
 const aiSdkResult = await agent.generate("message for agent", {
   format: "aisdk",
 });
+
+// With model settings (e.g., limiting output tokens)
+const limitedResult = await agent.generate("Write a short poem about coding", {
+  modelSettings: {
+    maxOutputTokens: 50,
+    temperature: 0.7,
+  },
+});
 ```
 
 :::info
@@ -392,91 +402,7 @@ const aiSdkResult = await agent.generate("message for agent", {
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description: "Model-specific settings like temperature, topP, etc.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in generation (0-2). Higher values make output more random.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description:
-                "Maximum number of retry attempts for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling parameter (0-1). Controls diversity of generated text.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Top-k sampling parameter. Limits vocabulary to k most likely tokens.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Penalty for token presence (-2 to 2). Reduces repetition.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Array of strings that will stop generation when encountered.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "threadId",
       type: "string",
@@ -652,13 +578,6 @@ const aiSdkResult = await agent.generate("message for agent", {
         },
       ],
     },
-    {
-      name: "maxTokens",
-      type: "number",
-      isOptional: true,
-      description:
-        "Conditions for stopping execution (e.g., step count, token limit).",
-    },
   ]}
 />
 

package/.docs/raw/reference/agents/network.mdx

@@ -3,6 +3,8 @@ title: "Reference: Agent.network() | Agents"
 description: "Documentation for the `Agent.network()` method in Mastra agents, which enables multi-agent collaboration and routing."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.network()
 
 :::caution Experimental Feature
@@ -208,91 +210,7 @@ await agent.network(`
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description:
-        "Model-specific settings like temperature, maxTokens, topP, etc. These are passed to the underlying language model.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description: "Maximum number of retries for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either temperature or topP, but not both.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "runId",
       type: "string",

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -3,6 +3,8 @@ title: "Reference: Agent.stream() | Streaming"
 description: "Documentation for the `Agent.stream()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.stream()
 
 The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5 compatibility.
@@ -396,91 +398,7 @@ const aiSdkStream = await agent.stream("message for agent", {
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description:
-        "Model-specific settings like temperature, maxTokens, topP, etc. These are passed to the underlying language model.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description: "Maximum number of retries for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either temperature or topP, but not both.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "threadId",
       type: "string",
@@ -661,13 +579,6 @@ const aiSdkStream = await agent.stream("message for agent", {
         },
       ],
     },
-    {
-      name: "maxTokens",
-      type: "number",
-      isOptional: true,
-      description:
-        "Condition(s) that determine when to stop the agent's execution. Can be a single condition or array of conditions.",
-    },
   ]}
 />
 

package/.docs/raw/reference/voice/composite-voice.mdx

@@ -7,31 +7,7 @@ description: "Documentation for the CompositeVoice class, which enables combinin
 
 The CompositeVoice class allows you to combine different voice providers for text-to-speech and speech-to-text operations. This is particularly useful when you want to use the best provider for each operation - for example, using OpenAI for speech-to-text and PlayAI for text-to-speech.
 
-CompositeVoice is used internally by the Agent class to provide flexible voice capabilities.
-
-## Usage Example
-
-```typescript
-import { CompositeVoice } from "@mastra/core/voice";
-import { OpenAIVoice } from "@mastra/voice-openai";
-import { PlayAIVoice } from "@mastra/voice-playai";
-
-// Create voice providers
-const openai = new OpenAIVoice();
-const playai = new PlayAIVoice();
-
-// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
-const voice = new CompositeVoice({
-  input: openai,
-  output: playai,
-});
-
-// Convert speech to text using OpenAI
-const text = await voice.listen(audioStream);
-
-// Convert text to speech using PlayAI
-const audio = await voice.speak("Hello, world!");
-```
+CompositeVoice supports both Mastra voice providers and AI SDK model providers
 
 ## Constructor Parameters
 
@@ -45,14 +21,20 @@ const audio = await voice.speak("Hello, world!");
     },
     {
       name: "config.input",
-      type: "MastraVoice",
-      description: "Voice provider to use for speech-to-text operations",
+      type: "MastraVoice | TranscriptionModel",
+      description: "Voice provider or AI SDK transcription model to use for speech-to-text operations. AI SDK models are automatically wrapped.",
       isOptional: true,
     },
     {
       name: "config.output",
+      type: "MastraVoice | SpeechModel",
+      description: "Voice provider or AI SDK speech model to use for text-to-speech operations. AI SDK models are automatically wrapped.",
+      isOptional: true,
+    },
+    {
+      name: "config.realtime",
       type: "MastraVoice",
-      description: "Voice provider to use for text-to-speech operations",
+      description: "Voice provider to use for real-time speech-to-speech operations",
       isOptional: true,
     },
   ]}
@@ -142,3 +124,64 @@ Notes:
 - If no speaking provider is configured, returns an empty array
 - Each voice object will have at least a voiceId property
 - Additional voice properties depend on the speaking provider
+
+## Usage Examples
+
+### Using Mastra Voice Providers
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+
+// Create voice providers
+const openai = new OpenAIVoice();
+const playai = new PlayAIVoice();
+
+// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
+const voice = new CompositeVoice({
+  input: openai,
+  output: playai,
+});
+
+// Convert speech to text using OpenAI
+const text = await voice.listen(audioStream);
+
+// Convert text to speech using PlayAI
+const audio = await voice.speak("Hello, world!");
+```
+
+### Using AI SDK Model Providers
+
+You can pass AI SDK transcription and speech models directly to CompositeVoice:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { elevenlabs } from "@ai-sdk/elevenlabs";
+
+// Use AI SDK models directly - they will be auto-wrapped
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'),      // AI SDK transcription
+  output: elevenlabs.speech('eleven_turbo_v2'),  // AI SDK speech
+});
+
+// Works the same way as with Mastra providers
+const text = await voice.listen(audioStream);
+const audio = await voice.speak("Hello from AI SDK!");
+```
+
+### Mix and Match
+
+You can combine Mastra providers with AI SDK models:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { PlayAIVoice } from "@mastra/voice-playai";
+import { groq } from "@ai-sdk/groq";
+
+const voice = new CompositeVoice({
+  input: groq.transcription('whisper-large-v3'),  // AI SDK for STT
+  output: new PlayAIVoice(),                       // Mastra for TTS
+});
+```

package/.docs/raw/reference/voice/voice.listen.mdx

@@ -7,41 +7,6 @@ description: "Documentation for the listen() method available in all Mastra voic
 
 The `listen()` method is a core function available in all Mastra voice providers that converts speech to text. It takes an audio stream as input and returns the transcribed text.
 
-## Usage Example
-
-```typescript
-import { OpenAIVoice } from "@mastra/voice-openai";
-import { getMicrophoneStream } from "@mastra/node-audio";
-import { createReadStream } from "fs";
-import path from "path";
-
-// Initialize a voice provider
-const voice = new OpenAIVoice({
-  listeningModel: {
-    name: "whisper-1",
-    apiKey: process.env.OPENAI_API_KEY,
-  },
-});
-
-// Basic usage with a file stream
-const audioFilePath = path.join(process.cwd(), "audio.mp3");
-const audioStream = createReadStream(audioFilePath);
-const transcript = await voice.listen(audioStream, {
-  filetype: "mp3",
-});
-console.log("Transcribed text:", transcript);
-
-// Using a microphone stream
-const microphoneStream = getMicrophoneStream(); // Assume this function gets audio input
-const transcription = await voice.listen(microphoneStream);
-
-// With provider-specific options
-const transcriptWithOptions = await voice.listen(audioStream, {
-  language: "en",
-  prompt: "This is a conversation about artificial intelligence.",
-});
-```
-
 ## Parameters
 
 <PropertiesTable
@@ -143,30 +108,42 @@ Each voice provider may support additional options specific to their implementat
   ]}
 />
 
-## Realtime Voice Providers
-
-When using realtime voice providers like `OpenAIRealtimeVoice`, the `listen()` method behaves differently:
-
-- Instead of returning transcribed text, it emits 'writing' events with the transcribed text
-- You need to register an event listener to receive the transcription
+## Usage Example
 
 ```typescript
-import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import { OpenAIVoice } from "@mastra/voice-openai";
 import { getMicrophoneStream } from "@mastra/node-audio";
+import { createReadStream } from "fs";
+import path from "path";
 
-const voice = new OpenAIRealtimeVoice();
-await voice.connect();
+// Initialize a voice provider
+const voice = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
 
-// Register event listener for transcription
-voice.on("writing", ({ text, role }) => {
-  console.log(`${role}: ${text}`);
+// Basic usage with a file stream
+const audioFilePath = path.join(process.cwd(), "audio.mp3");
+const audioStream = createReadStream(audioFilePath);
+const transcript = await voice.listen(audioStream, {
+  filetype: "mp3",
 });
+console.log("Transcribed text:", transcript);
 
-// This will emit 'writing' events instead of returning text
-const microphoneStream = getMicrophoneStream();
-await voice.listen(microphoneStream);
+// Using a microphone stream
+const microphoneStream = getMicrophoneStream(); // Assume this function gets audio input
+const transcription = await voice.listen(microphoneStream);
+
+// With provider-specific options
+const transcriptWithOptions = await voice.listen(audioStream, {
+  language: "en",
+  prompt: "This is a conversation about artificial intelligence.",
+});
 ```
 
+
 ## Using with CompositeVoice
 
 When using `CompositeVoice`, the `listen()` method delegates to the configured listening provider:
@@ -177,14 +154,70 @@ import { OpenAIVoice } from "@mastra/voice-openai";
 import { PlayAIVoice } from "@mastra/voice-playai";
 
 const voice = new CompositeVoice({
-  listenProvider: new OpenAIVoice(),
-  speakProvider: new PlayAIVoice(),
+  input: new OpenAIVoice(),
+  output: new PlayAIVoice(),
 });
 
 // This will use the OpenAIVoice provider
 const transcript = await voice.listen(audioStream);
 ```
 
+### Using AI SDK Model Providers
+
+You can also use AI SDK transcription models directly with `CompositeVoice`:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { groq } from "@ai-sdk/groq";
+
+// Use AI SDK transcription models
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'),  // AI SDK model
+  output: new PlayAIVoice(),                 // Mastra provider
+});
+
+// Works the same way
+const transcript = await voice.listen(audioStream);
+
+// Provider-specific options can be passed through
+const transcriptWithOptions = await voice.listen(audioStream, {
+  providerOptions: {
+    openai: {
+      language: 'en',
+      prompt: 'This is about AI',
+    }
+  }
+});
+```
+
+See the [CompositeVoice reference](/reference/v1/voice/composite-voice) for more details on AI SDK integration.
+
+
+## Realtime Voice Providers
+
+When using realtime voice providers like `OpenAIRealtimeVoice`, the `listen()` method behaves differently:
+
+- Instead of returning transcribed text, it emits 'writing' events with the transcribed text
+- You need to register an event listener to receive the transcription
+
+```typescript
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import { getMicrophoneStream } from "@mastra/node-audio";
+
+const voice = new OpenAIRealtimeVoice();
+await voice.connect();
+
+// Register event listener for transcription
+voice.on("writing", ({ text, role }) => {
+  console.log(`${role}: ${text}`);
+});
+
+// This will emit 'writing' events instead of returning text
+const microphoneStream = getMicrophoneStream();
+await voice.listen(microphoneStream);
+```
+
 ## Notes
 
 - Not all voice providers support speech-to-text functionality (e.g., PlayAI, Speechify)
@@ -194,6 +227,7 @@ const transcript = await voice.listen(audioStream);
 - Some providers support streaming transcription, where text is returned as it's transcribed
 - For best performance, consider closing or ending the audio stream when you're done with it
 
+
 ## Related Methods
 
 - [voice.speak()](./voice.speak) - Converts text to speech