@mastra/mcp-docs-server 0.13.37 → 0.13.38

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

@@ -3,8 +3,6 @@ title: "Reference: Agent.generate() | Agents | Mastra Docs"
 description: "Documentation for the `Agent.generate()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
 ---
 
-import { Callout } from 'nextra/components';
-
 # Agent.generate()
 
 The `.generate()` method enables non-streaming response generation from an agent, with enhanced capabilities and flexible output formats. It accepts messages and optional generation options, supporting both Mastra’s native format and AI SDK v5 compatibility.
@@ -17,14 +15,15 @@ const mastraResult = await agent.generate("message for agent");
 
 // AI SDK v5 compatible format
 const aiSdkResult = await agent.generate("message for agent", {
-  format: 'aisdk'
+  format: "aisdk",
 });
 ```
 
-<Callout type="info">
-  **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.generateLegacy()`](./generateLegacy.mdx) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
-</Callout>
+:::info
+
+**Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.generateLegacy()`](./generateLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
 
+:::
 
 ## Parameters
 
@@ -33,7 +32,8 @@ const aiSdkResult = await agent.generate("message for agent", {
     {
       name: "messages",
       type: "string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]",
-      description: "The messages to send to the agent. Can be a single string, array of strings, or structured message objects.",
+      description:
+        "The messages to send to the agent. Can be a single string, array of strings, or structured message objects.",
     },
     {
       name: "options",
@@ -44,8 +44,6 @@ const aiSdkResult = await agent.generate("message for agent", {
   ]}
 />
 
-
-
 ### Options
 
 <PropertiesTable
@@ -55,7 +53,8 @@ const aiSdkResult = await agent.generate("message for agent", {
       type: "'mastra' | 'aisdk'",
       isOptional: true,
       defaultValue: "'mastra'",
-      description: "Determines the output format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
+      description:
+        "Determines the output format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
     },
     {
       name: "maxSteps",
@@ -70,40 +69,50 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Evaluation scorers to run on the execution results.",
       properties: [
         {
-          parameters: [{
-            name: "scorer",
-            type: "string",
-            isOptional: false,
-            description: "Name of the scorer to use."
-          }]
-        },
-        {
-          parameters: [{
-            name: "sampling",
-            type: "ScoringSamplingConfig",
-            isOptional: true,
-            description: "Sampling configuration for the scorer.",
-            properties: [
-              {
-                parameters: [{
-                  name: "type",
-                  type: "'none' | 'ratio'",
-                  isOptional: false,
-                  description: "Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling."
-                }]
-              },
-              {
-                parameters: [{
-                  name: "rate",
-                  type: "number",
-                  isOptional: true,
-                  description: "Sampling rate (0-1). Required when type is 'ratio'."
-                }]
-              }
-            ]
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "scorer",
+              type: "string",
+              isOptional: false,
+              description: "Name of the scorer to use.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "sampling",
+              type: "ScoringSamplingConfig",
+              isOptional: true,
+              description: "Sampling configuration for the scorer.",
+              properties: [
+                {
+                  parameters: [
+                    {
+                      name: "type",
+                      type: "'none' | 'ratio'",
+                      isOptional: false,
+                      description:
+                        "Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling.",
+                    },
+                  ],
+                },
+                {
+                  parameters: [
+                    {
+                      name: "rate",
+                      type: "number",
+                      isOptional: true,
+                      description:
+                        "Sampling rate (0-1). Required when type is 'ratio'.",
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
     },
     {
       name: "tracingContext",
@@ -127,7 +136,8 @@ const aiSdkResult = await agent.generate("message for agent", {
       name: "onError",
       type: "({ error }: { error: Error | string }) => Promise<void> | void",
       isOptional: true,
-      description: "Callback function called when an error occurs during generation.",
+      description:
+        "Callback function called when an error occurs during generation.",
     },
     {
       name: "onAbort",
@@ -139,19 +149,22 @@ const aiSdkResult = await agent.generate("message for agent", {
       name: "activeTools",
       type: "Array<keyof ToolSet> | undefined",
       isOptional: true,
-      description: "Array of tool names that should be active during execution. If undefined, all available tools are active.",
+      description:
+        "Array of tool names that should be active during execution. If undefined, all available tools are active.",
     },
     {
       name: "abortSignal",
       type: "AbortSignal",
       isOptional: true,
-      description: "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
+      description:
+        "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
     },
     {
       name: "prepareStep",
       type: "PrepareStepFunction<any>",
       isOptional: true,
-      description: "Callback function called before each step of multi-step execution.",
+      description:
+        "Callback function called before each step of multi-step execution.",
     },
     {
       name: "context",
@@ -166,134 +179,169 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Options to fine tune your structured output generation.",
       properties: [
         {
-          parameters: [{
-            name: "schema",
-            type: "z.ZodSchema<S>",
-            isOptional: false,
-            description: "Zod schema defining the expected output structure."
-          }]
+          parameters: [
+            {
+              name: "schema",
+              type: "z.ZodSchema<S>",
+              isOptional: false,
+              description: "Zod schema defining the expected output structure.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "model",
-            type: "MastraLanguageModel",
-            isOptional: true,
-            description: "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"
-          }]
+          parameters: [
+            {
+              name: "model",
+              type: "MastraLanguageModel",
+              isOptional: true,
+              description:
+                "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",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "errorStrategy",
-            type: "'strict' | 'warn' | 'fallback'",
-            isOptional: true,
-            description: "Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values."
-          }]
+          parameters: [
+            {
+              name: "errorStrategy",
+              type: "'strict' | 'warn' | 'fallback'",
+              isOptional: true,
+              description:
+                "Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "fallbackValue",
-            type: "<S extends ZodTypeAny>",
-            isOptional: true,
-            description: "Fallback value to use when schema validation fails and errorStrategy is 'fallback'."
-          }]
+          parameters: [
+            {
+              name: "fallbackValue",
+              type: "<S extends ZodTypeAny>",
+              isOptional: true,
+              description:
+                "Fallback value to use when schema validation fails and errorStrategy is 'fallback'.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "instructions",
-            type: "string",
-            isOptional: true,
-            description: "Additional instructions for the structured output model."
-          }]
+          parameters: [
+            {
+              name: "instructions",
+              type: "string",
+              isOptional: true,
+              description:
+                "Additional instructions for the structured output model.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "jsonPromptInjection",
-            type: "boolean",
-            isOptional: true,
-            description: "Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "jsonPromptInjection",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "outputProcessors",
       type: "Processor[]",
       isOptional: true,
-      description: "Output processors to use for this execution (overrides agent's default).",
+      description:
+        "Output processors to use for this execution (overrides agent's default).",
     },
     {
       name: "inputProcessors",
       type: "Processor[]",
       isOptional: true,
-      description: "Input processors to use for this execution (overrides agent's default).",
+      description:
+        "Input processors to use for this execution (overrides agent's default).",
     },
     {
       name: "instructions",
       type: "string",
       isOptional: true,
-      description: "Custom instructions that override the agent's default instructions for this execution.",
+      description:
+        "Custom instructions that override the agent's default instructions for this execution.",
     },
     {
       name: "system",
       type: "string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]",
       isOptional: true,
-      description: "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.",
+      description:
+        "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.",
     },
     {
       name: "output",
       type: "Zod schema | JsonSchema7",
       isOptional: true,
-      description: "**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.",
+      description:
+        "**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.",
     },
     {
       name: "memory",
       type: "object",
       isOptional: true,
-      description: "Memory configuration for conversation persistence and retrieval.",
+      description:
+        "Memory configuration for conversation persistence and retrieval.",
       properties: [
         {
-          parameters: [{
-            name: "thread",
-            type: "string | { id: string; metadata?: Record<string, any>, title?: string }",
-            isOptional: false,
-            description: "Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title."
-          }]
+          parameters: [
+            {
+              name: "thread",
+              type: "string | { id: string; metadata?: Record<string, any>, title?: string }",
+              isOptional: false,
+              description:
+                "Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "resource",
-            type: "string",
-            isOptional: false,
-            description: "Resource identifier for organizing conversations by user, session, or context."
-          }]
+          parameters: [
+            {
+              name: "resource",
+              type: "string",
+              isOptional: false,
+              description:
+                "Resource identifier for organizing conversations by user, session, or context.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "options",
-            type: "MemoryConfig",
-            isOptional: true,
-            description: "Additional memory configuration options for conversation management."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "options",
+              type: "MemoryConfig",
+              isOptional: true,
+              description:
+                "Additional memory configuration options for conversation management.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "onFinish",
       type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
       isOptional: true,
-      description: "Callback fired when generation completes. Type varies by format.",
+      description:
+        "Callback fired when generation completes. Type varies by format.",
     },
     {
       name: "onStepFinish",
       type: "StreamTextOnStepFinishCallback<any> | never",
       isOptional: true,
-      description: "Callback fired after each generation step. Type varies by format.",
+      description:
+        "Callback fired after each generation step. Type varies by format.",
     },
     {
       name: "resourceId",
       type: "string",
       isOptional: true,
-      description: "Deprecated. Use memory.resource instead. Identifier for the resource/user.",
+      description:
+        "Deprecated. Use memory.resource instead. Identifier for the resource/user.",
     },
     {
       name: "telemetry",
@@ -303,38 +351,46 @@ const aiSdkResult = await agent.generate("message for agent", {
         "Settings for OTLP telemetry collection during generation (not AI tracing).",
       properties: [
         {
-          parameters: [{
-            name: "isEnabled",
-            type: "boolean",
-            isOptional: true,
-            description: "Whether telemetry collection is enabled."
-          }]
+          parameters: [
+            {
+              name: "isEnabled",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether telemetry collection is enabled.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "recordInputs",
-            type: "boolean",
-            isOptional: true,
-            description: "Whether to record input data in telemetry."
-          }]
+          parameters: [
+            {
+              name: "recordInputs",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether to record input data in telemetry.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "recordOutputs",
-            type: "boolean",
-            isOptional: true,
-            description: "Whether to record output data in telemetry."
-          }]
+          parameters: [
+            {
+              name: "recordOutputs",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether to record output data in telemetry.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "functionId",
-            type: "string",
-            isOptional: true,
-            description: "Identifier for the function being executed."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "functionId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the function being executed.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "modelSettings",
@@ -343,68 +399,90 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Model-specific settings like temperature, topP, etc.",
       properties: [
         {
-          parameters: [{
-            name: "temperature",
-            type: "number",
-            isOptional: true,
-            description: "Controls randomness in generation (0-2). Higher values make output more random."
-          }]
+          parameters: [
+            {
+              name: "temperature",
+              type: "number",
+              isOptional: true,
+              description:
+                "Controls randomness in generation (0-2). Higher values make output more random.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "maxRetries",
-            type: "number",
-            isOptional: true,
-            description: "Maximum number of retry attempts for failed requests."
-          }]
+          parameters: [
+            {
+              name: "maxRetries",
+              type: "number",
+              isOptional: true,
+              description:
+                "Maximum number of retry attempts for failed requests.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "topP",
-            type: "number",
-            isOptional: true,
-            description: "Nucleus sampling parameter (0-1). Controls diversity of generated text."
-          }]
+          parameters: [
+            {
+              name: "topP",
+              type: "number",
+              isOptional: true,
+              description:
+                "Nucleus sampling parameter (0-1). Controls diversity of generated text.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "topK",
-            type: "number",
-            isOptional: true,
-            description: "Top-k sampling parameter. Limits vocabulary to k most likely tokens."
-          }]
+          parameters: [
+            {
+              name: "topK",
+              type: "number",
+              isOptional: true,
+              description:
+                "Top-k sampling parameter. Limits vocabulary to k most likely tokens.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "presencePenalty",
-            type: "number",
-            isOptional: true,
-            description: "Penalty for token presence (-2 to 2). Reduces repetition."
-          }]
+          parameters: [
+            {
+              name: "presencePenalty",
+              type: "number",
+              isOptional: true,
+              description:
+                "Penalty for token presence (-2 to 2). Reduces repetition.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "frequencyPenalty",
-            type: "number",
-            isOptional: true,
-            description: "Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens."
-          }]
+          parameters: [
+            {
+              name: "frequencyPenalty",
+              type: "number",
+              isOptional: true,
+              description:
+                "Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "stopSequences",
-            type: "string[]",
-            isOptional: true,
-            description: "Array of strings that will stop generation when encountered."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "stopSequences",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Array of strings that will stop generation when encountered.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "threadId",
       type: "string",
       isOptional: true,
-      description: "Deprecated. Use memory.thread instead. Thread identifier for conversation continuity.",
+      description:
+        "Deprecated. Use memory.thread instead. Thread identifier for conversation continuity.",
     },
     {
       name: "toolChoice",
@@ -413,38 +491,46 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Controls how tools are selected during generation.",
       properties: [
         {
-          parameters: [{
-            name: "'auto'",
-            type: "string",
-            isOptional: false,
-            description: "Let the model decide when to use tools (default)."
-          }]
+          parameters: [
+            {
+              name: "'auto'",
+              type: "string",
+              isOptional: false,
+              description: "Let the model decide when to use tools (default).",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "'none'",
-            type: "string",
-            isOptional: false,
-            description: "Disable tool usage entirely."
-          }]
+          parameters: [
+            {
+              name: "'none'",
+              type: "string",
+              isOptional: false,
+              description: "Disable tool usage entirely.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "'required'",
-            type: "string",
-            isOptional: false,
-            description: "Force the model to use at least one tool."
-          }]
+          parameters: [
+            {
+              name: "'required'",
+              type: "string",
+              isOptional: false,
+              description: "Force the model to use at least one tool.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "{ type: 'tool'; toolName: string }",
-            type: "object",
-            isOptional: false,
-            description: "Force the model to use a specific tool."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "{ type: 'tool'; toolName: string }",
+              type: "object",
+              isOptional: false,
+              description: "Force the model to use a specific tool.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "toolsets",
@@ -462,7 +548,8 @@ const aiSdkResult = await agent.generate("message for agent", {
       name: "savePerStep",
       type: "boolean",
       isOptional: true,
-      description: "Save messages incrementally after each generation step completes (default: false).",
+      description:
+        "Save messages incrementally after each generation step completes (default: false).",
     },
     {
       name: "providerOptions",
@@ -471,38 +558,47 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Provider-specific options passed to the language model.",
       properties: [
         {
-          parameters: [{
-            name: "openai",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "OpenAI-specific options like reasoningEffort, responseFormat, etc."
-          }]
+          parameters: [
+            {
+              name: "openai",
+              type: "Record<string, JSONValue>",
+              isOptional: true,
+              description:
+                "OpenAI-specific options like reasoningEffort, responseFormat, etc.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "anthropic",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "Anthropic-specific options like maxTokens, etc."
-          }]
+          parameters: [
+            {
+              name: "anthropic",
+              type: "Record<string, JSONValue>",
+              isOptional: true,
+              description: "Anthropic-specific options like maxTokens, etc.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "google",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "Google-specific options."
-          }]
+          parameters: [
+            {
+              name: "google",
+              type: "Record<string, JSONValue>",
+              isOptional: true,
+              description: "Google-specific options.",
+            },
+          ],
         },
         {
-          parameters: [{
-            name: "[providerName]",
-            type: "Record<string, JSONValue>",
-            isOptional: true,
-            description: "Any provider-specific options."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "[providerName]",
+              type: "Record<string, JSONValue>",
+              isOptional: true,
+              description: "Any provider-specific options.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "runId",
@@ -514,23 +610,28 @@ const aiSdkResult = await agent.generate("message for agent", {
       name: "runtimeContext",
       type: "RuntimeContext",
       isOptional: true,
-      description: "Runtime context containing dynamic configuration and state.",
+      description:
+        "Runtime context containing dynamic configuration and state.",
     },
     {
       name: "tracingContext",
       type: "TracingContext",
       isOptional: true,
-      description: "AI tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+      description:
+        "AI tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
       properties: [
         {
-          parameters: [{
-            name: "currentSpan",
-            type: "AISpan",
-            isOptional: true,
-            description: "Current AI span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "currentSpan",
+              type: "AISpan",
+              isOptional: true,
+              description:
+                "Current AI span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "tracingOptions",
@@ -539,20 +640,24 @@ const aiSdkResult = await agent.generate("message for agent", {
       description: "Options for AI tracing configuration.",
       properties: [
         {
-          parameters: [{
-            name: "metadata",
-            type: "Record<string, any>",
-            isOptional: true,
-            description: "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags."
-          }]
-        }
-      ]
+          parameters: [
+            {
+              name: "metadata",
+              type: "Record<string, any>",
+              isOptional: true,
+              description:
+                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+            },
+          ],
+        },
+      ],
     },
     {
       name: "maxTokens",
       type: "number",
       isOptional: true,
-      description: "Conditions for stopping execution (e.g., step count, token limit).",
+      description:
+        "Conditions for stopping execution (e.g., step count, token limit).",
     },
   ]}
 />
@@ -564,14 +669,15 @@ const aiSdkResult = await agent.generate("message for agent", {
     {
       name: "result",
       type: "Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>> | Awaited<ReturnType<AISDKV5OutputStream<Output>['getFullOutput']>>",
-      description: "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
+      description:
+        "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
     },
     {
       name: "traceId",
       type: "string",
       isOptional: true,
-      description: "The trace ID associated with this execution when AI tracing is enabled. Use this to correlate logs and debug execution flow.",
+      description:
+        "The trace ID associated with this execution when AI tracing is enabled. Use this to correlate logs and debug execution flow.",
     },
   ]}
 />
-