@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-streaming-ChunkType.md

@@ -0,0 +1,292 @@
+# ChunkType
+
+The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.
+
+## Base Properties
+
+All chunks include these base properties:
+
+**type:** (`string`): The specific chunk type identifier
+
+**runId:** (`string`): Unique identifier for this execution run
+
+**from:** (`ChunkFrom`): enumAGENT:'AGENT'Chunk from agent executionUSER:'USER'Chunk from user inputSYSTEM:'SYSTEM'Chunk from system processesWORKFLOW:'WORKFLOW'Chunk from workflow execution
+
+## Text Chunks
+
+### text-start
+
+Signals the beginning of text generation.
+
+**type:** (`"text-start"`): Chunk type identifier
+
+**payload:** (`TextStartPayload`): TextStartPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### text-delta
+
+Incremental text content during generation.
+
+**type:** (`"text-delta"`): Chunk type identifier
+
+**payload:** (`TextDeltaPayload`): TextDeltaPayloadid:stringUnique identifier for this text generationtext:stringThe incremental text contentproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### text-end
+
+Signals the end of text generation.
+
+**type:** (`"text-end"`): Chunk type identifier
+
+**payload:** (`TextEndPayload`): TextEndPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Reasoning Chunks
+
+### reasoning-start
+
+Signals the beginning of reasoning generation (for models that support reasoning).
+
+**type:** (`"reasoning-start"`): Chunk type identifier
+
+**payload:** (`ReasoningStartPayload`): ReasoningStartPayloadid:stringUnique identifier for this reasoning generationsignature?:stringReasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-delta
+
+Incremental reasoning text during generation.
+
+**type:** (`"reasoning-delta"`): Chunk type identifier
+
+**payload:** (`ReasoningDeltaPayload`): ReasoningDeltaPayloadid:stringUnique identifier for this reasoning generationtext:stringThe incremental reasoning textproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-end
+
+Signals the end of reasoning generation.
+
+**type:** (`"reasoning-end"`): Chunk type identifier
+
+**payload:** (`ReasoningEndPayload`): ReasoningEndPayloadid:stringUnique identifier for this reasoning generationsignature?:stringFinal reasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-signature
+
+Contains the reasoning signature from models that support advanced reasoning (like OpenAI's o1 series). The signature represents metadata about the model's internal reasoning process, such as effort level or reasoning approach, but not the actual reasoning content itself.
+
+**type:** (`"reasoning-signature"`): Chunk type identifier
+
+**payload:** (`ReasoningSignaturePayload`): ReasoningSignaturePayloadid:stringUnique identifier for the reasoning sessionsignature:stringSignature describing the reasoning approach or effort level (e.g., reasoning effort settings)providerMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Tool Chunks
+
+### tool-call
+
+A tool is being called.
+
+**type:** (`"tool-call"`): Chunk type identifier
+
+**payload:** (`ToolCallPayload`): ToolCallPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledargs?:Record\<string, any>Arguments passed to the toolproviderExecuted?:booleanWhether the provider executed the tooloutput?:anyTool output if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-result
+
+Result from a tool execution.
+
+**type:** (`"tool-result"`): Chunk type identifier
+
+**payload:** (`ToolResultPayload`): ToolResultPayloadtoolCallId:stringUnique identifier for the tool calltoolName:stringName of the executed toolresult:anyThe result of the tool executionisError?:booleanWhether the result is an errorproviderExecuted?:booleanWhether the provider executed the toolargs?:Record\<string, any>Arguments that were passed to the toolproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-input-streaming-start
+
+Signals the start of streaming tool call arguments.
+
+**type:** (`"tool-call-input-streaming-start"`): Chunk type identifier
+
+**payload:** (`ToolCallInputStreamingStartPayload`): ToolCallInputStreamingStartPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledproviderExecuted?:booleanWhether the provider executed the tooldynamic?:booleanWhether the tool call is dynamicproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-delta
+
+Incremental tool call arguments during streaming.
+
+**type:** (`"tool-call-delta"`): Chunk type identifier
+
+**payload:** (`ToolCallDeltaPayload`): ToolCallDeltaPayloadargsTextDelta:stringIncremental text delta for tool argumentstoolCallId:stringUnique identifier for this tool calltoolName?:stringName of the tool being calledproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-input-streaming-end
+
+Signals the end of streaming tool call arguments.
+
+**type:** (`"tool-call-input-streaming-end"`): Chunk type identifier
+
+**payload:** (`ToolCallInputStreamingEndPayload`): ToolCallInputStreamingEndPayloadtoolCallId:stringUnique identifier for this tool callproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-error
+
+An error occurred during tool execution.
+
+**type:** (`"tool-error"`): Chunk type identifier
+
+**payload:** (`ToolErrorPayload`): ToolErrorPayloadid?:stringOptional identifiertoolCallId:stringUnique identifier for the tool calltoolName:stringName of the tool that failedargs?:Record\<string, any>Arguments that were passed to the toolerror:unknownThe error that occurredproviderExecuted?:booleanWhether the provider executed the toolproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Source and File Chunks
+
+### source
+
+Contains source information for content.
+
+**type:** (`"source"`): Chunk type identifier
+
+**payload:** (`SourcePayload`): SourcePayloadid:stringUnique identifiersourceType:'url' | 'document'Type of sourcetitle:stringTitle of the sourcemimeType?:stringMIME type of the sourcefilename?:stringFilename if applicableurl?:stringURL if applicableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### file
+
+Contains file data.
+
+**type:** (`"file"`): Chunk type identifier
+
+**payload:** (`FilePayload`): FilePayloaddata:string | Uint8ArrayThe file database64?:stringBase64 encoded data if applicablemimeType:stringMIME type of the fileproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Control Chunks
+
+### start
+
+Signals the start of streaming.
+
+**type:** (`"start"`): Chunk type identifier
+
+**payload:** (`StartPayload`): StartPayload\[key: string]:anyAdditional start data
+
+### step-start
+
+Signals the start of a processing step.
+
+**type:** (`"step-start"`): Chunk type identifier
+
+**payload:** (`StepStartPayload`): StepStartPayloadmessageId?:stringOptional message identifierrequest:objectRequest information including body and other datawarnings?:LanguageModelV2CallWarning\[]Any warnings from the language model call
+
+### step-finish
+
+Signals the completion of a processing step.
+
+**type:** (`"step-finish"`): Chunk type identifier
+
+**payload:** (`StepFinishPayload`): StepFinishPayloadid?:stringOptional identifiermessageId?:stringOptional message identifierstepResult:objectStep execution result with reason, warnings, and continuation infooutput:objectOutput information including usage statisticsmetadata:objectExecution metadata including request and provider infototalUsage?:LanguageModelV2UsageTotal usage statisticsresponse?:LanguageModelV2ResponseMetadataResponse metadataproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### raw
+
+Contains raw data from the provider.
+
+**type:** (`"raw"`): Chunk type identifier
+
+**payload:** (`RawPayload`): RawPayload\[key: string]:anyRaw data from the provider
+
+### finish
+
+Stream has completed successfully.
+
+**type:** (`"finish"`): Chunk type identifier
+
+**payload:** (`FinishPayload`): FinishPayloadstepResult:objectStep execution resultoutput:objectOutput information including usagemetadata:objectExecution metadatamessages:objectMessage historyresponse:objectResponse metadata and messages from the model provider
+
+### error
+
+An error occurred during streaming.
+
+**type:** (`"error"`): Chunk type identifier
+
+**payload:** (`ErrorPayload`): ErrorPayloaderror:unknownThe error that occurred
+
+### abort
+
+Stream was aborted.
+
+**type:** (`"abort"`): Chunk type identifier
+
+**payload:** (`AbortPayload`): AbortPayload\[key: string]:anyAdditional abort data
+
+## Object and Output Chunks
+
+### object
+
+Emitted when using output generation with defined schemas. Contains partial or complete structured data that conforms to the specified Zod or JSON schema. This chunk is typically skipped in some execution contexts and used for streaming structured object generation.
+
+**type:** (`"object"`): Chunk type identifier
+
+**object:** (`Partial<OUTPUT>`): Partial or complete structured data matching the defined schema. The type is determined by the OUTPUT schema parameter.
+
+### tool-output
+
+Contains output from agent or workflow execution, particularly used for tracking usage statistics and completion events. Often wraps other chunk types (like finish chunks) to provide nested execution context.
+
+**type:** (`"tool-output"`): Chunk type identifier
+
+**payload:** (`ToolOutputPayload`): ToolOutputPayloadoutput:ChunkTypeNested chunk data, often containing finish events with usage statistics
+
+### step-output
+
+Contains output from workflow step execution, used primarily for usage tracking and step completion events. Similar to tool-output but specifically for individual workflow steps.
+
+**type:** (`"step-output"`): Chunk type identifier
+
+**payload:** (`StepOutputPayload`): StepOutputPayloadoutput:ChunkTypeNested chunk data from step execution, typically containing finish events or other step results
+
+## Metadata and Special Chunks
+
+### response-metadata
+
+Contains metadata about the LLM provider's response. Emitted by some providers after text generation to provide additional context like model ID, timestamps, and response headers. This chunk is used internally for state tracking and doesn't affect message assembly.
+
+**type:** (`"response-metadata"`): Chunk type identifier
+
+**payload:** (`ResponseMetadataPayload`): ResponseMetadataPayloadsignature?:stringResponse signature if available\[key: string]:anyAdditional provider-specific metadata fields (e.g., id, modelId, timestamp, headers)
+
+### watch
+
+Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `stream()` is used.
+
+**type:** (`"watch"`): Chunk type identifier
+
+**payload:** (`WatchPayload`): WatchPayloadworkflowState?:objectCurrent workflow execution state (when used in workflows)eventTimestamp?:numberTimestamp when the event occurred\[key: string]:anyAdditional monitoring and execution data
+
+### tripwire
+
+Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
+
+**type:** (`"tripwire"`): Chunk type identifier
+
+**payload:** (`TripwirePayload`): TripwirePayloadreason:stringExplanation of why the content was blocked (e.g., 'Output processor blocked content')retry?:booleanWhether the processor requested a retry of the stepmetadata?:unknownAdditional metadata from the processor (e.g., scores, categories)processorId?:stringID of the processor that triggered the tripwire
+
+## Usage Example
+
+```typescript
+const stream = await agent.stream('Hello')
+
+for await (const chunk of stream.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta':
+      console.log('Text:', chunk.payload.text)
+      break
+
+    case 'tool-call':
+      console.log('Calling tool:', chunk.payload.toolName)
+      break
+
+    case 'tool-result':
+      console.log('Tool result:', chunk.payload.result)
+      break
+
+    case 'reasoning-delta':
+      console.log('Reasoning:', chunk.payload.text)
+      break
+
+    case 'finish':
+      console.log('Finished:', chunk.payload.stepResult.reason)
+      console.log('Usage:', chunk.payload.output.usage)
+      break
+
+    case 'error':
+      console.error('Error:', chunk.payload.error)
+      break
+  }
+}
+```
+
+## Related Types
+
+- [.stream()](https://mastra.ai/reference/streaming/agents/stream) - Method that returns streams emitting these chunks
+- [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput) - The stream object that emits these chunks
+- [workflow.stream()](https://mastra.ai/reference/streaming/workflows/stream) - Method that returns streams emitting these chunks for workflows

package/dist/docs/references/reference-streaming-agents-MastraModelOutput.md

@@ -0,0 +1,182 @@
+# MastraModelOutput
+
+The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
+
+```typescript
+// MastraModelOutput is returned by agent.stream()
+const stream = await agent.stream('Hello world')
+```
+
+For setup and basic usage, see the [.stream()](https://mastra.ai/reference/streaming/agents/stream) method documentation.
+
+## Streaming Properties
+
+These properties provide real-time access to model outputs as they're generated:
+
+**fullStream:** (`ReadableStream<ChunkType<OUTPUT>>`): ReadableStreamChunkType:ChunkType\<OUTPUT>All possible chunk types that can be emitted during streaming
+
+**textStream:** (`ReadableStream<string>`): Stream of incremental text content only. Filters out all metadata, tool calls, and control chunks to provide just the text being generated.
+
+**objectStream:** (`ReadableStream<Partial<OUTPUT>>`): ReadableStreamPartialSchemaOutput:Partial\<OUTPUT>Partially completed object matching the defined schema
+
+**elementStream:** (`ReadableStream<OUTPUT extends (infer T)[] ? T : never>`): Stream of individual array elements when the output schema defines an array type. Each element is emitted as it's completed rather than waiting for the entire array.
+
+## Promise-based Properties
+
+These properties resolve to final values after the stream completes:
+
+**text:** (`Promise<string>`): The complete concatenated text response from the model. Resolves when text generation is finished.
+
+**object:** (`Promise<OUTPUT>`): PromiseInferSchemaOutput:OUTPUTFully typed object matching the exact schema definition
+
+**reasoning:** (`Promise<string>`): Complete reasoning text for models that support reasoning (like OpenAI's o1 series). Returns empty string for models without reasoning capability.
+
+**reasoningText:** (`Promise<string | undefined>`): Alternative access to reasoning content. May be undefined for models that don't support reasoning, while 'reasoning' returns empty string.
+
+**toolCalls:** (`Promise<ToolCallChunk[]>`): ToolCallChunktype:'tool-call'Chunk type identifierrunId:stringExecution run identifierfrom:ChunkFromSource of the chunk (AGENT, WORKFLOW, etc.)payload:ToolCallPayloadTool call data including toolCallId, toolName, args, and execution details
+
+**toolResults:** (`Promise<ToolResultChunk[]>`): ToolResultChunktype:'tool-result'Chunk type identifierrunId:stringExecution run identifierfrom:ChunkFromSource of the chunk (AGENT, WORKFLOW, etc.)payload:ToolResultPayloadTool result data including toolCallId, toolName, result, and error status
+
+**usage:** (`Promise<LanguageModelUsage>`): RecordinputTokens:numberTokens consumed by the input promptoutputTokens:numberTokens generated in the responsetotalTokens:numberSum of input and output tokensreasoningTokens?:numberHidden reasoning tokens (for reasoning models)cachedInputTokens?:numberNumber of input tokens that were a cache hit
+
+**finishReason:** (`Promise<string | undefined>`): enumstop:'stop'Model finished naturallylength:'length'Hit maximum token limittool\_calls:'tool\_calls'Model called toolscontent\_filter:'content\_filter'Content was filtered
+
+**response:** (`Promise<Response>`): Responseid?:stringResponse ID from the model providertimestamp?:DateResponse timestampmodelId?:stringModel identifier used for this responseheaders?:Record\<string, string>Response headers from the model providermessages?:ResponseMessage\[]Response messages in model formatuiMessages?:UIMessage\[]Response messages in UI format, includes any metadata added by output processors
+
+## Error Properties
+
+**error:** (`string | Error | { message: string; stack: string; } | undefined`): Error information if the stream encountered an error. Undefined if no errors occurred. Can be a string message, Error object, or serialized error with stack trace.
+
+## Methods
+
+**getFullOutput:** (`() => Promise<FullOutput>`): FullOutputtext:stringComplete text responseobject?:OUTPUTStructured output if schema was providedtoolCalls:ToolCallChunk\[]All tool call chunks madetoolResults:ToolResultChunk\[]All tool result chunksusage:Record\<string, number>Token usage statisticsreasoning?:stringReasoning text if availablefinishReason?:stringWhy generation finishedresponse:ResponseResponse metadata and messages from the model provider
+
+**consumeStream:** (`(options?: ConsumeStreamOptions) => Promise<void>`): ConsumeStreamOptionsonError?:(error: Error) => voidCallback for handling stream errors
+
+## Usage Examples
+
+### Basic Text Streaming
+
+```typescript
+const stream = await agent.stream('Write a haiku')
+
+// Stream text as it's generated
+for await (const text of stream.textStream) {
+  process.stdout.write(text)
+}
+
+// Or get the complete text
+const fullText = await stream.text
+console.log(fullText)
+```
+
+### Structured Output Streaming
+
+```typescript
+const stream = await agent.stream('Generate user data', {
+  structuredOutput: {
+    schema: z.object({
+      name: z.string(),
+      age: z.number(),
+      email: z.string(),
+    }),
+  },
+})
+
+// Stream partial objects
+for await (const partial of stream.objectStream) {
+  console.log('Progress:', partial) // { name: "John" }, { name: "John", age: 30 }, ...
+}
+
+// Get final validated object
+const user = await stream.object
+console.log('Final:', user) // { name: "John", age: 30, email: "john@example.com" }
+```
+
+````text
+### Tool Calls and Results
+
+```typescript
+const stream = await agent.stream("What's the weather in NYC?", {
+  tools: { weather: weatherTool }
+});
+
+// Monitor tool calls
+const toolCalls = await stream.toolCalls;
+const toolResults = await stream.toolResults;
+
+console.log("Tools called:", toolCalls);
+console.log("Results:", toolResults);
+````
+
+### Complete Output Access
+
+```typescript
+const stream = await agent.stream('Analyze this data')
+
+const output = await stream.getFullOutput()
+console.log({
+  text: output.text,
+  usage: output.usage,
+  reasoning: output.reasoning,
+  finishReason: output.finishReason,
+})
+```
+
+### Full Stream Processing
+
+```typescript
+const stream = await agent.stream('Complex task')
+
+for await (const chunk of stream.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta':
+      process.stdout.write(chunk.payload.text)
+      break
+    case 'tool-call':
+      console.log(`Calling ${chunk.payload.toolName}...`)
+      break
+    case 'reasoning-delta':
+      console.log(`Reasoning: ${chunk.payload.text}`)
+      break
+    case 'finish':
+      console.log(`Done! Reason: ${chunk.payload.stepResult.reason}`)
+      // Access response messages with any metadata added by output processors
+      const uiMessages = chunk.payload.response?.uiMessages
+      if (uiMessages) {
+        console.log('Response messages:', uiMessages)
+      }
+      break
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+const stream = await agent.stream('Analyze this data')
+
+try {
+  // Option 1: Handle errors in consumeStream
+  await stream.consumeStream({
+    onError: error => {
+      console.error('Stream error:', error)
+    },
+  })
+
+  const result = await stream.text
+} catch (error) {
+  console.error('Failed to get result:', error)
+}
+
+// Option 2: Check error property
+const result = await stream.getFullOutput()
+if (stream.error) {
+  console.error('Stream had errors:', stream.error)
+}
+```
+
+## Related Types
+
+- [.stream()](https://mastra.ai/reference/streaming/agents/stream) - Method that returns MastraModelOutput
+- [ChunkType](https://mastra.ai/reference/streaming/ChunkType) - All possible chunk types in the full stream

package/dist/docs/references/reference-streaming-agents-streamLegacy.md

@@ -0,0 +1,142 @@
+# Agent.streamLegacy() (Legacy)
+
+> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for details on upgrading.
+
+The `.streamLegacy()` method is the legacy version of the agent streaming API, used for real-time streaming of responses from V1 model agents. This method accepts messages and optional streaming options.
+
+## Usage example
+
+```typescript
+await agent.streamLegacy('message for agent')
+```
+
+## Parameters
+
+**messages:** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options?:** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): Optional configuration for the streaming process.
+
+### Options parameters
+
+**abortSignal?:** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+
+**context?:** (`CoreMessage[]`): Additional context messages to provide to the agent.
+
+**experimental\_output?:** (`Zod schema | JsonSchema7`): Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.
+
+**instructions?:** (`string`): 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.
+
+**output?:** (`Zod schema | JsonSchema7`): Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
+
+**memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }The conversation thread, as a string ID or an object with an \`id\` and optional \`metadata\`.resource:stringIdentifier for the user or resource associated with the thread.options?:MemoryConfigConfiguration for memory behavior, like message history and semantic recall.
+
+**maxSteps?:** (`number`): Maximum number of execution steps allowed. (Default: `5`)
+
+**maxRetries?:** (`number`): Maximum number of retries. Set to 0 to disable retries. (Default: `2`)
+
+**memoryOptions?:** (`MemoryConfig`): lastMessages?:number | falseNumber of recent messages to include in context, or false to disable.semanticRecall?:boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }Enable semantic recall to find relevant past messages. Can be a boolean or detailed configuration.workingMemory?:WorkingMemoryConfiguration for working memory functionality.threads?:{ generateTitle?: boolean | { model: DynamicArgument\<MastraLanguageModel>; instructions?: DynamicArgument\<string> } }Thread-specific configuration, including automatic title generation.
+
+**onFinish?:** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
+
+**onStepFinish?:** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
+
+**resourceId?:** (`string`): \*\*Deprecated.\*\* Use \`memory.resource\` instead. Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.
+
+**telemetry?:** (`TelemetrySettings`): isEnabled?:booleanEnable or disable telemetry. Disabled by default while experimental.recordInputs?:booleanEnable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.recordOutputs?:booleanEnable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.functionId?:stringIdentifier for this function. Used to group telemetry data by function.
+
+**temperature?:** (`number`): 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.
+
+**threadId?:** (`string`): \*\*Deprecated.\*\* Use \`memory.thread\` instead. Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.
+
+**toolChoice?:** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 'auto':stringLet the model decide whether to use tools (default).'none':stringDo not use any tools.'required':stringRequire the model to use at least one tool.{ type: 'tool'; toolName: string }:objectRequire the model to use a specific tool by name. (Default: `'auto'`)
+
+**toolsets?:** (`ToolsetsInput`): Additional toolsets to make available to the agent during streaming.
+
+**clientTools?:** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
+
+**savePerStep?:** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+
+**providerOptions?:** (`Record<string, Record<string, JSONValue>>`): openai?:Record\<string, JSONValue>OpenAI-specific options. Example: \`{ reasoningEffort: 'high' }\`anthropic?:Record\<string, JSONValue>Anthropic-specific options. Example: \`{ maxTokens: 1000 }\`google?:Record\<string, JSONValue>Google-specific options. Example: \`{ safetySettings: \[...] }\`\[providerName]?:Record\<string, JSONValue>Other provider-specific options. The key is the provider name and the value is a record of provider-specific options.
+
+**runId?:** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
+
+**maxTokens?:** (`number`): Maximum number of tokens to generate.
+
+**topP?:** (`number`): Nucleus sampling. This is a number between 0 and 1. It is recommended to set either \`temperature\` or \`topP\`, but not both.
+
+**topK?:** (`number`): Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.
+
+**presencePenalty?:** (`number`): 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).
+
+**frequencyPenalty?:** (`number`): 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).
+
+**stopSequences?:** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**seed?:** (`number`): The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
+
+**headers?:** (`Record<string, string | undefined>`): Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+
+## Returns
+
+**textStream?:** (`AsyncGenerator<string>`): Async generator that yields text chunks as they become available.
+
+**fullStream?:** (`Promise<ReadableStream>`): Promise that resolves to a ReadableStream for the complete response.
+
+**text?:** (`Promise<string>`): Promise that resolves to the complete text response.
+
+**usage?:** (`Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>`): Promise that resolves to token usage information.
+
+**finishReason?:** (`Promise<string>`): Promise that resolves to the reason why the stream finished.
+
+**toolCalls?:** (`Promise<Array<ToolCall>>`): toolName:stringThe name of the tool invoked.args:anyThe arguments passed to the tool.
+
+## Extended usage example
+
+```typescript
+await agent.streamLegacy('message for agent', {
+  temperature: 0.7,
+  maxSteps: 3,
+  memory: {
+    thread: 'user-123',
+    resource: 'test-app',
+  },
+  toolChoice: 'auto',
+})
+```
+
+## Migration to New API
+
+> **Info:** The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
+
+### Quick Migration Example
+
+#### Before (Legacy)
+
+```typescript
+const result = await agent.streamLegacy('message', {
+  temperature: 0.7,
+  maxSteps: 3,
+  onFinish: result => console.log(result),
+})
+```
+
+#### After (New API)
+
+```typescript
+const result = await agent.stream('message', {
+  modelSettings: {
+    temperature: 0.7,
+  },
+  maxSteps: 3,
+  onFinish: result => console.log(result),
+})
+```
+
+## Related
+
+- [Migration Guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis)
+- [New .stream() method](https://mastra.ai/reference/streaming/agents/stream)
+- [Generating responses](https://mastra.ai/docs/agents/overview)
+- [Streaming responses](https://mastra.ai/docs/agents/overview)

package/dist/docs/references/reference-streaming-workflows-observeStream.md

@@ -0,0 +1,42 @@
+# Run.observeStream()
+
+The `.observeStream()` method opens a new `ReadableStream` to a workflow run that is currently running, allowing you to observe the stream of events if the original stream is no longer available.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+const stream = await run.observeStream()
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+## Returns
+
+`ReadableStream<ChunkType>`
+
+## Stream Events
+
+The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
+- [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream)
+- [Run.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)