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

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

@@ -1,45 +1,51 @@
 ---
-title: "Reference: Agent.stream() | Streaming | Agents | Mastra Docs"
-description: Documentation for the `.stream()` method in Mastra agents, which enables real-time streaming of responses.
+title: "Reference: stream() | Agents | Mastra Docs"
+description: "Documentation for the `.stream()` method in Mastra agents, which enables real-time streaming of responses."
 ---
 
-# `stream()`
+# stream()
 
-The `stream()` 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 `.stream()` method enables real-time streaming of responses from an agent. This method accepts messages and optional streaming options.
 
-## Parameters
-
-### `messages`
+## Usage example
 
-The `messages` parameter can be:
+```typescript showLineNumbers copy
+const response = await agent.stream("message for agent");
+```
 
-- A single string
-- An array of strings
-- An array of message objects with `role` and `content` properties
-- An array of `UIMessageWithMetadata` objects (for messages with metadata)
+## Parameters
 
-The message object structures:
+<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: "AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>",
+      isOptional: true,
+      description: "Optional configuration for the streaming process.",
+    },
+  ]}
+/>
 
-```typescript
-interface Message {
-  role: "system" | "user" | "assistant";
-  content: string;
-}
+## Extended usage example
 
-// For messages with metadata
-interface UIMessageWithMetadata {
-  role: "user" | "assistant";
-  content: string;
-  parts: Array<{ type: string; text?: string; [key: string]: any }>;
-  metadata?: Record<string, unknown>; // Optional metadata field
-}
+```typescript showLineNumbers copy
+const response = await agent.stream("message for agent", {
+  temperature: 0.7,
+  maxSteps: 3,
+  memory: {
+    thread: "user-123",
+    resource: "test-app"
+  },
+  toolChoice: "auto"
+});
 ```
 
-When using `UIMessageWithMetadata`, the metadata will be preserved throughout the conversation and stored with the messages in memory.
-
-### `options` (Optional)
-
-An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.
+### Options parameters
 
 <PropertiesTable
   content={[
@@ -70,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",
@@ -97,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."
           }]
         }
       ]
@@ -107,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",
@@ -121,27 +134,55 @@ 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.",
+      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 | StreamObjectOnFinishCallback",
-      isOptional: true,
-      description: "Callback function called when streaming is complete.",
-    },
-    {
-      name: "onStepFinish",
-      type: "GenerateTextOnStepFinishCallback<any> | never",
+      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
       isOptional: true,
       description:
-        "Callback function called after each step during streaming. Unavailable for structured output",
+        "Callback function called when streaming completes. Receives the final result.",
     },
     {
-      name: "output",
-      type: "Zod schema | JsonSchema7",
+      name: "onStepFinish",
+      type: "StreamTextOnStepFinishCallback<any> | never",
       isOptional: true,
       description:
-        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+        "Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output",
     },
     {
       name: "resourceId",
@@ -155,7 +196,41 @@ An optional object that can include configuration for output structure, memory m
       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",
@@ -177,13 +252,43 @@ An optional object that can include configuration for output structure, memory m
       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",
@@ -196,242 +301,174 @@ An optional object that can include configuration for output structure, memory m
       name: "savePerStep",
       type: "boolean",
       isOptional: true,
-      description: "Save messages incrementally after each generation step completes (default: false)",
-    }
-  ]}
-/>
-
-#### 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.",
+      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: "maxTokens",
+      type: "number",
       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: "Maximum number of tokens to generate.",
     },
     {
-      name: "recordOutputs",
-      type: "boolean",
+      name: "topP",
+      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: "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either `temperature` or `topP`, but not both.",
     },
     {
-      name: "functionId",
-      type: "string",
+      name: "topK",
+      type: "number",
       isOptional: true,
-      description:
-        "Identifier for this function. Used to group telemetry data by function.",
+      description: "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
     },
     {
-      name: "metadata",
-      type: "Record<string, AttributeValue>",
+      name: "presencePenalty",
+      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: "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: "tracer",
-      type: "Tracer",
+      name: "frequencyPenalty",
+      type: "number",
       isOptional: true,
-      description:
-        "A custom OpenTelemetry tracer instance to use for the telemetry data. See OpenTelemetry documentation for details.",
+      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.",
+    },
+    {
+      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.",
+    }
   ]}
 />
 
 ## Returns
 
-The return value of the `stream()` method depends on the options provided, specifically the `output` option.
-
-### PropertiesTable for Return Values
-
 <PropertiesTable
   content={[
     {
       name: "textStream",
-      type: "AsyncIterable<string>",
+      type: "AsyncGenerator<string>",
+      isOptional: true,
+      description:
+        "Async generator that yields text chunks as they become available.",
+    },
+    {
+      name: "fullStream",
+      type: "Promise<ReadableStream>",
       isOptional: true,
       description:
-        "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
+        "Promise that resolves to a ReadableStream for the complete response.",
     },
     {
-      name: "objectStream",
-      type: "AsyncIterable<object>",
+      name: "text",
+      type: "Promise<string>",
       isOptional: true,
       description:
-        "Stream of structured data. Present only when using `output` option with a schema.",
+        "Promise that resolves to the complete text response.",
     },
     {
-      name: "partialObjectStream",
-      type: "AsyncIterable<object>",
+      name: "usage",
+      type: "Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>",
       isOptional: true,
       description:
-        "Stream of structured data. Present only when using `experimental_output` option.",
+        "Promise that resolves to token usage information.",
     },
     {
-      name: "object",
-      type: "Promise<object>",
+      name: "finishReason",
+      type: "Promise<string>",
       isOptional: true,
       description:
-        "Promise that resolves to the final structured output. Present when using either `output` or `experimental_output` options.",
+        "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."
+          }]
+        }
+      ]
     },
   ]}
 />
-
-## Examples
-
-### Basic Text Streaming
-
-```typescript
-const stream = await myAgent.stream([
-  { 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
-const schema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    nextSteps: { type: "array", items: { type: "string" } },
-  },
-  required: ["summary", "nextSteps"],
-};
-
-const response = await myAgent.stream("What should we do next?", {
-  output: schema,
-  threadId: "project-123",
-  onFinish: (text) => console.log("Finished:", text),
-});
-
-for await (const chunk of response.textStream) {
-  console.log(chunk);
-}
-
-const result = await response.object;
-console.log("Final structured result:", result);
-```
-
-The key difference between Agent's `stream()` and LLM's `stream()` is that Agents maintain conversation context through `threadId`, can access tools, and integrate with the agent's memory system.