@mastra/mcp-docs-server 0.13.26 → 0.13.27

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

@@ -1,18 +1,32 @@
 ---
 title: "Reference: Agent.stream() | Agents | Mastra Docs"
-description: "Documentation for the `Agent.stream()` method in Mastra agents, which enables real-time streaming of responses."
+description: "Documentation for the `Agent.stream()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
 ---
 
-# Agent.stream()
+import { Callout } from 'nextra/components';
 
-The `.stream()` method enables real-time streaming of responses from an agent. This method accepts messages and optional streaming options.
+# 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.
 
 ## Usage example
 
-```typescript copy
-await agent.stream("message for agent");
+```ts filename="index.ts" copy
+// Default Mastra format
+const mastraStream = await agent.stream("message for agent");
+
+// AI SDK v5 compatible format
+const aiSdkStream = await agent.stream("message for agent", {
+  format: 'aisdk'
+});
 ```
 
+<Callout type="info">
+  **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](./streamLegacy.mdx) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
+</Callout>
+
+
 ## Parameters
 
 <PropertiesTable
@@ -24,36 +38,187 @@ await agent.stream("message for agent");
     },
     {
       name: "options",
-      type: "AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>",
+      type: "AgentExecutionOptions<Output, StructuredOutput, Format>",
       isOptional: true,
       description: "Optional configuration for the streaming process.",
     },
   ]}
 />
 
-### Options parameters
+
+
+### 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.",
+    },
+    {
+      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.",
+      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: "CoreMessage[]",
+      type: "ModelMessage[]",
       isOptional: true,
       description: "Additional context messages to provide to the agent.",
     },
     {
-      name: "experimental_output",
-      type: "Zod schema | JsonSchema7",
+      name: "structuredOutput",
+      type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
       isOptional: true,
-      description:
-        "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+      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",
@@ -62,12 +227,18 @@ await agent.stream("message for agent");
       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:
-        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+        "**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",
@@ -101,61 +272,6 @@ await agent.stream("message for agent");
         }
       ]
     },
-    {
-      name: "maxSteps",
-      type: "number",
-      isOptional: true,
-      defaultValue: "5",
-      description: "Maximum number of execution steps allowed.",
-    },
-    {
-      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.",
-      properties: [
-        {
-          parameters: [{
-            name: "lastMessages",
-            type: "number | false",
-            isOptional: true,
-            description: "Number of recent messages to include in context, or false to disable."
-          }]
-        },
-        {
-          parameters: [{
-            name: "semanticRecall",
-            type: "boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }",
-            isOptional: true,
-            description: "Enable semantic recall to find relevant past messages. Can be a boolean or detailed configuration."
-          }]
-        },
-        {
-          parameters: [{
-            name: "workingMemory",
-            type: "WorkingMemory",
-            isOptional: true,
-            description: "Configuration for working memory functionality."
-          }]
-        },
-        {
-          parameters: [{
-            name: "threads",
-            type: "{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }",
-            isOptional: true,
-            description: "Thread-specific configuration, including automatic title generation."
-          }]
-        }
-      ]
-    },
     {
       name: "onFinish",
       type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
@@ -219,11 +335,69 @@ await agent.stream("message for agent");
       ]
     },
     {
-      name: "temperature",
-      type: "number",
+      name: "modelSettings",
+      type: "CallSettings",
       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.",
+        "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",
@@ -377,50 +551,8 @@ await agent.stream("message for agent");
       name: "maxTokens",
       type: "number",
       isOptional: true,
-      description: "Maximum number of tokens to generate.",
-    },
-    {
-      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.",
-    },
-    {
-      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.",
-    },
-    {
-      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).",
-    },
-    {
-      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: "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: "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.",
+      description: "Condition(s) that determine when to stop the agent's execution. Can be a single condition or array of conditions.",
     },
-    {
-      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.",
-    }
   ]}
 />
 
@@ -429,64 +561,9 @@ await agent.stream("message for agent");
 <PropertiesTable
   content={[
     {
-      name: "textStream",
-      type: "AsyncGenerator<string>",
-      isOptional: true,
-      description:
-        "Async generator that yields text chunks as they become available.",
-    },
-    {
-      name: "fullStream",
-      type: "Promise<ReadableStream>",
-      isOptional: true,
-      description:
-        "Promise that resolves to a ReadableStream for the complete response.",
-    },
-    {
-      name: "text",
-      type: "Promise<string>",
-      isOptional: true,
-      description:
-        "Promise that resolves to the complete text response.",
-    },
-    {
-      name: "usage",
-      type: "Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>",
-      isOptional: true,
-      description:
-        "Promise that resolves to token usage information.",
-    },
-    {
-      name: "finishReason",
-      type: "Promise<string>",
-      isOptional: true,
-      description:
-        "Promise that resolves to the reason why the stream finished.",
-    },
-    {
-      name: "toolCalls",
-      type: "Promise<Array<ToolCall>>",
-      isOptional: true,
-      description:
-        "Promise that resolves to the tool calls made during the streaming process.",
-      properties: [
-        {
-          parameters: [{
-            name: "toolName",
-            type: "string",
-            required: true,
-            description: "The name of the tool invoked."
-          }]
-        },
-        {
-          parameters: [{
-            name: "args",
-            type: "any",
-            required: true,
-            description: "The arguments passed to the tool."
-          }]
-        }
-      ]
+      name: "stream",
+      type: "MastraModelOutput<Output> | AISDKV5OutputStream<Output>",
+      description: "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
     },
     {
       name: "traceId",
@@ -499,15 +576,111 @@ await agent.stream("message for agent");
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+### Mastra Format (Default)
+
+```ts filename="index.ts" showLineNumbers copy
+import { stepCountIs } from 'ai-v5';
+
+const stream = await agent.stream("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.stream("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.stream("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.stream("message for agent", {
-  temperature: 0.7,
-  maxSteps: 3,
+  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"
+  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 }),
+  ],
 });
 ```