@mastra/mcp-docs-server 0.13.26 → 0.13.27

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

@@ -1,673 +0,0 @@
----
-title: "Reference: Agent.streamVNext() (Experimental) | Agents | Mastra Docs"
-description: "Documentation for the `Agent.streamVNext()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
----
-
-import { StreamVNextCallout } from "@/components/streamVNext-callout.tsx"
-
-# Agent.streamVNext() (Experimental)
-
-<StreamVNextCallout />
-
-The `.streamVNext()` 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.
-
-## Usage example
-
-```ts filename="index.ts" copy
-// Default Mastra format
-const mastraStream = await agent.streamVNext("message for agent");
-
-// AI SDK v5 compatible format
-const aiSdkStream = await agent.streamVNext("message for agent", {
-  format: 'aisdk'
-});
-```
-
-## Parameters
-
-<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: "AgentExecutionOptions<Output, StructuredOutput, Format>",
-      isOptional: true,
-      description: "Optional configuration for the streaming process.",
-    },
-  ]}
-/>
-
-### Options
-
-<PropertiesTable
-  content={[
-    {
-      name: "format",
-      type: "'mastra' | 'aisdk'",
-      isOptional: true,
-      defaultValue: "'mastra'",
-      description: "Determines the output stream format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
-    },
-    {
-      name: "maxSteps",
-      type: "number",
-      isOptional: true,
-      description: "Maximum number of steps to run during execution.",
-    },
-    {
-      name: "scorers",
-      type: "MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>",
-      isOptional: true,
-      description: "Evaluation scorers to run on the execution results.",
-      properties: [
-        {
-          parameters: [{
-            name: "scorer",
-            type: "string",
-            isOptional: false,
-            description: "Name of the scorer to use."
-          }]
-        },
-        {
-          parameters: [{
-            name: "sampling",
-            type: "ScoringSamplingConfig",
-            isOptional: true,
-            description: "Sampling configuration for the scorer.",
-            properties: [
-              {
-                parameters: [{
-                  name: "type",
-                  type: "'none' | 'ratio'",
-                  isOptional: false,
-                  description: "Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling."
-                }]
-              },
-              {
-                parameters: [{
-                  name: "rate",
-                  type: "number",
-                  isOptional: true,
-                  description: "Sampling rate (0-1). Required when type is 'ratio'."
-                }]
-              }
-            ]
-          }]
-        }
-      ]
-    },
-    {
-      name: "tracingContext",
-      type: "TracingContext",
-      isOptional: true,
-      description: "AI tracing context for span hierarchy and metadata.",
-      properties: [
-        {
-          parameters: [{
-            name: "currentSpan",
-            type: "AISpan",
-            isOptional: true,
-            description: "Current AI span for creating child spans and adding metadata."
-          }]
-        }
-      ]
-    },
-    {
-      name: "tracingOptions",
-      type: "TracingOptions",
-      isOptional: true,
-      description: "Options for AI tracing configuration.",
-      properties: [
-        {
-          parameters: [{
-            name: "metadata",
-            type: "Record<string, any>",
-            isOptional: true,
-            description: "Metadata to add to the root trace span."
-          }]
-        }
-      ]
-    },
-    {
-      name: "returnScorerData",
-      type: "boolean",
-      isOptional: true,
-      description: "Whether to return detailed scoring data in the response.",
-    },
-    {
-      name: "onChunk",
-      type: "(chunk: ChunkType) => Promise<void> | void",
-      isOptional: true,
-      description: "Callback function called for each chunk during streaming.",
-    },
-    {
-      name: "onError",
-      type: "({ error }: { error: Error | string }) => Promise<void> | void",
-      isOptional: true,
-      description: "Callback function called when an error occurs during streaming.",
-    },
-    {
-      name: "onAbort",
-      type: "(event: any) => Promise<void> | void",
-      isOptional: true,
-      description: "Callback function called when the stream is aborted.",
-    },
-    {
-      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: "activeTools",
-      type: "Array<keyof ToolSet> | undefined",
-      isOptional: true,
-      description: "Array of active tool names that can be used during execution.",
-    },
-    {
-      name: "prepareStep",
-      type: "PrepareStepFunction<any>",
-      isOptional: true,
-      description: "Callback function called before each step of multi-step execution.",
-    },
-    {
-      name: "context",
-      type: "ModelMessage[]",
-      isOptional: true,
-      description: "Additional context messages to provide to the agent.",
-    },
-    {
-      name: "structuredOutput",
-      type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
-      isOptional: true,
-      description: "Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.",
-      properties: [
-        {
-          parameters: [{
-            name: "schema",
-            type: "z.ZodSchema<S>",
-            isOptional: false,
-            description: "Zod schema to validate the output against."
-          }]
-        },
-        {
-          parameters: [{
-            name: "model",
-            type: "MastraLanguageModel",
-            isOptional: true,
-            description: "Model to use for the internal structuring agent. If not provided, falls back to the agent's model."
-          }]
-        },
-        {
-          parameters: [{
-            name: "errorStrategy",
-            type: "'strict' | 'warn' | 'fallback'",
-            isOptional: true,
-            description: "Strategy when parsing or validation fails. Defaults to 'strict'."
-          }]
-        },
-        {
-          parameters: [{
-            name: "fallbackValue",
-            type: "<S extends ZodTypeAny>",
-            isOptional: true,
-            description: "Fallback value when errorStrategy is 'fallback'."
-          }]
-        },
-        {
-          parameters: [{
-            name: "instructions",
-            type: "string",
-            isOptional: true,
-            description: "Custom instructions for the structuring agent."
-          }]
-        }
-      ]
-    },
-    {
-      name: "outputProcessors",
-      type: "Processor[]",
-      isOptional: true,
-      description: "Overrides the output processors set on the agent. Output processors that can modify or validate messages from the agent before they are returned to the user. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
-    },
-    {
-      name: "inputProcessors",
-      type: "Processor[]",
-      isOptional: true,
-      description: "Overrides the input processors set on the agent. Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
-    },
-    {
-      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: "system",
-      type: "string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]",
-      isOptional: true,
-      description: "Custom system message(s) to include in the prompt. Can be a single string, message object, or array of either. System messages provide additional context or behavior instructions that supplement the agent's main instructions.",
-    },
-    {
-      name: "output",
-      type: "Zod schema | JsonSchema7",
-      isOptional: true,
-      description:
-        "**Deprecated.** Use structuredOutput with maxSteps:1 to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
-    },
-    {
-      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."
-          }]
-        }
-      ]
-    },
-    {
-      name: "onFinish",
-      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
-      isOptional: true,
-      description:
-        "Callback function called when streaming completes. Receives the final result.",
-    },
-    {
-      name: "onStepFinish",
-      type: "StreamTextOnStepFinishCallback<any> | never",
-      isOptional: true,
-      description:
-        "Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output",
-    },
-    {
-      name: "resourceId",
-      type: "string",
-      isOptional: true,
-      description:
-        "**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 OTLP telemetry collection during streaming (not AI tracing).",
-      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: "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."
-          }]
-        },
-      ]
-    },
-    {
-      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 streaming.",
-    },
-    {
-      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.",
-    },
-    {
-      name: "savePerStep",
-      type: "boolean",
-      isOptional: true,
-      description: "Save messages incrementally after each stream step completes (default: false).",
-    },
-    {
-      name: "providerOptions",
-      type: "Record<string, Record<string, JSONValue>>",
-      isOptional: true,
-      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: [
-        {
-          parameters: [{
-            name: "openai",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "OpenAI-specific options. Example: `{ reasoningEffort: 'high' }`"
-          }]
-        },
-        {
-          parameters: [{
-            name: "anthropic",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "Anthropic-specific options. Example: `{ maxTokens: 1000 }`"
-          }]
-        },
-        {
-          parameters: [{
-            name: "google",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "Google-specific options. Example: `{ safetySettings: [...] }`"
-          }]
-        },
-        {
-          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: "runId",
-      type: "string",
-      isOptional: true,
-      description: "Unique ID for this generation run. Useful for tracking and debugging purposes.",
-    },
-    {
-      name: "runtimeContext",
-      type: "RuntimeContext",
-      isOptional: true,
-      description: "Runtime context for dependency injection and contextual information.",
-    },
-    {
-      name: "stopWhen",
-      type: "StopCondition | StopCondition[]",
-      isOptional: true,
-      description: "Condition(s) that determine when to stop the agent's execution. Can be a single condition or array of conditions.",
-    },
-  ]}
-/>
-
-## Returns
-
-<PropertiesTable
-  content={[
-    {
-      name: "stream",
-      type: "MastraModelOutput<Output> | AISDKV5OutputStream<Output>",
-      description: "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput with traceId property. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
-    },
-    {
-      name: "traceId",
-      type: "string",
-      isOptional: true,
-      description: "The trace ID associated with this execution when AI tracing is enabled. Available via stream.traceId for Mastra format.",
-    },
-  ]}
-/>
-
-## Extended usage example
-
-### Mastra Format (Default)
-
-```ts filename="index.ts" showLineNumbers copy
-import { stepCountIs } from 'ai-v5';
-
-const stream = await agent.streamVNext("Tell me a story", {
-  stopWhen: stepCountIs(3), // Stop after 3 steps
-  modelSettings: {
-    temperature: 0.7,
-  },
-});
-
-// Access text stream
-for await (const chunk of stream.textStream) {
-  console.log(chunk);
-}
-
-// Get full text after streaming
-const fullText = await stream.text;
-```
-
-### AI SDK v5 Format
-
-```ts filename="index.ts" showLineNumbers copy
-import { stepCountIs } from 'ai-v5';
-
-const stream = await agent.streamVNext("Tell me a story", {
-  format: 'aisdk',
-  stopWhen: stepCountIs(3), // Stop after 3 steps
-  modelSettings: {
-    temperature: 0.7,
-  },
-});
-
-// Use with AI SDK v5 compatible interfaces
-for await (const part of stream.fullStream) {
-  if (part.type === 'text-delta') {
-    console.log(part.text);
-  }
-}
-
-// In an API route for frontend integration
-return stream.toUIMessageStreamResponse();
-```
-
-### Using Callbacks
-
-All callback functions are now available as top-level properties for a cleaner API experience.
-
-```ts filename="index.ts" showLineNumbers copy
-const stream = await agent.streamVNext("Tell me a story", {
-  onFinish: (result) => {
-    console.log('Streaming finished:', result);
-  },
-  onStepFinish: (step) => {
-    console.log('Step completed:', step);
-  },
-  onChunk: (chunk) => {
-    console.log('Received chunk:', chunk);
-  },
-  onError: ({ error }) => {
-    console.error('Streaming error:', error);
-  },
-  onAbort: (event) => {
-    console.log('Stream aborted:', event);
-  },
-});
-
-// Process the stream
-for await (const chunk of stream.textStream) {
-  console.log(chunk);
-}
-```
-
-### Advanced Example with Options
-
-```ts filename="index.ts" showLineNumbers copy
-import { z } from "zod";
-import { stepCountIs } from 'ai-v5';
-
-await agent.streamVNext("message for agent", {
-  format: 'aisdk', // Enable AI SDK v5 compatibility
-  stopWhen: stepCountIs(3), // Stop after 3 steps
-  modelSettings: {
-    temperature: 0.7,
-  },
-  memory: {
-    thread: "user-123",
-    resource: "test-app"
-  },
-  toolChoice: "auto",
-  // Structured output with better DX
-  structuredOutput: {
-    schema: z.object({
-      sentiment: z.enum(['positive', 'negative', 'neutral']),
-      confidence: z.number(),
-    }),
-    model: openai("gpt-4o-mini"),
-    errorStrategy: 'warn',
-  },
-  // Output processors for streaming response validation
-  outputProcessors: [
-    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
-    new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
-  ],
-});
-```