@mastra/mcp-docs-server 0.13.7-alpha.4 → 0.13.7

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

@@ -0,0 +1,598 @@
+---
+title: "Reference: Agent.streamVNext() | Streaming | Agents | Mastra Docs"
+description: Documentation for the `.streamVNext()` method in Mastra agents, which enables real-time streaming of responses.
+---
+
+# `streamVNext()`
+
+The `streamVNext()` method enables real-time streaming of responses from an agent. This method accepts `messages` and an optional `options` object as parameters, similar to `generate()`.
+
+## Parameters
+
+### `messages`
+
+The `messages` parameter can be:
+
+- A single string
+- An array of strings
+- An array of message objects with `role` and `content` properties
+
+The message object structure:
+
+```typescript
+interface Message {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+```
+
+### `options` (Optional)
+
+An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.
+
+<PropertiesTable
+  content={[
+    {
+      name: "abortSignal",
+      type: "AbortSignal",
+      isOptional: true,
+      description:
+        "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
+    },
+    {
+      name: "context",
+      type: "CoreMessage[]",
+      isOptional: true,
+      description: "Additional context messages to provide to the agent.",
+    },
+    {
+      name: "experimental_output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description:
+        "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description:
+        "Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.",
+    },
+    {
+      name: "memory",
+      type: "object",
+      isOptional: true,
+      description: "Configuration for memory. This is the preferred way to manage memory.",
+      properties: [
+        {
+          parameters: [{
+              name: "thread",
+              type: "string | { id: string; metadata?: Record<string, any>, title?: string }",
+              isOptional: false,
+              description: "The conversation thread, as a string ID or an object with an `id` and optional `metadata`."
+          }]
+        },
+        {
+          parameters: [{
+              name: "resource",
+              type: "string",
+              isOptional: false,
+              description: "Identifier for the user or resource associated with the thread."
+          }]
+        },
+        {
+          parameters: [{
+              name: "options",
+              type: "MemoryConfig",
+              isOptional: true,
+              description: "Configuration for memory behavior, like message history and semantic recall. See `MemoryConfig` below."
+          }]
+        }
+      ]
+    },
+    {
+      name: "maxSteps",
+      type: "number",
+      isOptional: true,
+      defaultValue: "5",
+      description: "Maximum number of steps allowed during streaming.",
+    },
+    {
+      name: "maxRetries",
+      type: "number",
+      isOptional: true,
+      defaultValue: "2",
+      description: "Maximum number of retries. Set to 0 to disable retries.",
+    },
+    {
+      name: "memoryOptions",
+      type: "MemoryConfig",
+      isOptional: true,
+      description:
+        "**Deprecated.** Use `memory.options` instead. Configuration options for memory management. See MemoryConfig section below for details.",
+    },
+    {
+      name: "onFinish",
+      type: "StreamTextOnFinishCallback | StreamObjectOnFinishCallback",
+      isOptional: true,
+      description: "Callback function called when streaming is complete.",
+    },
+    {
+      name: "onStepFinish",
+      type: "GenerateTextOnStepFinishCallback<any> | never",
+      isOptional: true,
+      description:
+        "Callback function called after each step during streaming. Unavailable for structured output",
+    },
+    {
+      name: "output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description:
+        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+    },
+    {
+      name: "telemetry",
+      type: "TelemetrySettings",
+      isOptional: true,
+      description:
+        "Settings for telemetry collection during streaming. See TelemetrySettings section below for details.",
+    },
+    {
+      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.",
+    },
+    {
+      name: "toolChoice",
+      type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
+      isOptional: true,
+      defaultValue: "'auto'",
+      description: "Controls how the agent uses tools during streaming.",
+    },
+    {
+      name: "toolsets",
+      type: "ToolsetsInput",
+      isOptional: true,
+      description:
+        "Additional toolsets to make available to the agent during this stream.",
+    },
+    {
+      name: "clientTools",
+      type: "ToolsInput",
+      isOptional: true,
+      description:
+        "Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.",
+    },
+  ]}
+/>
+
+#### MemoryConfig
+
+Configuration options for memory management:
+
+<PropertiesTable
+  content={[
+    {
+      name: "lastMessages",
+      type: "number | false",
+      isOptional: true,
+      description:
+        "Number of most recent messages to include in context. Set to false to disable.",
+    },
+    {
+      name: "semanticRecall",
+      type: "boolean | object",
+      isOptional: true,
+      description:
+        "Configuration for semantic memory recall. Can be boolean or detailed config.",
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "topK",
+              type: "number",
+              isOptional: true,
+              description:
+                "Number of most semantically similar messages to retrieve.",
+            },
+          ],
+        },
+        {
+          type: "number | object",
+          parameters: [
+            {
+              name: "messageRange",
+              type: "number | { before: number; after: number }",
+              isOptional: true,
+              description:
+                "Range of messages to consider for semantic search. Can be a single number or before/after configuration.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "workingMemory",
+      type: "object",
+      isOptional: true,
+      description: "Configuration for working memory.",
+      properties: [
+        {
+          type: "boolean",
+          parameters: [
+            {
+              name: "enabled",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether to enable working memory.",
+            },
+          ],
+        },
+        {
+          type: "string",
+          parameters: [
+            {
+              name: "template",
+              type: "string",
+              isOptional: true,
+              description: "Template to use for working memory.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "threads",
+      type: "object",
+      isOptional: true,
+      description: "Thread-specific memory configuration.",
+      properties: [
+        {
+          type: "boolean | object",
+          parameters: [
+            {
+              name: "generateTitle",
+              type: "boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>), instructions: string | ((ctx: RuntimeContext) => string | Promise<string>) }",
+              isOptional: true,
+              description:
+                `Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model and/or custom instructions for title generation (useful for cost optimization or title customization).
+Example: { model: openai('gpt-4.1-nano'), instructions: 'Generate a concise title based on the initial user message.' }`,
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+#### TelemetrySettings
+
+Settings for telemetry collection during streaming:
+
+<PropertiesTable
+  content={[
+    {
+      name: "isEnabled",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description:
+        "Enable or disable telemetry. Disabled by default while experimental.",
+    },
+    {
+      name: "recordInputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description:
+        "Enable or disable input recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "recordOutputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description:
+        "Enable or disable output recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "functionId",
+      type: "string",
+      isOptional: true,
+      description:
+        "Identifier for this function. Used to group telemetry data by function.",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, AttributeValue>",
+      isOptional: true,
+      description:
+        "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
+    },
+    {
+      name: "tracer",
+      type: "Tracer",
+      isOptional: true,
+      description:
+        "A custom OpenTelemetry tracer instance to use for the telemetry data. See OpenTelemetry documentation for details.",
+    },
+  ]}
+/>
+
+
+
+## Protocol
+
+<PropertiesTable
+  content={[
+    {
+      name: "start",
+      type: "object",
+      description: "The agent starts",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'start', runId: '1', from: 'AGENT', payload: {} }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "step-start",
+      type: "object",
+      description: "The start of a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'step-start', runId: '1', from: 'AGENT', payload: { messageId: 'uuid', request: { /* Raw request object */ }, warnings: [] } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "tool-call",
+      type: "object",
+      description: "The start of a tool call",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'tool-call', runId: '1', from: 'AGENT', payload: { toolCallId: 'uuid', args: { ... }, toolName: 'my tool' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "tool-output",
+      type: "object",
+      description: "Custom output from a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'tool-output', runId: '1', from: 'AGENT', payload: { toolName: 'my step', output: { ... }, toolCallId: 'uuid' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "tool-result",
+      type: "object",
+      description: "The result of a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'tool-result', runId: '1', from: 'AGENT', payload: { toolCallId: 'uuid', result: { ... }, toolName: 'my tool' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "step-finish",
+      type: "object",
+      description: "The end of a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'step-finish', runId: '1', from: 'AGENT', payload: { reason: 'stop', usage: { promptTokens: 100, completionTokens: 100, totalTokens: 200 }, response: Response, messageId: 'uuid', providerMetadata: { ... } } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "finish",
+      type: "object",
+      description: "The end of the workflow",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'finish', runId: '1', from: 'AGENT', payload: { totalUsage: { promptTokens: 100, completionTokens: 100, totalTokens: 200 } } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+The return value of the `streamVNext()` method is a custom MatraAgentStream. This stream extends a ReadableStream, so all basic stream methods are available.
+
+### PropertiesTable for Return Values
+
+<PropertiesTable
+  content={[
+    {
+      name: "textStream",
+      type: "ReadableStream<string>",
+      isOptional: true,
+      description:
+        "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
+    },
+    {
+      name: "usage",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "Total usage of the agent, including agents/workflows as a tool.",
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "promptTokens",
+              type: "number",
+              isOptional: true,
+              description: "The number of prompt tokens used by the agent.",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "completionTokens",
+              type: "number",
+              isOptional: true,
+              description: "The number of completion tokens used by the agent.",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "totalTokens",
+              type: "number", 
+              isOptional: true,
+              description: "The total number of tokens used by the agent.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "finishReason",
+      type: "Promise<string>",
+      isOptional: true,
+      description:
+        "The reason the agent stopped streaming.",
+    },
+    {
+      name: "toolCalls",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "The tool calls made by the agent.",
+    },
+    {
+      name: "toolResults",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "The tool results returned by the agent.",
+    },
+    {
+      name: "text",
+      type: "Promise<string>",
+      isOptional: true,
+      description:
+        "The full text of the agent's response.",
+    },
+    {
+      name: "object",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "The object of the agent's response, if you use output or experimental output.",
+    },
+  ]}
+/>
+
+## Examples
+
+### Basic Text Streaming
+
+```typescript
+const stream = await myAgent.streamVNext([
+  { role: "user", content: "Tell me a story." },
+]);
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Structured Output Streaming with Thread Context
+
+```typescript
+import { z } from "zod";
+
+const schema = z.object({
+  summary: z.string(),
+  nextSteps: z.array(z.string()),
+});
+
+const response = await myAgent.streamVNext("What should we do next?", {
+  output: schema,
+  memory: {
+    thread: "project-123",
+  },
+});
+
+const result = await response.object;
+console.log("Final structured result:", result);
+```
+

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

@@ -3,8 +3,12 @@ title: "Reference: Answer Relevancy | Metrics | Evals | Mastra Docs"
 description: Documentation for the Answer Relevancy Metric in Mastra, which evaluates how well LLM outputs address the input query.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # AnswerRelevancyMetric
 
+<ScorerCallout />
+
 The `AnswerRelevancyMetric` class evaluates how well an LLM's output answers or addresses the input query. It uses a judge-based system to determine relevancy and provides detailed scoring and reasoning.
 
 ## Basic Usage

package/.docs/raw/reference/evals/bias.mdx

@@ -3,8 +3,12 @@ title: "Reference: Bias | Output Metrics | Evals | Mastra Docs"
 description: Documentation for the Bias Metric in Mastra, which evaluates LLM outputs for various forms of bias, including gender, political, racial/ethnic, or geographical bias.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # BiasMetric
 
+<ScorerCallout />
+
 The `BiasMetric` class evaluates whether an LLM's output contains various forms of bias, including gender, political, racial/ethnic, or geographical bias. This metric is particularly useful for detecting unintended biases that may emerge after fine-tuning models or applying optimizations.
 
 ## Basic Usage

package/.docs/raw/reference/evals/completeness.mdx

@@ -3,8 +3,12 @@ title: "Reference: Completeness | Metrics | Evals | Mastra Docs"
 description: Documentation for the Completeness Metric in Mastra, which evaluates how thoroughly LLM outputs cover key elements present in the input.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # CompletenessMetric
 
+<ScorerCallout />
+
 The `CompletenessMetric` class evaluates how thoroughly an LLM's output covers the key elements present in the input. It analyzes nouns, verbs, topics, and terms to determine coverage and provides a detailed completeness score.
 
 ## Basic Usage

package/.docs/raw/reference/evals/content-similarity.mdx

@@ -3,8 +3,12 @@ title: "Reference: Content Similarity | Evals | Mastra Docs"
 description: Documentation for the Content Similarity Metric in Mastra, which measures textual similarity between strings and provides a matching score.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # ContentSimilarityMetric
 
+<ScorerCallout />
+
 The `ContentSimilarityMetric` class measures the textual similarity between two strings, providing a score that indicates how closely they match. It supports configurable options for case sensitivity and whitespace handling.
 
 ## Basic Usage

package/.docs/raw/reference/evals/context-position.mdx

@@ -3,8 +3,12 @@ title: "Reference: Context Position | Metrics | Evals | Mastra Docs"
 description: Documentation for the Context Position Metric in Mastra, which evaluates the ordering of context nodes based on their relevance to the query and output.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # ContextPositionMetric
 
+<ScorerCallout />
+
 The `ContextPositionMetric` class evaluates how well context nodes are ordered based on their relevance to the query and output. It uses position-weighted scoring to emphasize the importance of having the most relevant context pieces appear earlier in the sequence.
 
 ## Basic Usage

package/.docs/raw/reference/evals/context-precision.mdx

@@ -3,8 +3,12 @@ title: "Reference: Context Precision | Metrics | Evals | Mastra Docs"
 description: Documentation for the Context Precision Metric in Mastra, which evaluates the relevance and precision of retrieved context nodes for generating expected outputs.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # ContextPrecisionMetric
 
+<ScorerCallout />
+
 The `ContextPrecisionMetric` class evaluates how relevant and precise the retrieved context nodes are for generating the expected output. It uses a judge-based system to analyze each context piece's contribution and provides weighted scoring based on position.
 
 ## Basic Usage

package/.docs/raw/reference/evals/context-relevancy.mdx

@@ -3,8 +3,12 @@ title: "Reference: Context Relevancy | Evals | Mastra Docs"
 description: Documentation for the Context Relevancy Metric, which evaluates the relevance of retrieved context in RAG pipelines.
 ---
 
+import { ScorerCallout } from '@/components/scorer-callout'
+
 # ContextRelevancyMetric
 
+<ScorerCallout />
+
 The `ContextRelevancyMetric` class evaluates the quality of your RAG (Retrieval-Augmented Generation) pipeline's retriever by measuring how relevant the retrieved context is to the input query. It uses an LLM-based evaluation system that first extracts statements from the context and then assesses their relevance to the input.
 
 ## Basic Usage