Experimental output support (#2520)

mastra-ai · Feb 25, 2025 · 6cb63e0 · 6cb63e0
1 parent dbaff23
commit 6cb63e0
Show file tree

Hide file tree

Showing 10 changed files with 349 additions and 145 deletions.
diff --git a/.changeset/short-facts-wink.md b/.changeset/short-facts-wink.md
@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Experimental output support
diff --git a/docs/src/pages/docs/reference/agents/generate.mdx b/docs/src/pages/docs/reference/agents/generate.mdx
@@ -38,59 +38,71 @@ An optional object that can include:
     {
       name: "messages",
       type: "string | Array<string> | Array<Message>",
+      required: true,
       description: "The messages to be processed by the agent. Can be a single string, an array of strings, or an array of message objects with `role` and `content`.",
     },
     {
       name: "options",
       type: "object",
-      isOptional: true,
+      required: false,
       description: "Additional options for the `generate` method.",
       properties: [
         {
-          name: "structuredOutput",
-          type: "object | Zod schema",
-          isOptional: true,
-          description: "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
-        },
-        {
-          name: "onStepFinish",
-          type: "(step: string) => void",
-          isOptional: true,
-          description: "Callback function called after each execution step. Receives step details as a JSON string.",
-        },
-        {
-          name: "maxSteps",
-          type: "number",
-          isOptional: true,
-          default: 5,
-          description: "Maximum number of execution steps allowed.",
-        },
-        {
-          name: "threadId",
-          type: "string",
-          isOptional: true,
-          description: "Identifier for the conversation thread. Allows for maintaining context across multiple interactions.",
-        },
-        {
-          name: "resourceId",
-          type: "string",
-          isOptional: true,
-          description: "Identifier for the user or resource interacting with the agent.",
-        },
-        {
-          name: "temperature",
-          type: "number",
-          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.",
-        },
-        {
-          name: "context",
-          type: "Array<Message>",
-          isOptional: true,
-          description: "Additional context messages to provide to the agent.",
-        },
-      ],
-    },
+          type: "object",
+          parameters: [
+            {
+              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.",
+            },
+            {
+              name: "experimental_output",
+              type: "Zod schema | JsonSchema7",
+              isOptional: true,
+              description: "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+            },
+            {
+              name: "onStepFinish",
+              type: "(step: string) => void",
+              isOptional: true,
+              description: "Callback function called after each execution step. Receives step details as a JSON string.",
+            },
+            {
+              name: "maxSteps",
+              type: "number",
+              isOptional: true,
+              defaultValue: "5",
+              description: "Maximum number of execution steps allowed.",
+            },
+            {
+              name: "threadId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the conversation thread. Allows for maintaining context across multiple interactions.",
+            },
+            {
+              name: "resourceId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the user or resource interacting with the agent.",
+            },
+            {
+              name: "temperature",
+              type: "number",
+              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.",
+            },
+            {
+              name: "context",
+              type: "Array<Message>",
+              isOptional: true,
+              description: "Additional context messages to provide to the agent.",
+            }
+          ]
+        }
+      ]
+    }
   ]}
 />
 
@@ -105,27 +117,27 @@ The return value of the `generate()` method depends on the options provided, spe
     {
       name: "text",
       type: "string",
-      isOptional: true,
+      required: false,
       description: "The generated text response. Present if `structuredOutput` is not provided.",
     },
     {
       name: "object",
       type: "object",
-      isOptional: true,
+      required: false,
       description: "The generated structured response based on the provided schema. Present if `structuredOutput` is provided.",
     },
     {
       name: "toolCalls",
       type: "Array<ToolCall>",
-      isOptional: true,
+      required: false,
       description: "The tool calls made during the generation process.",
     },
     {
       name: "error",
       type: "string",
-      isOptional: true,
+      required: false,
       description: "Error message if the generation fails.",
-    },
+    }
   ]}
 />
 
@@ -136,13 +148,15 @@ The return value of the `generate()` method depends on the options provided, spe
     {
       name: "toolName",
       type: "string",
+      required: true,
       description: "The name of the tool invoked.",
     },
     {
       name: "args",
       type: "any",
+      required: true,
       description: "The arguments passed to the tool.",
-    },
+    }
   ]}
 />
 

