@mastra/mcp-docs-server 0.13.44 → 0.13.45-alpha.0

package/.docs/raw/agents/adding-voice.mdx

@@ -280,6 +280,55 @@ export const agent = new Agent({
 });
 ```
 
+### 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-4o"),
+
+  // 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:

package/.docs/raw/course/01-first-agent/05-running-playground.md

@@ -1,14 +1,14 @@
-# Running the Playground
+# Running Mastra Studio
 
-To test your agent as you build it, you'll need to run the Mastra playground:
+To test your agent as you build it, you'll need to run the Mastra Studio:
 
 ```bash
 npm run dev
 ```
 
-This will start the playground at `http://localhost:4111/`, where you can interact with your agent and test its capabilities.
+This will start the studio at `http://localhost:4111`, where you can interact with your agent and test its capabilities.
 
-The playground provides a user-friendly interface for testing your agent, allowing you to:
+The studio provides a user-friendly interface for testing your agent, allowing you to:
 
 - Send messages to your agent
 - See the agent's responses
@@ -16,4 +16,4 @@ The playground provides a user-friendly interface for testing your agent, allowi
 - Test tools directly
 - Debug any issues that arise
 
-In the next step, we'll create our first agent with a simple system prompt and test it in the playground.
+In the next step, we'll create our first agent with a simple system prompt and test it in the studio.

package/.docs/raw/course/01-first-agent/09-testing-your-agent.md

@@ -1,12 +1,12 @@
 # Testing Your Agent
 
-Now let's test our agent in the playground:
+Now let's test our agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You should see your "Financial Assistant Agent" in the list of agents
 4. Try sending a message like "Hello, can you help me analyze my spending?"
 
 At this point, your agent can respond to basic questions but doesn't have access to any transaction data. In the next step, we'll create a custom tool to fetch transaction data from a Google Sheet.
 
-Testing your agent in the playground is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.
+Testing your agent in the studio is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.

package/.docs/raw/course/01-first-agent/13-testing-your-tool.md

@@ -1,9 +1,9 @@
 # Testing Your Tool
 
-Let's test our tool and agent in the playground:
+Let's test our tool and agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You can test the tool directly in the Tools tab to make sure it's working
 4. Then, try asking your agent questions like:
    - "Can you show me my recent transactions?"
@@ -12,4 +12,4 @@ Let's test our tool and agent in the playground:
 
 Your agent should now be able to fetch the transaction data and answer questions about it. However, it doesn't yet have memory, so it won't remember previous conversations. We'll add that in the next step.
 
-Testing your tool directly in the playground is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.
+Testing your tool directly in the studio is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.

package/.docs/raw/course/01-first-agent/17-testing-memory.md

@@ -1,9 +1,9 @@
 # Testing Your Agent with Memory
 
-Let's test our agent's memory capabilities in the playground:
+Let's test our agent's memory capabilities in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. Start a conversation with your agent by asking about transactions
 4. Then, ask a follow-up question that references the previous conversation, like:
    - "What was that largest transaction again?"

package/.docs/raw/course/04-workflows/07-using-playground.md

