@mastra/mcp-docs-server 1.1.7-alpha.0 → 1.1.8-alpha.0

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

@@ -13,45 +13,115 @@ For setup and basic usage, see the [.stream()](https://mastra.ai/reference/strea
 
 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
+**fullStream** (`ReadableStream<ChunkType<OUTPUT>>`): Complete stream of all chunk types including text, tool calls, reasoning, metadata, and control chunks. Provides granular access to every aspect of the model's response.
 
-**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.
+**fullStream.ChunkType** (`ChunkType<OUTPUT>`): All possible chunk types that can be emitted during streaming
 
-**objectStream:** (`ReadableStream<Partial<OUTPUT>>`): ReadableStreamPartialSchemaOutput:Partial\<OUTPUT>Partially completed object matching the defined schema
+**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.
 
-**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.
+**objectStream** (`ReadableStream<Partial<OUTPUT>>`): Stream of progressive structured object updates when using output schemas. Emits partial objects as they're built up, allowing real-time visualization of structured data generation.
+
+**objectStream.PartialSchemaOutput** (`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.
+**text** (`Promise<string>`): The complete concatenated text response from the model. Resolves when text generation is finished.
+
+**object** (`Promise<OUTPUT>`): The complete structured object response when using output schemas. Validated against the schema before resolving. Rejects if validation fails.
+
+**object.InferSchemaOutput** (`OUTPUT`): Fully 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[]>`): Array of all tool call chunks made during execution. Each chunk contains tool metadata and execution details.
+
+**toolCalls.type** (`'tool-call'`): Chunk type identifier
+
+**toolCalls.runId** (`string`): Execution run identifier
+
+**toolCalls.from** (`ChunkFrom`): Source of the chunk (AGENT, WORKFLOW, etc.)
+
+**toolCalls.payload** (`ToolCallPayload`): Tool call data including toolCallId, toolName, args, and execution details
+
+**toolResults** (`Promise<ToolResultChunk[]>`): Array of all tool result chunks corresponding to the tool calls. Contains execution results and error information.
+
+**toolResults.type** (`'tool-result'`): Chunk type identifier
+
+**toolResults.runId** (`string`): Execution run identifier
+
+**toolResults.from** (`ChunkFrom`): Source of the chunk (AGENT, WORKFLOW, etc.)
+
+**toolResults.payload** (`ToolResultPayload`): Tool result data including toolCallId, toolName, result, and error status
+
+**usage** (`Promise<LanguageModelUsage>`): Token usage statistics including input tokens, output tokens, total tokens, and reasoning tokens (for reasoning models).
+
+**usage.inputTokens** (`number`): Tokens consumed by the input prompt
 
-**object:** (`Promise<OUTPUT>`): PromiseInferSchemaOutput:OUTPUTFully typed object matching the exact schema definition
+**usage.outputTokens** (`number`): Tokens generated in the response
 
-**reasoning:** (`Promise<string>`): Complete reasoning text for models that support reasoning (like OpenAI's o1 series). Returns empty string for models without reasoning capability.
+**usage.totalTokens** (`number`): Sum of input and output tokens
 
-**reasoningText:** (`Promise<string | undefined>`): Alternative access to reasoning content. May be undefined for models that don't support reasoning, while 'reasoning' returns empty string.
+**usage.reasoningTokens** (`number`): Hidden reasoning tokens (for reasoning models)
 
-**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
+**usage.cachedInputTokens** (`number`): Number of input tokens that were a cache hit
 
-**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
+**finishReason** (`Promise<string | undefined>`): Reason why generation stopped (e.g., 'stop', 'length', 'tool\_calls', 'content\_filter'). Undefined if the stream hasn't finished.
 
-**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.stop** (`'stop'`): Model finished naturally
 
-**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
+**finishReason.length** (`'length'`): Hit maximum token limit
 
-**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
+**finishReason.tool\_calls** (`'tool_calls'`): Model called tools
+
+**finishReason.content\_filter** (`'content_filter'`): Content was filtered
+
+**response** (`Promise<Response>`): Response metadata and messages from the model provider.
+
+**response.id** (`string`): Response ID from the model provider
+
+**response.timestamp** (`Date`): Response timestamp
+
+**response.modelId** (`string`): Model identifier used for this response
+
+**response.headers** (`Record<string, string>`): Response headers from the model provider
+
+**response.messages** (`ResponseMessage[]`): Response messages in model format
+
+**response.uiMessages** (`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.
+**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
+**getFullOutput** (`() => Promise<FullOutput>`): Returns a comprehensive output object containing all results: text, structured object, tool calls, usage statistics, reasoning, and metadata. Convenient single method to access all stream results.
+
+**getFullOutput.text** (`string`): Complete text response
+
+**getFullOutput.object** (`OUTPUT`): Structured output if schema was provided
+
+**getFullOutput.toolCalls** (`ToolCallChunk[]`): All tool call chunks made
+
+**getFullOutput.toolResults** (`ToolResultChunk[]`): All tool result chunks
+
+**getFullOutput.usage** (`Record<string, number>`): Token usage statistics
+
+**getFullOutput.reasoning** (`string`): Reasoning text if available
+
+**getFullOutput.finishReason** (`string`): Why generation finished
+
+**getFullOutput.response** (`Response`): Response metadata and messages from the model provider
+
+**consumeStream** (`(options?: ConsumeStreamOptions) => Promise<void>`): Manually consume the entire stream without processing chunks. Useful when you only need the final promise-based results and want to trigger stream consumption.
 
-**consumeStream:** (`(options?: ConsumeStreamOptions) => Promise<void>`): ConsumeStreamOptionsonError?:(error: Error) => voidCallback for handling stream errors
+**consumeStream.onError** (`(error: Error) => void`): Callback for handling stream errors
 
 ## Usage Examples
 

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

@@ -12,93 +12,205 @@ const stream = await agent.stream('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.
+**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** (`AgentExecutionOptions<Output, Format>`): Optional configuration for the streaming process.
 
-### Options
+**options.maxSteps** (`number`): Maximum number of steps to run during execution.
 
-**maxSteps?:** (`number`): Maximum number of steps to run during execution.
+**options.scorers** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): Evaluation scorers to run on the execution results.
 
-**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'.
+**options.scorers.scorer** (`string`): Name of the scorer to use.
 
-**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.
+**options.scorers.sampling** (`ScoringSamplingConfig`): Sampling configuration for the scorer.
 
-**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.
+**options.scorers.sampling.type** (`'none' | 'ratio'`): Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling.
 
-**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.
+**options.scorers.sampling.rate** (`number`): Sampling rate (0-1). Required when type is 'ratio'.
 
-**tracingContext?:** (`TracingContext`): Tracing context for span hierarchy and metadata.
+**options.onIterationComplete** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): Callback function called after each iteration completes. Use this to monitor progress, provide feedback to guide the agent, or stop execution early. The callback receives context about the iteration including the current text, tool calls, and finish reason.
 
-**returnScorerData?:** (`boolean`): Whether to return detailed scoring data in the response.
+**options.onIterationComplete.context.iteration** (`number`): Current iteration number (1-based).
 
-**onChunk?:** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk during streaming.
+**options.onIterationComplete.context.maxIterations** (`number | undefined`): Maximum iterations allowed (if set).
 
-**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
+**options.onIterationComplete.context.text** (`string`): The text response from this iteration.
 
-**onAbort?:** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+**options.onIterationComplete.context.isFinal** (`boolean`): Whether this is the final iteration.
 
-**abortSignal?:** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+**options.onIterationComplete.context.finishReason** (`string`): Reason why this iteration finished (e.g., 'stop', 'length', 'tool-calls').
 
-**activeTools?:** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
+**options.onIterationComplete.context.toolCalls** (`ToolCall[]`): Tool calls made in this iteration.
 
-**prepareStep?:** (`PrepareStepFunction<any>`): Callback function called before each step of multi-step execution.
+**options.onIterationComplete.context.messages** (`MastraDBMessage[]`): All messages accumulated so far.
 
-**context?:** (`ModelMessage[]`): Additional context messages to provide to the agent.
+**options.onIterationComplete.return.continue** (`boolean`): Set to false to stop execution early.
 
-**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' } }\`).
+**options.onIterationComplete.return.feedback** (`string`): Feedback message to guide the agent's next iteration.
 
-**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.
+**options.isTaskComplete** (`IsTaskCompleteConfig`): Task completion scoring configuration that validates whether the task is complete. Uses Mastra's evaluation scorers to automatically check if the agent's response satisfies the completion criteria.
 
-**includeRawChunks?:** (`boolean`): Whether to include raw chunks in the stream output (not available on all model providers).
+**options.isTaskComplete.scorers** (`MastraScorer[]`): Array of scorers that evaluate task completion. Each scorer returns 0 (failed) or 1 (passed).
 
-**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.
+**options.isTaskComplete.strategy** (`'all' | 'any'`): Strategy for combining scorer results. 'all' requires all scorers to pass, 'any' requires at least one.
 
-**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.
+**options.isTaskComplete.onComplete** (`(result: IsTaskCompleteRunResult) => void | Promise<void>`): Callback called when the task completion check finishes. Receives the result with individual scorer scores.
 
-**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.
+**options.isTaskComplete.parallel** (`boolean`): Whether to run scorers in parallel.
 
-**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.
+**options.isTaskComplete.timeout** (`number`): Maximum time in milliseconds to wait for all scorers to complete.
 
-**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.
+**options.delegation** (`DelegationConfig`): Configuration for subagent delegation. Use this to control and monitor when the agent delegates tasks to other agents, including the ability to modify, reject delegations, and provide feedback to guide the supervisor.
 
-**onFinish?:** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
+**options.delegation.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.
 
-**onStepFinish?:** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
+**options.delegation.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.
 
-**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.
+**options.delegation.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.
 
-**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.
+**options.tracingContext** (`TracingContext`): Tracing context for span hierarchy and metadata.
 
-**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'`)
+**options.returnScorerData** (`boolean`): Whether to return detailed scoring data in the response.
 
-**toolsets?:** (`ToolsetsInput`): Additional toolsets to make available to the agent during streaming.
+**options.onChunk** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk 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.
+**options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
 
-**savePerStep?:** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
 
-**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.
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
 
-**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.
+**options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
 
-**toolCallConcurrency?:** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
+**options.prepareStep** (`PrepareStepFunction<any>`): Callback function called before each step of multi-step execution.
 
-**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.
+**options.context** (`ModelMessage[]`): Additional context messages to provide to the agent.
 
-**runId?:** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options to fine tune your structured output generation.
 
-**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
+**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema defining the expected output structure.
 
-**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.
+**options.structuredOutput.model** (`MastraLanguageModel`): Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output
 
-**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.
+**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values.
+
+**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Fallback value to use when schema validation fails and errorStrategy is 'fallback'.
+
+**options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
+
+**options.structuredOutput.jsonPromptInjection** (`boolean`): Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.
+
+**options.structuredOutput.providerOptions** (`ProviderOptions`): Provider-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' } }\`).
+
+**options.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.
+
+**options.includeRawChunks** (`boolean`): Whether to include raw chunks in the stream output (not available on all model providers).
+
+**options.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.
+
+**options.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.
+
+**options.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.
+
+**options.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.
+
+**options.memory** (`object`): Configuration for memory. This is the preferred way to manage memory.
+
+**options.memory.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\`.
+
+**options.memory.resource** (`string`): Identifier for the user or resource associated with the thread.
+
+**options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, and workingMemory.
+
+**options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
+
+**options.onStepFinish** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
+
+**options.telemetry** (`TelemetrySettings`): Settings for OTLP telemetry collection during streaming (not Tracing).
+
+**options.telemetry.isEnabled** (`boolean`): Enable or disable telemetry. Disabled by default while experimental.
+
+**options.telemetry.recordInputs** (`boolean`): Enable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.
+
+**options.telemetry.recordOutputs** (`boolean`): Enable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.
+
+**options.telemetry.functionId** (`string`): Identifier for this function. Used to group telemetry data by function.
+
+**options.modelSettings** (`CallSettings`): Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.
+
+**options.modelSettings.temperature** (`number`): Controls randomness in generation (0-2). Higher values make output more random.
+
+**options.modelSettings.maxOutputTokens** (`number`): Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.
+
+**options.modelSettings.maxRetries** (`number`): Maximum number of retry attempts for failed requests.
+
+**options.modelSettings.topP** (`number`): Nucleus sampling parameter (0-1). Controls diversity of generated text.
+
+**options.modelSettings.topK** (`number`): Top-k sampling parameter. Limits vocabulary to k most likely tokens.
+
+**options.modelSettings.presencePenalty** (`number`): Penalty for token presence (-2 to 2). Reduces repetition.
+
+**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
+
+**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
+
+**options.toolChoice.'auto'** (`string`): Let the model decide whether to use tools (default).
+
+**options.toolChoice.'none'** (`string`): Do not use any tools.
+
+**options.toolChoice.'required'** (`string`): Require the model to use at least one tool.
+
+**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Require the model to use a specific tool by name.
+
+**options.toolsets** (`ToolsetsInput`): Additional toolsets to make available to the agent during streaming.
+
+**options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
+
+**options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+
+**options.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.
+
+**options.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.
+
+**options.toolCallConcurrency** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
+
+**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 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 } }\`.
+
+**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI-specific options. Example: \`{ reasoningEffort: 'high' }\`
+
+**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic-specific options. Example: \`{ maxTokens: 1000 }\`
+
+**options.providerOptions.google** (`Record<string, JSONValue>`): Google-specific options. Example: \`{ safetySettings: \[...] }\`
+
+**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): Other provider-specific options. The key is the provider name and the value is a record of provider-specific options.
+
+**options.runId** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+
+**options.requestContext** (`RequestContext`): Request Context for dependency injection and contextual information.
+
+**options.tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.
+
+**options.tracingContext.currentSpan** (`Span`): Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**options.tracingOptions** (`TracingOptions`): Options for Tracing configuration.
+
+**options.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.
+
+**options.tracingOptions.requestContextKeys** (`string[]`): Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').
+
+**options.tracingOptions.traceId** (`string`): Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.
+
+**options.tracingOptions.parentSpanId** (`string`): Parent 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.
+
+**options.tracingOptions.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.
+**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.
+**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