diff --git a/docs/src/pages/docs/reference/agents/stream.mdx b/docs/src/pages/docs/reference/agents/stream.mdx
@@ -33,87 +33,107 @@ An optional object that can include:
 <PropertiesTable
   content={[
     {
-      name: 'output',
-      type: 'string | JSONSchema7 | ZodSchema',
-      isOptional: true,
-      default: "'text'",
-      description: 'Defines the output format. Can be "text" or a schema for structured output.',
-    },
-    {
-      name: 'context',
-      type: 'CoreMessage[]',
-      isOptional: true,
-      description: 'Additional context messages to provide to the agent.',
-    },
-    {
-      name: 'threadId',
-      type: 'string',
-      isOptional: true,
-      description: 'Identifier for the conversation thread. Allows for maintaining context across multiple interactions.',
-    },
-    {
-      name: 'resourceId',
-      type: 'string',
-      isOptional: true,
-      description: 'Identifier for the user or resource interacting with the agent.',
-    },
-    {
-      name: 'onFinish',
-      type: '(result: string) => Promise<void> | void',
-      isOptional: true,
-      description: 'Callback function called when streaming is complete.',
-    },
-    {
-      name: 'onStepFinish',
-      type: '(step: string) => void',
-      isOptional: true,
-      description: 'Callback function called after each step during streaming.',
-    },
-    {
-      name: 'maxSteps',
-      type: 'number',
-      isOptional: true,
-      default: '5',
-      description: 'Maximum number of steps allowed during streaming.',
-    },
-    {
-      name: 'toolsets',
-      type: 'ToolsetsInput',
-      isOptional: true,
-      description: 'Additional toolsets to make available to the agent during this stream.',
-    },
-    {
-      name: 'temperature',
-      type: 'number',
-      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.',
+      name: "options",
+      type: "object",
+      required: false,
+      description: "Additional options for the `stream` method.",
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              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.",
+            },
+            {
+              name: "experimental_output",
+              type: "Zod schema | JsonSchema7",
+              isOptional: true,
+              description: "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+            },
+            {
+              name: "context",
+              type: "CoreMessage[]",
+              isOptional: true,
+              description: "Additional context messages to provide to the agent.",
+            },
+            {
+              name: "threadId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the conversation thread. Allows for maintaining context across multiple interactions.",
+            },
+            {
+              name: "resourceId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the user or resource interacting with the agent.",
+            },
+            {
+              name: "onFinish",
+              type: "(result: string) => Promise<void> | void",
+              isOptional: true,
+              description: "Callback function called when streaming is complete.",
+            },
+            {
+              name: "onStepFinish",
+              type: "(step: string) => void",
+              isOptional: true,
+              description: "Callback function called after each step during streaming.",
+            },
+            {
+              name: "maxSteps",
+              type: "number",
+              isOptional: true,
+              defaultValue: "5",
+              description: "Maximum number of steps allowed during streaming.",
+            },
+            {
+              name: "toolsets",
+              type: "ToolsetsInput",
+              isOptional: true,
+              description: "Additional toolsets to make available to the agent during this stream.",
+            },
+            {
+              name: "temperature",
+              type: "number",
+              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.",
+            }
+          ]
+        }
+      ]
     }
   ]}
 />
 
 ## Returns
 
-The method returns a promise that resolves to an object containing one or more of the following properties:
+The return value of the `stream()` method depends on the options provided, specifically the `output` option.
+
+### PropertiesTable for Return Values
 
 <PropertiesTable
   content={[
     {
-      name: 'textStream',
-      type: 'AsyncIterable<string>',
-      isOptional: true,
-      description: 'An async iterable stream of text chunks. Present when output is "text".',
+      name: "textStream",
+      type: "AsyncIterable<string>",
+      required: false,
+      description: "An async iterable stream of text chunks. Present when output is 'text'.",
     },
     {
-      name: 'objectStream',
-      type: 'AsyncIterable<object>',
-      isOptional: true,
-      description: 'An async iterable stream of structured data. Present when a schema is provided.',
+      name: "objectStream",
+      type: "AsyncIterable<object>",
+      required: false,
+      description: "An async iterable stream of structured data. Present when a schema is provided.",
     },
     {
-      name: 'object',
-      type: 'Promise<object>',
-      isOptional: true,
-      description: 'A promise that resolves to the final structured output when using a schema.',
+      name: "object",
+      type: "Promise<object>",
+      required: false,
+      description: "A promise that resolves to the final structured output when using a schema.",
     }
   ]}
 />