@mastra/core 1.9.0 → 1.10.0

package/dist/docs/references/reference-agents-generate.md

@@ -45,139 +45,273 @@ console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remai
 
 ## 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 generation process.
+**options** (`AgentExecutionOptions<Output, Format>`): Optional configuration for the generation process.
 
-### Options
+**options.maxSteps** (`number`): Maximum number of steps to run during execution.
 
-**maxSteps?:** (`number`): Maximum number of steps to run during execution.
+**options.stopWhen** (`LoopOptions['stopWhen']`): Conditions for stopping execution (e.g., step count, token limit).
 
-**stopWhen?:** (`LoopOptions['stopWhen']`): Conditions for stopping execution (e.g., step count, token limit).
+**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.
 
-**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.onIterationComplete.context.iteration** (`number`): Current iteration number (1-based).
 
-**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.onIterationComplete.context.maxIterations** (`number | undefined`): Maximum iterations allowed (if set).
 
-**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.onIterationComplete.context.text** (`string`): The text response from this iteration.
 
-**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.onIterationComplete.context.isFinal** (`boolean`): Whether this is the final iteration.
 
-**returnScorerData?:** (`boolean`): Whether to return detailed scoring data in the response.
+**options.onIterationComplete.context.finishReason** (`string`): Reason why this iteration finished (e.g., 'stop', 'length', 'tool-calls').
 
-**onChunk?:** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk during generation.
+**options.onIterationComplete.context.toolCalls** (`ToolCall[]`): Tool calls made in this iteration.
 
-**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during generation.
+**options.onIterationComplete.context.messages** (`MastraDBMessage[]`): All messages accumulated so far.
 
-**onAbort?:** (`(event: any) => Promise<void> | void`): Callback function called when the generation is aborted.
+**options.onIterationComplete.return.continue** (`boolean`): Set to false to stop execution early.
 
-**activeTools?:** (`Array<keyof ToolSet> | undefined`): Array of tool names that should be active during execution. If undefined, all available tools are active.
+**options.onIterationComplete.return.feedback** (`string`): Feedback message to guide the agent's next 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.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.
 
-**prepareStep?:** (`PrepareStepFunction`): Callback function called before each step of multi-step execution.
+**options.isTaskComplete.scorers** (`MastraScorer[]`): Array of scorers that evaluate task completion. Each scorer returns 0 (failed) or 1 (passed).
 
