@mastra/mcp-docs-server 0.13.26 → 0.13.27

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

@@ -1,18 +1,31 @@
 ---
 title: "Reference: Agent.generate() | Agents | Mastra Docs"
-description: "Documentation for the `Agent.generate()` method in Mastra agents, which produces text or structured responses."
+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 is used to interact with an agent to produce text or structured responses. This method accepts messages and optional generation options.
+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.
 
 ## Usage example
 
 ```typescript copy
-await agent.generate("message for agent");
+// Default Mastra format
+const mastraResult = await agent.generate("message for agent");
+
+// AI SDK v5 compatible format
+const aiSdkResult = await agent.generate("message for agent", {
+  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>
+
+
 ## Parameters
 
 <PropertiesTable
@@ -20,31 +33,129 @@ 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 with multimodal content (text, images, etc.).",
+      description: "The messages to send to the agent. Can be a single string, array of strings, or structured message objects.",
     },
     {
       name: "options",
-      type: "AgentGenerateOptions",
+      type: "AgentExecutionOptions<Output, StructuredOutput, Format>",
       isOptional: true,
       description: "Optional configuration for the generation process.",
     },
   ]}
 />
 
-### Options parameters
+
+
+### Options
 
 <PropertiesTable
   content={[
+    {
+      name: "format",
+      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.",
+    },
+    {
+      name: "maxSteps",
+      type: "number",
+      isOptional: true,
+      description: "Maximum number of steps to run during execution.",
+    },
+    {
+      name: "scorers",
+      type: "MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>",
+      isOptional: true,
+      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'."
+                }]
+              }
+            ]
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      isOptional: true,
+      description: "AI tracing context for span hierarchy and metadata.",
+    },
+    {
+      name: "returnScorerData",
+      type: "boolean",
+      isOptional: true,
+      description: "Whether to return detailed scoring data in the response.",
+    },
+    {
+      name: "onChunk",
+      type: "(chunk: ChunkType) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called for each chunk during generation.",
+    },
+    {
+      name: "onError",
+      type: "({ error }: { error: Error | string }) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called when an error occurs during generation.",
+    },
+    {
+      name: "onAbort",
+      type: "(event: any) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called when the generation is aborted.",
+    },
+    {
+      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.",
+    },
     {
       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.",
     },
     {
       name: "context",
-      type: "CoreMessage[]",
+      type: "ModelMessage[]",
       isOptional: true,
       description: "Additional context messages to provide to the agent.",
     },
@@ -59,15 +170,15 @@ await agent.generate("message for agent");
             name: "schema",
             type: "z.ZodSchema<S>",
             isOptional: false,
-            description: "Zod schema to validate the output against."
+            description: "Zod schema defining the expected output structure."
           }]
         },
         {
           parameters: [{
             name: "model",
             type: "MastraLanguageModel",
-            isOptional: false,
-            description: "Model to use for the internal structuring agent."
+            isOptional: true,
+            description: "Language model to use for structured output generation. If not provided, uses the agent's default model."
           }]
         },
         {
@@ -75,7 +186,7 @@ await agent.generate("message for agent");
             name: "errorStrategy",
             type: "'strict' | 'warn' | 'fallback'",
             isOptional: true,
-            description: "Strategy when parsing or validation fails. Defaults to 'strict'."
+            description: "Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values."
           }]
         },
         {
@@ -83,7 +194,7 @@ await agent.generate("message for agent");
             name: "fallbackValue",
             type: "<S extends ZodTypeAny>",
             isOptional: true,
-            description: "Fallback value when errorStrategy is 'fallback'."
+            description: "Fallback value to use when schema validation fails and errorStrategy is 'fallback'."
           }]
         },
         {
@@ -91,102 +202,90 @@ await agent.generate("message for agent");
             name: "instructions",
             type: "string",
             isOptional: true,
-            description: "Custom instructions for the structuring agent."
+            description: "Additional instructions for structured output generation."
           }]
-        },
+        }
       ]
     },
     {
       name: "outputProcessors",
       type: "Processor[]",
       isOptional: true,
-      description: "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.",
+      description: "Output processors to use for this execution (overrides agent's default).",
     },
     {
       name: "inputProcessors",
       type: "Processor[]",
       isOptional: true,
-      description: "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.",
+      description: "Input processors to use for this execution (overrides agent's default).",
     },
     {
-      name: "experimental_output",
-      type: "Zod schema | JsonSchema7",
+      name: "instructions",
+      type: "string",
       isOptional: true,
-      description:
-        "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.",
+      description: "Custom instructions that override the agent's default instructions for this execution.",
     },
     {
-      name: "instructions",
-      type: "string",
+      name: "system",
+      type: "string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]",
       isOptional: true,
-      description:
-        "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.",
+      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:
-        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+      description: "**Deprecated.** Use structuredOutput with maxSteps:1 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: "Configuration for memory. This is the preferred way to manage memory.",
+      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: "The conversation thread, as a string ID or an object with an `id` and optional `metadata`."
+            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: "Identifier for the user or resource associated with the thread."
+            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: "Configuration for memory behavior, like message history and semantic recall. See `MemoryConfig` below."
+            name: "options",
+            type: "MemoryConfig",
+            isOptional: true,
+            description: "Additional memory configuration options for conversation management."
           }]
         }
       ]
     },
     {
-      name: "maxSteps",
-      type: "number",
-      isOptional: true,
-      defaultValue: "5",
-      description: "Maximum number of execution steps allowed.",
-    },
-    {
-      name: "maxRetries",
-      type: "number",
+      name: "onFinish",
+      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
       isOptional: true,
-      defaultValue: "2",
-      description: "Maximum number of retries. Set to 0 to disable retries.",
+      description: "Callback fired when generation completes. Type varies by format.",
     },
     {
       name: "onStepFinish",
-      type: "GenerateTextOnStepFinishCallback<any> | never",
+      type: "StreamTextOnStepFinishCallback<any> | never",
       isOptional: true,
-      description:
-        "Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output",
+      description: "Callback fired after each generation step. Type varies by format.",
     },
     {
-      name: "runId",
+      name: "resourceId",
       type: "string",
       isOptional: true,
-      description: "Unique ID for this generation run. Useful for tracking and debugging purposes.",
+      description: "Deprecated. Use memory.resource instead. Identifier for the resource/user.",
     },
     {
       name: "telemetry",
@@ -200,7 +299,7 @@ await agent.generate("message for agent");
             name: "isEnabled",
             type: "boolean",
             isOptional: true,
-            description: "Enable or disable telemetry. Disabled by default while experimental."
+            description: "Whether telemetry collection is enabled."
           }]
         },
         {
@@ -208,7 +307,7 @@ await agent.generate("message for agent");
             name: "recordInputs",
             type: "boolean",
             isOptional: true,
-            description: "Enable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information."
+            description: "Whether to record input data in telemetry."
           }]
         },
         {
@@ -216,7 +315,7 @@ await agent.generate("message for agent");
             name: "recordOutputs",
             type: "boolean",
             isOptional: true,
-            description: "Enable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information."
+            description: "Whether to record output data in telemetry."
           }]
         },
         {
@@ -224,51 +323,117 @@ await agent.generate("message for agent");
             name: "functionId",
             type: "string",
             isOptional: true,
-            description: "Identifier for this function. Used to group telemetry data by function."
+            description: "Identifier for the function being executed."
           }]
         }
       ]
     },
     {
-      name: "temperature",
-      type: "number",
+      name: "modelSettings",
+      type: "CallSettings",
       isOptional: true,
-      description:
-        "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.",
+      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: "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: "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: "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."
+          }]
+        }
+      ]
+    },
+    {
+      name: "threadId",
+      type: "string",
+      isOptional: true,
+      description: "Deprecated. Use memory.thread instead. Thread identifier for conversation continuity.",
     },
     {
       name: "toolChoice",
       type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
       isOptional: true,
-      defaultValue: "'auto'",
-      description: "Controls how the agent uses tools during generation.",
+      description: "Controls how tools are selected during generation.",
       properties: [
         {
           parameters: [{
             name: "'auto'",
             type: "string",
-            description: "Let the model decide whether to use tools (default)."
+            isOptional: false,
+            description: "Let the model decide when to use tools (default)."
           }]
         },
         {
           parameters: [{
             name: "'none'",
             type: "string",
-            description: "Do not use any tools."
+            isOptional: false,
+            description: "Disable tool usage entirely."
           }]
         },
         {
           parameters: [{
             name: "'required'",
             type: "string",
-            description: "Require the model to use at least one tool."
+            isOptional: false,
+            description: "Force the model to use at least one tool."
           }]
         },
         {
           parameters: [{
             name: "{ type: 'tool'; toolName: string }",
             type: "object",
-            description: "Require the model to use a specific tool by name."
+            isOptional: false,
+            description: "Force the model to use a specific tool."
           }]
         }
       ]
@@ -277,34 +442,32 @@ await agent.generate("message for agent");
       name: "toolsets",
       type: "ToolsetsInput",
       isOptional: true,
-      description:
-        "Additional toolsets to make available to the agent during generation.",
+      description: "Additional tool sets that can be used for this execution.",
     },
     {
       name: "clientTools",
       type: "ToolsInput",
       isOptional: true,
-      description:
-        "Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.",
+      description: "Client-side tools available during execution.",
     },
     {
       name: "savePerStep",
       type: "boolean",
       isOptional: true,
-      description: "Save messages incrementally after each stream step completes (default: false).",
+      description: "Save messages incrementally after each generation step completes (default: false).",
     },
     {
       name: "providerOptions",
       type: "Record<string, Record<string, JSONValue>>",
       isOptional: true,
-      description: "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.",
+      description: "Provider-specific options passed to the language model.",
       properties: [
         {
           parameters: [{
             name: "openai",
             type: "Record<string, JSONValue>",
             isOptional: true,
-            description: "OpenAI-specific options. Example: `{ reasoningEffort: 'high' }`"
+            description: "OpenAI-specific options like reasoningEffort, responseFormat, etc."
           }]
         },
         {
@@ -312,7 +475,7 @@ await agent.generate("message for agent");
             name: "anthropic",
             type: "Record<string, JSONValue>",
             isOptional: true,
-            description: "Anthropic-specific options. Example: `{ maxTokens: 1000 }`"
+            description: "Anthropic-specific options like maxTokens, etc."
           }]
         },
         {
@@ -320,7 +483,7 @@ await agent.generate("message for agent");
             name: "google",
             type: "Record<string, JSONValue>",
             isOptional: true,
-            description: "Google-specific options. Example: `{ safetySettings: [...] }`"
+            description: "Google-specific options."
           }]
         },
         {
@@ -328,16 +491,22 @@ await agent.generate("message for agent");
             name: "[providerName]",
             type: "Record<string, JSONValue>",
             isOptional: true,
-            description: "Other provider-specific options. The key is the provider name and the value is a record of provider-specific options."
+            description: "Any provider-specific options."
           }]
         }
       ]
     },
+    {
+      name: "runId",
+      type: "string",
+      isOptional: true,
+      description: "Unique identifier for this execution run.",
+    },
     {
       name: "runtimeContext",
       type: "RuntimeContext",
       isOptional: true,
-      description: "Runtime context for dependency injection and contextual information.",
+      description: "Runtime context containing dynamic configuration and state.",
     },
     {
       name: "tracingContext",
@@ -375,50 +544,8 @@ await agent.generate("message for agent");
       name: "maxTokens",
       type: "number",
       isOptional: true,
-      description: "Maximum number of tokens to generate.",
-    },
-    {
-      name: "topP",
-      type: "number",
-      isOptional: true,
-      description: "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either `temperature` or `topP`, but not both.",
-    },
-    {
-      name: "topK",
-      type: "number",
-      isOptional: true,
-      description: "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
-    },
-    {
-      name: "presencePenalty",
-      type: "number",
-      isOptional: true,
-      description: "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).",
-    },
-    {
-      name: "frequencyPenalty",
-      type: "number",
-      isOptional: true,
-      description: "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).",
-    },
-    {
-      name: "stopSequences",
-      type: "string[]",
-      isOptional: true,
-      description: "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
-    },
-    {
-      name: "seed",
-      type: "number",
-      isOptional: true,
-      description: "The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.",
+      description: "Conditions for stopping execution (e.g., step count, token limit).",
     },
-    {
-      name: "headers",
-      type: "Record<string, string | undefined>",
-      isOptional: true,
-      description: "Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.",
-    }
   ]}
 />
 
@@ -427,40 +554,9 @@ await agent.generate("message for agent");
 <PropertiesTable
   content={[
     {
-      name: "text",
-      type: "string",
-      isOptional: true,
-      description: "The generated text response. Present when output is 'text' (no schema provided).",
-    },
-    {
-      name: "object",
-      type: "object",
-      isOptional: true,
-      description: "The generated structured response. Present when a schema is provided via `output`, `structuredOutput`, or `experimental_output`.",
-    },
-    {
-      name: "toolCalls",
-      type: "Array<ToolCall>",
-      isOptional: true,
-      description: "The tool calls made during the generation process. Present in both text and object modes.",
-      properties: [
-        {
-          parameters: [{
-            name: "toolName",
-            type: "string",
-            required: true,
-            description: "The name of the tool invoked."
-          }]
-        },
-        {
-          parameters: [{
-            name: "args",
-            type: "any",
-            required: true,
-            description: "The arguments passed to the tool."
-          }]
-        }
-      ]
+      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.",
     },
     {
       name: "traceId",
@@ -471,62 +567,3 @@ await agent.generate("message for agent");
   ]}
 />
 
-## Extended usage example
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-import { ModerationProcessor, TokenLimiterProcessor } from "@mastra/core/processors";
-
-await agent.generate(
-  [
-    { role: "user", content: "message for agent" },
-    {
-      role: "user",
-      content: [
-        {
-          type: "text",
-          text: "message for agent"
-        },
-        {
-          type: "image",
-          imageUrl: "https://example.com/image.jpg",
-          mimeType: "image/jpeg"
-        }
-      ]
-    }
-  ],
-  {
-    temperature: 0.7,
-    maxSteps: 3,
-    memory: {
-      thread: "user-123",
-      resource: "test-app"
-    },
-    toolChoice: "auto",
-    providerOptions: {
-      openai: {
-        reasoningEffort: "high"
-      }
-    },
-    // Structured output with better DX
-    structuredOutput: {
-      schema: z.object({
-        sentiment: z.enum(['positive', 'negative', 'neutral']),
-        confidence: z.number(),
-      }),
-      model: openai("gpt-4o-mini"),
-      errorStrategy: 'warn',
-    },
-    // Output processors for response validation
-    outputProcessors: [
-      new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
-      new TokenLimiterProcessor({ maxTokens: 1000 }),
-    ],
-  }
-);
-```
-
-## Related
-
-- [Generating responses](../../docs/agents/overview.mdx#generating-responses)
-- [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)