@@ -14,7 +14,7 @@ You should see output like:
 
 ```bash
 🚀 Mastra Dev Server starting...
-📊 Playground available at: http://localhost:4111
+📊 Studio available at: http://localhost:4111
 ```
 
 ## Accessing Workflows in Playground

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -118,7 +118,7 @@ export const mastra = new Mastra({
     apiRoutes: [
       workflowRoute({
         path: "/workflow",
-        agent: "weatherAgent",
+        workflow: "weatherWorkflow",
       }),
     ],
   },
@@ -148,6 +148,28 @@ const { error, status, sendMessage, messages, regenerate, stop } = useChat({
 });
 ```
 
+To  enable agent text chunks and tool calls streaming when a workflow step pipes an agent's stream to the workflow writer (see [Workflow Streaming](/docs/streaming/workflow-streaming#workflow-using-an-agent)).
+
+Set the `includeTextStreamParts` `workflowRoute` option to `true`
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core/mastra";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow",
+        workflow: "weatherWorkflow",
+        //This provides a seamless streaming experience even when agents are running inside workflow steps.
+        includeTextStreamParts: true
+      }),
+    ],
+  },
+});
+```
+
+
 ### `networkRoute()`
 
 Use the `networkRoute()` utility to create a route handler that automatically formats the agent network stream into an AI SDK-compatible format.

package/.docs/raw/reference/client-js/memory.mdx

@@ -125,6 +125,49 @@ const result = await thread.deleteMessages([
 // Returns: { success: true, message: "3 messages deleted successfully" }
 ```
 
+## Working Memory
+
+Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
+
+### Get Working Memory
+
+Retrieve the current working memory for a thread:
+
+```typescript
+const workingMemory = await mastraClient.getWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+```
+
+The response includes:
+- `workingMemory`: The current working memory content (string or null)
+- `source`: Whether the memory is from `"thread"` or `"resource"` scope
+- `workingMemoryTemplate`: The template used for working memory (if configured)
+- `threadExists`: Whether the thread exists
+
+### Update Working Memory
+
+Update the working memory content for a thread:
+
+```typescript
+await mastraClient.updateWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  workingMemory: `# User Profile
+- Name: John Doe
+- Location: New York
+- Preferences: Prefers formal communication
+`,
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+
+// Returns: { success: true }
+```
+
+**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+
 ### Get Memory Status
 
 Check the status of the memory system:

package/.docs/raw/reference/core/mastra-class.mdx

@@ -139,5 +139,13 @@ export const mastra = new Mastra({
       isOptional: true,
       defaultValue: "{}",
     },
+    {
+      name: "gateways",
+      type: "Record<string, MastraModelGateway>",
+      description:
+        "Custom model gateways to register for accessing AI models through alternative providers or private deployments. Structured as a key-value pair, with keys being the registry key (used for getGateway()) and values being gateway instances.",
+      isOptional: true,
+      defaultValue: "{}",
+    },
   ]}
 />

package/.docs/raw/reference/core/mastra-model-gateway.mdx

@@ -0,0 +1,223 @@
+---
+title: "Reference: MastraModelGateway | Core"
+description: "Base class for creating custom model gateways"
+---
+
+# MastraModelGateway
+
+Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
+
+## Class Overview
+
+```typescript
+import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
+import type { LanguageModelV2 } from '@ai-sdk/provider-v5';
+
+class MyCustomGateway extends MastraModelGateway {
+  readonly id = 'custom';
+  readonly name = 'My Custom Gateway';
+
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['model-1', 'model-2'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: this.id,
+      },
+    };
+  }
+
+  buildUrl(modelId: string, envVars?: Record<string, string>): string {
+    return 'https://api.my-provider.com/v1';
+  }
+
+  async getApiKey(modelId: string): Promise<string> {
+    const apiKey = process.env.MY_API_KEY;
+    if (!apiKey) throw new Error('MY_API_KEY not set');
+    return apiKey;
+  }
+
+  async resolveLanguageModel({
+    modelId,
+    providerId,
+    apiKey,
+  }: {
+    modelId: string;
+    providerId: string;
+    apiKey: string;
+  }): Promise<LanguageModelV2> {
+    const baseURL = this.buildUrl(`${providerId}/${modelId}`);
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL,
+    }).chatModel(modelId);
+  }
+}
+```
+
+## Required Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: 'id',
+      type: 'string',
+      description: 'Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn\'t use a prefix.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Human-readable name for the gateway.',
+    },
+  ]}
+/>
+
+## Required Methods
+
+### fetchProviders()
+
+Fetches provider configurations from the gateway.
+
+**Returns:** `Promise<Record<string, ProviderConfig>>`
+
+**ProviderConfig Structure:**
+<PropertiesTable
+  content={[
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Display name of the provider',
+    },
+    {
+      name: 'models',
+      type: 'string[]',
+      description: 'Array of available model IDs',
+    },
+    {
+      name: 'apiKeyEnvVar',
+      type: 'string | string[]',
+      description: 'Environment variable(s) for API key',
+    },
+    {
+      name: 'gateway',
+      type: 'string',
+      description: 'Gateway identifier',
+    },
+    {
+      name: 'url',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional base API URL',
+    },
+    {
+      name: 'apiKeyHeader',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional custom auth header name',
+    },
+    {
+      name: 'docUrl',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional documentation URL',
+    },
+  ]}
+/>
+
+### buildUrl()
+
+Builds the API URL for a specific model/provider combination.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID (e.g., "custom/my-provider/model-1")',
+    },
+    {
+      name: 'envVars',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description: 'Optional environment variables',
+    },
+  ]}
+/>
+
+**Returns:** `string | undefined | Promise<string | undefined>`
+
+### getApiKey()
+
+Retrieves the API key for authentication.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<string>`
+
+### resolveLanguageModel()
+
+Creates a language model instance.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'The model ID',
+    },
+    {
+      name: 'providerId',
+      type: 'string',
+      description: 'The provider ID',
+    },
+    {
+      name: 'apiKey',
+      type: 'string',
+      description: 'The API key for authentication',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<LanguageModelV2> | LanguageModelV2`
+
+## Instance Methods
+
+### getId()
+
+Returns the gateway's unique identifier.
+
+**Returns:** `string` - The gateway's `id` property
+
+## Model ID Format
+
+For true gateways, the gateway ID is used as a prefix and models are accessed using this format:
+
+```
+[gateway-id]/[provider]/[model]
+```
+
+Examples:
+- Gateway with `id = 'custom'`: `'custom/my-provider/model-1'`
+
+## Built-in Implementations
+
+- **NetlifyGateway** - Netlify AI Gateway integration
+- **ModelsDevGateway** - Registry of OpenAI-compatible providers
+
+## Related
+
+- [Custom Gateways Guide](/models/gateways/custom-gateways) - Complete guide to creating custom gateways

package/.docs/raw/reference/scorers/answer-relevancy.mdx

@@ -112,115 +112,45 @@ A relevancy score between 0 and 1:
 - **0.1–0.3**: The response includes minimal relevant content and largely misses the intent of the query.
 - **0.0**: The response is entirely unrelated and does not answer the query.
 
-## Examples
+## Example
 
-### High relevancy example
+Evaluate agent responses for relevancy across different scenarios:
 
-In this example, the response accurately addresses the input query with specific and relevant information.
-
-```typescript title="src/example-high-answer-relevancy.ts" showLineNumbers copy
+```typescript title="src/example-answer-relevancy.ts" showLineNumbers copy
+import { runExperiment } from "@mastra/core/scores";
 import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
+import { myAgent } from "./agent";
 
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
+const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o" });
 
-const inputMessages = [
-  {
-    role: "user",
-    content: "What are the health benefits of regular exercise?",
+const result = await runExperiment({
+  data: [
+    {
+      input: "What are the health benefits of regular exercise?",
+    },
+    {
+      input: "What should a healthy breakfast include?",
+    },
+    {
+      input: "What are the benefits of meditation?",
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.name].score,
+      reason: scorerResults[scorer.name].reason,
+    });
   },
-];
-const outputMessage = {
-  text: "Regular exercise improves cardiovascular health, strengthens muscles, boosts metabolism, and enhances mental well-being through the release of endorphins.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
 });
 
-console.log(result);
+console.log(result.scores);
 ```
 
-#### High relevancy output
-
-The output receives a high score because it accurately answers the query without including unrelated information.
-
-```typescript
-{
-  score: 1,
-  reason: 'The score is 1 because the output directly addresses the question by providing multiple explicit health benefits of regular exercise, including improvements in cardiovascular health, muscle strength, metabolism, and mental well-being. Each point is relevant and contributes to a comprehensive understanding of the health benefits.'
-}
-```
+For more details on `runExperiment`, see the [runExperiment reference](/reference/scorers/run-experiment).
 
-### Partial relevancy example
-
-In this example, the response addresses the query in part but includes additional information that isn’t directly relevant.
-
-```typescript title="src/example-partial-answer-relevancy.ts" showLineNumbers copy
-import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
-
-const inputMessages = [
-  { role: "user", content: "What should a healthy breakfast include?" },
-];
-const outputMessage = {
-  text: "A nutritious breakfast should include whole grains and protein. However, the timing of your breakfast is just as important - studies show eating within 2 hours of waking optimizes metabolism and energy levels throughout the day.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
-});
-
-console.log(result);
-```
-
-#### Partial relevancy output
-
-The output receives a lower score because it partially answers the query. While some relevant information is included, unrelated details reduce the overall relevance.
-
-```typescript
-{
-  score: 0.25,
-  reason: 'The score is 0.25 because the output provides a direct answer by mentioning whole grains and protein as components of a healthy breakfast, which is relevant. However, the additional information about the timing of breakfast and its effects on metabolism and energy levels is not directly related to the question, leading to a lower overall relevance score.'
-}
-```
-
-## Low relevancy example
-
-In this example, the response does not address the query and contains information that is entirely unrelated.
-
-```typescript title="src/example-low-answer-relevancy.ts" showLineNumbers copy
-import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
-
-const inputMessages = [
-  { role: "user", content: "What are the benefits of meditation?" },
-];
-const outputMessage = {
-  text: "The Great Wall of China is over 13,000 miles long and was built during the Ming Dynasty to protect against invasions.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
-});
-
-console.log(result);
-```
-
-#### Low relevancy output
-
-The output receives a score of 0 because it fails to answer the query or provide any relevant information.
-
-```typescript
-{
-  score: 0,
-  reason: 'The score is 0 because the output about the Great Wall of China is completely unrelated to the benefits of meditation, providing no relevant information or context that addresses the input question.'
-}
-```
+To add this scorer to an agent, see the [Scorers overview](/docs/scorers/overview) guide.
 
 ## Related