-**requireToolApproval?:** (`boolean`): When true, all tool calls require explicit approval before execution. The generate() method will return with \`finishReason: 'suspended'\` and include a \`suspendPayload\` with tool call details (\`toolCallId\`, \`toolName\`, \`args\`). Use \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to proceed. See \[Agent Approval]\(/docs/agents/agent-approval#tool-approval-with-generate) for details.
+**options.isTaskComplete.strategy** (`'all' | 'any'`): Strategy for combining scorer results. 'all' requires all scorers to pass, 'any' requires at least one.
 
-**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.isTaskComplete.onComplete** (`(result: IsTaskCompleteRunResult) => void | Promise<void>`): Callback called when the task completion check finishes. Receives the result with individual scorer scores.
 
-**toolCallConcurrency?:** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
+**options.isTaskComplete.parallel** (`boolean`): Whether to run scorers in parallel.
 
-**context?:** (`ModelMessage[]`): Additional context messages to provide to the agent.
+**options.isTaskComplete.timeout** (`number`): Maximum time in milliseconds to wait for all scorers to complete.
 
-**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.logger?:IMastraLoggerOptional logger instance for structured logging during output generation.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.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.
 
-**outputProcessors?:** (`OutputProcessorOrWorkflow[]`): Output processors to use for this execution (overrides agent's default).
+**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.
 
-**maxProcessorRetries?:** (`number`): Maximum number of times processors can trigger a retry for this generation. Overrides agent's default maxProcessorRetries.
+**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.
 
-**inputProcessors?:** (`InputProcessorOrWorkflow[]`): Input processors to use for this execution (overrides agent's default).
+**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.
 
-**instructions?:** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Custom instructions that override the agent's default instructions for this execution. Can be a single string, message object, or array of either.
+**options.scorers** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): Evaluation scorers to run on the execution results.
 
-**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.scorers.scorer** (`string`): Name of the scorer to use.
 
-**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.scorers.sampling** (`ScoringSamplingConfig`): Sampling configuration for the scorer.
 
-**memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title.resource:stringResource identifier for organizing conversations by user, session, or context.options?:MemoryConfigAdditional memory configuration options including lastMessages, readOnly, semanticRecall, and workingMemory.
+**options.scorers.sampling.type** (`'none' | 'ratio'`): Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling.
 
-**onFinish?:** (`LoopConfig['onFinish']`): Callback fired when generation completes.
+**options.scorers.sampling.rate** (`number`): Sampling rate (0-1). Required when type is 'ratio'.
 
-**onStepFinish?:** (`LoopConfig['onStepFinish']`): Callback fired after each generation step.
+**options.returnScorerData** (`boolean`): Whether to return detailed scoring data in the response.
 
-**telemetry?:** (`TelemetrySettings`): isEnabled?:booleanWhether telemetry collection is enabled.recordInputs?:booleanWhether to record input data in telemetry.recordOutputs?:booleanWhether to record output data in telemetry.functionId?:stringIdentifier for the function being executed.
+**options.onChunk** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk during generation.
 
-**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.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during generation.
 
-**toolChoice?:** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 'auto':stringLet the model decide when to use tools (default).'none':stringDisable tool usage entirely.'required':stringForce the model to use at least one tool.{ type: 'tool'; toolName: string }:objectForce the model to use a specific tool.
+**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the generation is aborted.
 
-**toolsets?:** (`ToolsetsInput`): Additional tool sets that can be used for this execution.
+**options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of tool names that should be active during execution. If undefined, all available tools are active.
 
-**clientTools?:** (`ToolsInput`): Client-side tools available during execution.
+**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.
 
-**savePerStep?:** (`boolean`): Save messages incrementally after each generation step completes (default: false).
+**options.prepareStep** (`PrepareStepFunction`): Callback function called before each step of multi-step execution.
 
-**providerOptions?:** (`Record<string, Record<string, JSONValue>>`): openai?:Record\<string, JSONValue>OpenAI-specific options like reasoningEffort, responseFormat, etc.anthropic?:Record\<string, JSONValue>Anthropic-specific options like maxTokens, etc.google?:Record\<string, JSONValue>Google-specific options.\[providerName]?:Record\<string, JSONValue>Any provider-specific options.
+**options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The generate() method will return with \`finishReason: 'suspended'\` and include a \`suspendPayload\` with tool call details (\`toolCallId\`, \`toolName\`, \`args\`). Use \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to proceed. See \[Agent Approval]\(/docs/agents/agent-approval#tool-approval-with-generate) for details.
 
-**runId?:** (`string`): Unique identifier for this execution run.
+**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.
 
-**requestContext?:** (`RequestContext`): Request Context containing dynamic configuration and state.
+**options.toolCallConcurrency** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
 
-**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.context** (`ModelMessage[]`): Additional context messages to provide to the agent.
 
-**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** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options to fine tune your structured output generation.
 
-**includeRawChunks?:** (`boolean`): Whether to include raw chunks in the stream output. Not available on all model providers.
+**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema defining the expected output structure.
+
+**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
+
+**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.logger** (`IMastraLogger`): Optional logger instance for structured logging during output generation.
+
+**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** (`OutputProcessorOrWorkflow[]`): Output processors to use for this execution (overrides agent's default).
+
+**options.maxProcessorRetries** (`number`): Maximum number of times processors can trigger a retry for this generation. Overrides agent's default maxProcessorRetries.
+
+**options.inputProcessors** (`InputProcessorOrWorkflow[]`): Input processors to use for this execution (overrides agent's default).
+
+**options.instructions** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Custom instructions that override the agent's default instructions for this execution. Can be a single string, message object, or array of either.
+
+**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`): Memory configuration for conversation persistence and retrieval.
+
+**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title.
+
+**options.memory.resource** (`string`): Resource identifier for organizing conversations by user, session, or context.
+
+**options.memory.options** (`MemoryConfig`): Additional memory configuration options including lastMessages, readOnly, semanticRecall, and workingMemory.
+
+**options.onFinish** (`LoopConfig['onFinish']`): Callback fired when generation completes.
+
+**options.onStepFinish** (`LoopConfig['onStepFinish']`): Callback fired after each generation step.
+
+**options.telemetry** (`TelemetrySettings`): Settings for OTLP telemetry collection during generation (not Tracing).
+
+**options.telemetry.isEnabled** (`boolean`): Whether telemetry collection is enabled.
+
+**options.telemetry.recordInputs** (`boolean`): Whether to record input data in telemetry.
+
+**options.telemetry.recordOutputs** (`boolean`): Whether to record output data in telemetry.
+
+**options.telemetry.functionId** (`string`): Identifier for the function being executed.
+
+**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 tools are selected during generation.
+
+**options.toolChoice.'auto'** (`string`): Let the model decide when to use tools (default).
+
+**options.toolChoice.'none'** (`string`): Disable tool usage entirely.
+
+**options.toolChoice.'required'** (`string`): Force the model to use at least one tool.
+
+**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Force the model to use a specific tool.
+
+**options.toolsets** (`ToolsetsInput`): Additional tool sets that can be used for this execution.
+
+**options.clientTools** (`ToolsInput`): Client-side tools available during execution.
+
+**options.savePerStep** (`boolean`): Save messages incrementally after each generation step completes (default: false).
+
+**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Provider-specific options passed to the language model.
+
+**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI-specific options like reasoningEffort, responseFormat, etc.
+
+**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic-specific options like maxTokens, etc.
+
+**options.providerOptions.google** (`Record<string, JSONValue>`): Google-specific options.
+
+**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): Any provider-specific options.
+
+**options.runId** (`string`): Unique identifier for this execution run.
+
+**options.requestContext** (`RequestContext`): Request Context containing dynamic configuration and state.
+
+**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.
+
+**options.includeRawChunks** (`boolean`): Whether to include raw chunks in the stream output. Not available on all model providers.
 
 ## Returns
 
