@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/streaming/agents/stream.md

@@ -0,0 +1,221 @@
+# 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
+
+```ts
+const stream = await agent.stream('message for agent')
+```
+
+> **Info:** **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](https://mastra.ai/reference/streaming/agents/streamLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
+
+## 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?:** (`AgentExecutionOptions<Output, Format>`): Optional configuration for the streaming process.
+
+### Options
+
+**maxSteps?:** (`number`): Maximum number of steps to run during execution.
+
+**scorers?:** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): scorer:stringName of the scorer to use.sampling?:ScoringSamplingConfigSampling configuration for the scorer.type:'none' | 'ratio'Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling.rate?:numberSampling rate (0-1). Required when type is 'ratio'.
+
+**onIterationComplete?:** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): context.iteration:numberCurrent iteration number (1-based).context.maxIterations:number | undefinedMaximum iterations allowed (if set).context.text:stringThe text response from this iteration.context.isFinal:booleanWhether this is the final iteration.context.finishReason:stringReason why this iteration finished (e.g., 'stop', 'length', 'tool-calls').context.toolCalls:ToolCall\[]Tool calls made in this iteration.context.messages:MastraDBMessage\[]All messages accumulated so far.return.continue?:booleanSet to false to stop execution early.return.feedback?:stringFeedback message to guide the agent's next iteration.
+
+**isTaskComplete?:** (`IsTaskCompleteConfig`): scorers:MastraScorer\[]Array of scorers that evaluate task completion. Each scorer returns 0 (failed) or 1 (passed).strategy?:'all' | 'any'Strategy for combining scorer results. 'all' requires all scorers to pass, 'any' requires at least one.onComplete?:(result: IsTaskCompleteRunResult) => void | Promise\<void>Callback called when the task completion check finishes. Receives the result with individual scorer scores.parallel?:booleanWhether to run scorers in parallel.timeout?:numberMaximum time in milliseconds to wait for all scorers to complete.
+
+**delegation?:** (`DelegationConfig`): onDelegationStart?:(context: DelegationStartContext) => DelegationStartResult | void | Promise\<DelegationStartResult | void>Called before delegating to a subagent. Use this to modify the delegation parameters or reject the delegation entirely.onDelegationComplete?:(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>Called after a subagent delegation completes. The context includes a \`bail()\` method to stop further execution, and you can return \`{ feedback }\` to guide the supervisor's next action. Feedback is saved to supervisor memory as an assistant message.messageFilter?:(context: MessageFilterContext) => MastraDBMessage\[] | Promise\<MastraDBMessage\[]>Callback function called before delegating to a subagent. Use this to filter the messages that are passed to the subagent.
+
+**tracingContext?:** (`TracingContext`): Tracing context for span hierarchy and metadata.
+
+**returnScorerData?:** (`boolean`): Whether to return detailed scoring data in the response.
+
+**onChunk?:** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk during streaming.
+
+**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
+
+**onAbort?:** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+
+**abortSignal?:** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+
+**activeTools?:** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
+
+**prepareStep?:** (`PrepareStepFunction<any>`): Callback function called before each step of multi-step execution.
+
+**context?:** (`ModelMessage[]`): Additional context messages to provide to the agent.
+
+**structuredOutput?:** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): schema:z.ZodSchema\<S>Zod schema defining the expected output structure.model?:MastraLanguageModelLanguage model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured outputerrorStrategy?:'strict' | 'warn' | 'fallback'Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values.fallbackValue?:\<S extends ZodTypeAny>Fallback value to use when schema validation fails and errorStrategy is 'fallback'.instructions?:stringAdditional instructions for the structured output model.jsonPromptInjection?:booleanInjects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.providerOptions?:ProviderOptionsProvider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`).
+
+**outputProcessors?:** (`Processor[]`): 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.
+
+**includeRawChunks?:** (`boolean`): Whether to include raw chunks in the stream output (not available on all model providers).
+
+**inputProcessors?:** (`Processor[]`): 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.
+
+**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.
+
+**system?:** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): 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.
+
+**output?:** (`Zod schema | JsonSchema7`): \*\*Deprecated.\*\* Use structuredOutput without a model to achieve the same thing. 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 including lastMessages, readOnly, semanticRecall, and workingMemory.
+
+**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
+
+**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.
+
+**modelSettings?:** (`CallSettings`): temperature?:numberControls randomness in generation (0-2). Higher values make output more random.maxOutputTokens?:numberMaximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.maxRetries?:numberMaximum number of retry attempts for failed requests.topP?:numberNucleus sampling parameter (0-1). Controls diversity of generated text.topK?:numberTop-k sampling parameter. Limits vocabulary to k most likely tokens.presencePenalty?:numberPenalty for token presence (-2 to 2). Reduces repetition.frequencyPenalty?:numberPenalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.stopSequences?:string\[]Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**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).
+
+**requireToolApproval?:** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit \`tool-call-approval\` chunks and pause until \`approveToolCall()\` or \`declineToolCall()\` is called.
+
+**autoResumeSuspendedTools?:** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts \`resumeData\` from the user's message based on the tool's \`resumeSchema\`. Requires memory to be configured.
+
+**toolCallConcurrency?:** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
+
+**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.
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+## Returns
+
+**stream:** (`MastraModelOutput<Output>`): Returns a MastraModelOutput instance that provides access to the streaming output.
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+## Extended usage example
+
+### Mastra Format (Default)
+
+```ts
+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)
+}
+
+// or access full stream
+for await (const chunk of stream.fullStream) {
+  console.log(chunk)
+}
+
+// Get full text after streaming
+const fullText = await stream.text
+```
+
+### AI SDK v5+ Format
+
+To use the stream with AI SDK v5 (and later), you can convert it using our utility function `toAISdkStream`.
+
+```ts
+import { stepCountIs, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+const stream = await agent.stream('Tell me a story', {
+  stopWhen: stepCountIs(3), // Stop after 3 steps
+  modelSettings: {
+    temperature: 0.7,
+  },
+})
+
+// In an API route for frontend integration
+return createUIMessageStreamResponse({
+  stream: toAISdkStream(stream, { from: 'agent' }),
+})
+```
+
+### Using Callbacks
+
+All callback functions are now available as top-level properties for a cleaner API experience.
+
+```ts
+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
+import { z } from 'zod'
+import { stepCountIs } from 'ai'
+
+await agent.stream('message for agent', {
+  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-5.1',
+    errorStrategy: 'warn',
+  },
+  // Output processors for streaming response validation
+  outputProcessors: [
+    new ModerationProcessor({ model: 'openrouter/openai/gpt-oss-safeguard-20b' }),
+    new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
+  ],
+})
+```
+
+## Related
+
+- [Generating responses](https://mastra.ai/docs/agents/overview)
+- [Streaming responses](https://mastra.ai/docs/agents/overview)
+- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Networks](https://mastra.ai/docs/agents/networks) - Using the supervisor pattern for multi-agent coordination
+- [Migration: .network() to Supervisor Pattern](https://mastra.ai/guides/migrations/network-to-supervisor)
+- [Guide: Research Coordinator](https://mastra.ai/guides/guide/research-coordinator)

package/.docs/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/.docs/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)

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -0,0 +1,61 @@
+# Run.resumeStream()
+
+The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+const result = await stream.result
+
+if (result!.status === 'suspended') {
+  const resumedStream = await run.resumeStream({
+    resumeData: {
+      value: 'resume data',
+    },
+  })
+}
+```
+
+## Parameters
+
+**resumeData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+
+**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+
+**step?:** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+## Returns
+
+**stream:** (`MastraWorkflowStream<ChunkType>`): A custom stream that extends ReadableStream\<ChunkType> with additional workflow-specific properties
+
+**stream.status:** (`Promise<RunStatus>`): A promise that resolves to the current workflow run status
+
+**stream.result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+
+**stream.usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>`): A promise that resolves to token usage statistics
+
+## 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)

package/.docs/reference/streaming/workflows/stream.md

@@ -0,0 +1,88 @@
+# Run.stream()
+
+The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+## Parameters
+
+**inputData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+
+**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**closeOnSuspend?:** (`boolean`): Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.
+
+## Returns
+
+Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
+
+**fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.
+
+**result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+
+**status:** (`WorkflowRunStatus`): The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')
+
+**usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>`): A promise that resolves to token usage statistics
+
+## Extended usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+
+// Access the final result
+const result = await stream.result
+console.log('Final result:', result)
+
+// Access token usage
+const usage = await stream.usage
+console.log('Token usage:', usage)
+
+// Check current status
+console.log('Status:', stream.status)
+```
+
+## 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-progress`**: A foreach step reports per-iteration progress (includes `completedCount`, `totalCount`, `currentIndex`, `iterationStatus`, and optional `iterationOutput`)
+- **`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.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)