@mastra/mcp-docs-server 0.13.10 → 0.13.11-alpha.1

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

@@ -1,34 +1,51 @@
 ---
-title: "Reference: Agent.streamVNext() | Streaming | Agents | Mastra Docs"
-description: Documentation for the `.streamVNext()` method in Mastra agents, which enables real-time streaming of responses.
+title: "Reference: streamVNext() | Agents | Mastra Docs"
+description: "Documentation for the `.streamVNext()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
 ---
 
-# `streamVNext()`
+# 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()`.
+The `.streamVNext()` method enables real-time streaming of responses from an agent with enhanced capabilities. This method accepts messages and optional streaming options, providing a next-generation streaming experience.
 
-## Parameters
+## Usage example
 
-### `messages`
+```typescript showLineNumbers copy
+const response = await agent.streamVNext("message for agent");
+```
 
-The `messages` parameter can be:
+## Parameters
 
-- A single string
-- An array of strings
-- An array of message objects with `role` and `content` properties
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]",
+      description: "The messages to send to the agent. Can be a single string, array of strings, or structured message objects.",
+    },
+    {
+      name: "options",
+      type: "AgentVNextStreamOptions<Output, StructuredOutput>",
+      isOptional: true,
+      description: "Optional configuration for the streaming process.",
+    },
+  ]}
+/>
 
-The message object structure:
+## Extended usage example
 
-```typescript
-interface Message {
-  role: "system" | "user" | "assistant";
-  content: string;
-}
+```typescript showLineNumbers copy
+const response = await agent.streamVNext("message for agent", {
+  temperature: 0.7,
+  maxSteps: 3,
+  memory: {
+    thread: "user-123",
+    resource: "test-app"
+  },
+  toolChoice: "auto"
+});
 ```
 
-### `options` (Optional)
-
-An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.
+### Options parameters
 
 <PropertiesTable
   content={[
@@ -59,6 +76,13 @@ An optional object that can include configuration for output structure, memory m
       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: "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: "memory",
       type: "object",
@@ -86,7 +110,7 @@ An optional object that can include configuration for output structure, memory m
               name: "options",
               type: "MemoryConfig",
               isOptional: true,
-              description: "Configuration for memory behavior, like message history and semantic recall. See `MemoryConfig` below."
+              description: "Configuration for memory behavior, like message history and semantic recall."
           }]
         }
       ]
@@ -96,7 +120,7 @@ An optional object that can include configuration for output structure, memory m
       type: "number",
       isOptional: true,
       defaultValue: "5",
-      description: "Maximum number of steps allowed during streaming.",
+      description: "Maximum number of execution steps allowed.",
     },
     {
       name: "maxRetries",
@@ -110,34 +134,69 @@ An optional object that can include configuration for output structure, memory m
       type: "MemoryConfig",
       isOptional: true,
       description:
-        "**Deprecated.** Use `memory.options` instead. Configuration options for memory management. See MemoryConfig section below for details.",
+        "**Deprecated.** Use `memory.options` instead. Configuration options for memory management.",
     },
     {
       name: "onFinish",
-      type: "StreamTextOnFinishCallback | StreamObjectOnFinishCallback",
+      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
       isOptional: true,
-      description: "Callback function called when streaming is complete.",
+      description:
+        "Callback function called when streaming completes. Receives the final result.",
     },
     {
       name: "onStepFinish",
-      type: "GenerateTextOnStepFinishCallback<any> | never",
+      type: "StreamTextOnStepFinishCallback<any> | never",
       isOptional: true,
       description:
-        "Callback function called after each step during streaming. Unavailable for structured output",
+        "Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output",
     },
     {
-      name: "output",
-      type: "Zod schema | JsonSchema7",
+      name: "resourceId",
+      type: "string",
       isOptional: true,
       description:
-        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+        "**Deprecated.** Use `memory.resource` instead. Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.",
     },
     {
       name: "telemetry",
       type: "TelemetrySettings",
       isOptional: true,
       description:
-        "Settings for telemetry collection during streaming. See TelemetrySettings section below for details.",
+        "Settings for telemetry collection during streaming.",
+      properties: [
+        {
+          parameters: [{
+            name: "isEnabled",
+            type: "boolean",
+            isOptional: true,
+            description: "Enable or disable telemetry. Disabled by default while experimental."
+          }]
+        },
+        {
+          parameters: [{
+            name: "recordInputs",
+            type: "boolean",
+            isOptional: true,
+            description: "Enable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information."
+          }]
+        },
+        {
+          parameters: [{
+            name: "recordOutputs",
+            type: "boolean",
+            isOptional: true,
+            description: "Enable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information."
+          }]
+        },
+        {
+          parameters: [{
+            name: "functionId",
+            type: "string",
+            isOptional: true,
+            description: "Identifier for this function. Used to group telemetry data by function."
+          }]
+        }
+      ]
     },
     {
       name: "temperature",
@@ -146,19 +205,56 @@ An optional object that can include configuration for output structure, memory m
       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: "threadId",
+      type: "string",
+      isOptional: true,
+      description:
+        "**Deprecated.** Use `memory.thread` instead. Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.",
+    },
     {
       name: "toolChoice",
       type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
       isOptional: true,
       defaultValue: "'auto'",
       description: "Controls how the agent uses tools during streaming.",
+      properties: [
+        {
+          parameters: [{
+            name: "'auto'",
+            type: "string",
+            description: "Let the model decide whether to use tools (default)."
+          }]
+        },
+        {
+          parameters: [{
+            name: "'none'",
+            type: "string",
+            description: "Do not use any tools."
+          }]
+        },
+        {
+          parameters: [{
+            name: "'required'",
+            type: "string",
+            description: "Require the model to use at least one tool."
+          }]
+        },
+        {
+          parameters: [{
+            name: "{ type: 'tool'; toolName: string }",
+            type: "object",
+            description: "Require the model to use a specific tool by name."
+          }]
+        }
+      ]
     },
     {
       name: "toolsets",
       type: "ToolsetsInput",
       isOptional: true,
       description:
-        "Additional toolsets to make available to the agent during this stream.",
+        "Additional toolsets to make available to the agent during streaming.",
     },
     {
       name: "clientTools",
@@ -167,432 +263,142 @@ An optional object that can include configuration for output structure, memory m
       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",
+      name: "savePerStep",
+      type: "boolean",
       isOptional: true,
-      description:
-        "Number of most recent messages to include in context. Set to false to disable.",
+      description: "Save messages incrementally after each stream step completes (default: false).",
     },
     {
-      name: "semanticRecall",
-      type: "boolean | object",
+      name: "providerOptions",
+      type: "Record<string, Record<string, JSONValue>>",
       isOptional: true,
-      description:
-        "Configuration for semantic memory recall. Can be boolean or detailed config.",
+      description: "Additional provider-specific options that are passed through to the underlying LLM provider. The structure is `{ providerName: { optionKey: value } }`. For example: `{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }`.",
       properties: [
         {
-          type: "number",
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Number of most semantically similar messages to retrieve.",
-            },
-          ],
+          parameters: [{
+            name: "openai",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "OpenAI-specific options. Example: `{ reasoningEffort: 'high' }`"
+          }]
         },
         {
-          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.",
-            },
-          ],
+          parameters: [{
+            name: "anthropic",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Anthropic-specific options. Example: `{ maxTokens: 1000 }`"
+          }]
         },
-      ],
-    },
-    {
-      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.",
-            },
-          ],
+          parameters: [{
+            name: "google",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Google-specific options. Example: `{ safetySettings: [...] }`"
+          }]
         },
         {
-          type: "string",
-          parameters: [
-            {
-              name: "template",
-              type: "string",
-              isOptional: true,
-              description: "Template to use for working memory.",
-            },
-          ],
-        },
-      ],
+          parameters: [{
+            name: "[providerName]",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Other provider-specific options. The key is the provider name and the value is a record of provider-specific options."
+          }]
+        }
+      ]
     },
     {
-      name: "threads",
-      type: "object",
+      name: "runId",
+      type: "string",
       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.' }`,