-**result:** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): Returns the full output of the generation process including text, object (if structured output), tool calls, tool results, usage statistics, and step information.
+**result** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): Returns the full output of the generation process including text, object (if structured output), tool calls, tool results, usage statistics, and step information.
+
+**text** (`string`): The generated text response from the agent.
+
+**object** (`Output | undefined`): The structured output object if structuredOutput was provided, validated against the schema.
+
+**toolCalls** (`ToolCall[]`): Array of tool calls made during generation.
+
+**toolResults** (`ToolResult[]`): Array of results from tool executions.
+
+**usage** (`TokenUsage`): Token usage statistics for the generation.
+
+**steps** (`Step[]`): Array of execution steps, useful for debugging multi-step generations.
+
+**finishReason** (`string`): The reason generation finished. Values include 'stop' (normal completion), 'tool-calls' (ended with tool calls), 'suspended' (waiting for tool approval), or 'error' (error occurred).
+
+**response** (`object`): Response metadata from the model provider. Useful for accessing rate limit headers and request IDs.
+
+**response.id** (`string`): Response ID from the model provider.
+
+**response.timestamp** (`Date`): Timestamp when the response was generated.
 
-**text:** (`string`): The generated text response from the agent.
+**response.modelId** (`string`): Model identifier used for this response.
 
-**object?:** (`Output | undefined`): The structured output object if structuredOutput was provided, validated against the schema.
+**response.headers** (`Record<string, string>`): HTTP response headers from the model provider. Contains rate limit information (e.g., \`anthropic-ratelimit-requests-remaining\`, \`x-ratelimit-remaining-tokens\`) and other provider-specific metadata.
 
-**toolCalls:** (`ToolCall[]`): Array of tool calls made during generation.
+**response.messages** (`ResponseMessage[]`): Response messages in model format.
 
-**toolResults:** (`ToolResult[]`): Array of results from tool executions.
+**response.uiMessages** (`UIMessage[]`): Response messages in UI format, includes any metadata added by output processors.
 
-**usage:** (`TokenUsage`): Token usage statistics for the generation.
+**request** (`object`): The request that was sent to the model.
 
-**steps:** (`Step[]`): Array of execution steps, useful for debugging multi-step generations.
+**request.body** (`unknown`): The request body sent to the model provider.
 
-**finishReason:** (`string`): The reason generation finished. Values include 'stop' (normal completion), 'tool-calls' (ended with tool calls), 'suspended' (waiting for tool approval), or 'error' (error occurred).
+**warnings** (`LanguageModelWarning[]`): Any warnings from the model provider during generation.
 
-**response:** (`object`): id?:stringResponse ID from the model provider.timestamp?:DateTimestamp when the response was generated.modelId?:stringModel identifier used for this response.headers?:Record\<string, string>HTTP response headers from the model provider. Contains rate limit information (e.g., \`anthropic-ratelimit-requests-remaining\`, \`x-ratelimit-remaining-tokens\`) and other provider-specific metadata.messages?:ResponseMessage\[]Response messages in model format.uiMessages?:UIMessage\[]Response messages in UI format, includes any metadata added by output processors.
+**providerMetadata** (`Record<string, unknown>`): Provider-specific metadata returned with the response.
 
-**request?:** (`object`): body?:unknownThe request body sent to the model provider.
+**reasoning** (`ReasoningChunk[]`): Reasoning details from models that support reasoning (e.g., OpenAI o1 series).
 
-**warnings?:** (`LanguageModelWarning[]`): Any warnings from the model provider during generation.
+**reasoningText** (`string`): Combined reasoning text from reasoning models.
 
-**providerMetadata?:** (`Record<string, unknown>`): Provider-specific metadata returned with the response.
+**sources** (`SourceChunk[]`): Sources referenced by the model during generation.
 
-**reasoning?:** (`ReasoningChunk[]`): Reasoning details from models that support reasoning (e.g., OpenAI o1 series).
+**files** (`FileChunk[]`): Files generated by the model.
 
-**reasoningText?:** (`string`): Combined reasoning text from reasoning models.
+**suspendPayload** (`object`): Present when \`finishReason\` is 'suspended'. Contains tool call details needed to approve or decline the pending tool call.
 
-**sources?:** (`SourceChunk[]`): Sources referenced by the model during generation.
+**suspendPayload.toolCallId** (`string`): Unique identifier for the pending tool call.
 
-**files?:** (`FileChunk[]`): Files generated by the model.
+**suspendPayload.toolName** (`string`): Name of the tool that requires approval.
 
-**suspendPayload?:** (`object`): toolCallId:stringUnique identifier for the pending tool call.toolName:stringName of the tool that requires approval.args:Record\<string, any>Arguments that will be passed to the tool.
+**suspendPayload.args** (`Record<string, any>`): Arguments that will be passed to the tool.
 
-**runId?:** (`string`): Unique identifier for this execution run. Required when calling \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to resume a suspended execution.
+**runId** (`string`): Unique identifier for this execution run. Required when calling \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to resume a suspended execution.
 
-**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.
 
-**messages:** (`MastraDBMessage[]`): All messages from this execution including input, memory history, and response.
+**messages** (`MastraDBMessage[]`): All messages from this execution including input, memory history, and response.
 
-**rememberedMessages:** (`MastraDBMessage[]`): Only messages loaded from memory (conversation history).
+**rememberedMessages** (`MastraDBMessage[]`): Only messages loaded from memory (conversation history).
 
-**error?:** (`Error`): Error object if the generation failed.
+**error** (`Error`): Error object if the generation failed.
 
-**tripwire?:** (`StepTripwireData`): Tripwire data if content was blocked by a processor.
+**tripwire** (`StepTripwireData`): Tripwire data if content was blocked by a processor.
 
-**scoringData?:** (`object`): Scoring data for evals when \`returnScorerData\` is enabled.
+**scoringData** (`object`): Scoring data for evals when \`returnScorerData\` is enabled.
 
 ## Related
 

package/dist/docs/references/reference-agents-generateLegacy.md

@@ -12,77 +12,119 @@ await agent.generateLegacy('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 with multimodal content (text, images, etc.).
+**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 with multimodal content (text, images, etc.).
 
-**options?:** (`AgentGenerateOptions`): Optional configuration for the generation process.
+**options** (`AgentGenerateOptions`): Optional configuration for the generation process.
 
-### Options parameters
+**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.
 
-**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.context** (`CoreMessage[]`): Additional context messages to provide to the agent.
 
-**context?:** (`CoreMessage[]`): Additional context messages to provide to the agent.
+**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.
 
-**structuredOutput?:** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): schema:z.ZodSchema\<S>Zod schema to validate the output against.model:MastraLanguageModelModel to use for the internal structuring agent.errorStrategy?:'strict' | 'warn' | 'fallback'Strategy when parsing or validation fails. Defaults to 'strict'.fallbackValue?:\<S extends ZodTypeAny>Fallback value when errorStrategy is 'fallback'.instructions?:stringCustom instructions for the structuring agent.
+**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema to validate the output against.
 
-**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.structuredOutput.model** (`MastraLanguageModel`): Model to use for the internal structuring agent.
 
-**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.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): Strategy when parsing or validation fails. Defaults to 'strict'.
 
-**experimental\_output?:** (`Zod schema | JsonSchema7`): Note, the preferred route is to use the \`structuredOutput\` property. Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.
+**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Fallback value when errorStrategy is 'fallback'.
 
-**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.structuredOutput.instructions** (`string`): Custom instructions for the structuring agent.
 
-**output?:** (`Zod schema | JsonSchema7`): Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
+**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.
 
-**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. See \`MemoryConfig\` below.
+**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.
 
-**maxSteps?:** (`number`): Maximum number of execution steps allowed. (Default: `5`)
+**options.experimental\_output** (`Zod schema | JsonSchema7`): Note, the preferred route is to use the \`structuredOutput\` property. Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.
 
-**maxRetries?:** (`number`): Maximum number of retries. Set to 0 to disable retries. (Default: `2`)
+**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.
 
-**onStepFinish?:** (`GenerateTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
+**options.output** (`Zod schema | JsonSchema7`): Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
 
-**runId?:** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+**options.memory** (`object`): Configuration for memory. This is the preferred way to manage memory.
 
-**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.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\`.
 
-**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.
+**options.memory.resource** (`string`): Identifier for the user or resource associated with the thread.
 
-**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.memory.options** (`MemoryConfig`): Configuration for memory behavior, like message history and semantic recall. See \`MemoryConfig\` below.
 
-**toolsets?:** (`ToolsetsInput`): Additional toolsets to make available to the agent during generation.
+**options.maxSteps** (`number`): Maximum number of execution steps allowed.
 
-**clientTools?:** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
+**options.maxRetries** (`number`): Maximum number of retries. Set to 0 to disable retries.
 
-**savePerStep?:** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+**options.onStepFinish** (`GenerateTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
 
-**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.runId** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
 
-**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
+**options.telemetry** (`TelemetrySettings`): Settings for telemetry collection during generation.
 
-**maxTokens?:** (`number`): Maximum number of tokens to generate.
+**options.telemetry.isEnabled** (`boolean`): Enable or disable telemetry. Disabled by default while experimental.
 
-**topP?:** (`number`): Nucleus sampling. This is a number between 0 and 1. It is recommended to set either \`temperature\` or \`topP\`, but not both.
+**options.telemetry.recordInputs** (`boolean`): Enable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.
 
-**topK?:** (`number`): Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.
+**options.telemetry.recordOutputs** (`boolean`): Enable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.
 
-**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).
+**options.telemetry.functionId** (`string`): Identifier for this function. Used to group telemetry data by function.
 
-**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).
+**options.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.
 
-**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 generation.
 
-**seed?:** (`number`): The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
+**options.toolChoice.'auto'** (`string`): Let the model decide whether to use tools (default).
 
-**headers?:** (`Record<string, string | undefined>`): Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+**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 generation.
+
+**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.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 } }\`. Since Mastra extends AI SDK, see the \[AI SDK documentation]\(https\://sdk.vercel.ai/docs/providers/ai-sdk-providers) for complete provider options.
+
+**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.requestContext** (`RequestContext`): Request Context for dependency injection and contextual information.
+
+**options.maxTokens** (`number`): Maximum number of tokens to generate.
+
+**options.topP** (`number`): Nucleus sampling. This is a number between 0 and 1. It is recommended to set either \`temperature\` or \`topP\`, but not both.
+
+**options.topK** (`number`): Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.
+
+**options.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).
+
+**options.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).
+
+**options.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**options.seed** (`number`): The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
+
+**options.headers** (`Record<string, string | undefined>`): Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
 
 ## Returns
 
-**text?:** (`string`): The generated text response. Present when output is 'text' (no schema provided).
+**text** (`string`): The generated text response. Present when output is 'text' (no schema provided).
+
+**object** (`object`): The generated structured response. Present when a schema is provided via \`output\`, \`structuredOutput\`, or \`experimental\_output\`.
+
+**toolCalls** (`Array<ToolCall>`): The tool calls made during the generation process. Present in both text and object modes.
 
-**object?:** (`object`): The generated structured response. Present when a schema is provided via \`output\`, \`structuredOutput\`, or \`experimental\_output\`.
+**toolCalls.toolName** (`string`): The name of the tool invoked.
 
-**toolCalls?:** (`Array<ToolCall>`): toolName:stringThe name of the tool invoked.args:anyThe arguments passed to the tool.
+**toolCalls.args** (`any`): The arguments passed to the tool.
 
 ## Migration to New API
 

package/dist/docs/references/reference-agents-getDefaultGenerateOptions.md

@@ -12,11 +12,13 @@ await agent.getDefaultGenerateOptionsLegacy()
 
 ## Parameters
 
-**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+**options** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+**options.requestContext** (`RequestContext`): Request Context for dependency injection and contextual information.
 
 ## Returns
 
-**defaultOptions:** (`AgentGenerateOptions | Promise<AgentGenerateOptions>`): The default generation options configured for the agent, either as a direct object or a promise that resolves to the options.
+**defaultOptions** (`AgentGenerateOptions | Promise<AgentGenerateOptions>`): The default generation options configured for the agent, either as a direct object or a promise that resolves to the options.
 
 ## Extended usage example
 
@@ -26,10 +28,6 @@ await agent.getDefaultGenerateOptionsLegacy({
 })
 ```
 
-### Options parameters
-
-**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
-
 ## Related
 
 - [Agent generation](https://mastra.ai/docs/agents/overview)