-            },
-          ],
-        },
-      ],
+      description: "Unique ID for this generation run. Useful for tracking and debugging purposes.",
     },
-  ]}
-/>
-
-#### TelemetrySettings
-
-Settings for telemetry collection during streaming:
-
-<PropertiesTable
-  content={[
     {
-      name: "isEnabled",
-      type: "boolean",
+      name: "runtimeContext",
+      type: "RuntimeContext",
       isOptional: true,
-      defaultValue: "false",
-      description:
-        "Enable or disable telemetry. Disabled by default while experimental.",
+      description: "Runtime context for dependency injection and contextual information.",
     },
     {
-      name: "recordInputs",
-      type: "boolean",
+      name: "experimental_generateMessageId",
+      type: "IDGenerator",
       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.",
+      description: "Generate a unique ID for each message.",
     },
     {
-      name: "recordOutputs",
-      type: "boolean",
+      name: "maxTokens",
+      type: "number",
       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.",
+      description: "Maximum number of tokens to generate.",
     },
     {
-      name: "functionId",
-      type: "string",
+      name: "topP",
+      type: "number",
       isOptional: true,
-      description:
-        "Identifier for this function. Used to group telemetry data by function.",
+      description: "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either `temperature` or `topP`, but not both.",
     },
     {
-      name: "metadata",
-      type: "Record<string, AttributeValue>",
+      name: "topK",
+      type: "number",
       isOptional: true,
-      description:
-        "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
+      description: "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
     },
     {
-      name: "tracer",
-      type: "Tracer",
+      name: "presencePenalty",
+      type: "number",
       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,
-            },
-          ],
-        },
-      ],
+      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).",
     },
     {
-      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: "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).",
     },
     {
-      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: "stopSequences",
+      type: "string[]",
+      isOptional: true,
+      description: "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
     },
     {
-      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: "seed",
+      type: "number",
+      isOptional: true,
+      description: "The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.",
     },
     {
-      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: "headers",
+      type: "Record<string, string | undefined>",
+      isOptional: true,
+      description: "Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.",
     },
     {
-      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: "system",
+      type: "string",
+      isOptional: true,
+      description: "System message to include in the prompt. Can be used with `prompt` or `messages`.",
     },
     {
-      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,
-            },
-          ],
-        },
-      ],
-    },
+      name: "prompt",
+      type: "string",
+      isOptional: true,
+      description: "A simple text prompt. You can either use `prompt` or `messages` but not both.",
+    }
   ]}
 />
 
 ## 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.",
+      name: "stream",
+      type: "MastraAgentStream<Output extends ZodSchema ? z.infer<Output> : StructuredOutput extends ZodSchema ? z.infer<StructuredOutput> : unknown>",
+      description: "A streaming interface that provides enhanced streaming capabilities for text and structured 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);
-```
-