fix(core): AgentExecutionOptions<undefined> no longer requires structuredOutput (#17131)

Co-authored-by: shenglu <shenglu@sapia.ai>
Co-authored-by: shenglu zhang <shenglu@sapia.ai@shenglus-MacBook-Pro.local>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: 5 people

.changeset/fix-agent-execution-options-undefined.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed `AgentExecutionOptions<undefined>` (and its public/inner variants) incorrectly requiring a `structuredOutput` property. When the output type is `undefined` or `null` — including a fully-nullish union such as `undefined | null` — `structuredOutput` is now correctly optional, regardless of the `strictNullChecks` setting. This is the shape produced by `AgentConfig.defaultOptions`, so `defaultOptions: { maxSteps: 50 }` now type-checks without a spurious `structuredOutput` requirement. Object output types still require `structuredOutput` as before.

packages/core/src/agent/agent-types.test-d.ts

@@ -3,7 +3,7 @@ import { assertType, describe, expectTypeOf, it } from 'vitest';
 import { z } from 'zod/v4';
 import type { RequestContext } from '../request-context';
 import type { PublicSchema } from '../schema';
-import type { AgentExecutionOptions } from './agent.types';
+import type { AgentExecutionOptions, PublicAgentExecutionOptions } from './agent.types';
 import type { AgentConfig } from './types';
 
 /**
@@ -151,4 +151,34 @@ describe('Agent Type Tests', () => {
       expectTypeOf(config.id).toEqualTypeOf<'test-agent'>();
     });
   });
+
+  describe('Issue #16732: AgentExecutionOptions<undefined> should not require structuredOutput', () => {
+    it('should allow AgentExecutionOptions<undefined> without structuredOutput', () => {
+      assertType<AgentExecutionOptions<undefined>>({ maxSteps: 50 });
+    });
+
+    it('should allow PublicAgentExecutionOptions<undefined> without structuredOutput', () => {
+      assertType<PublicAgentExecutionOptions<undefined>>({ maxSteps: 50 });
+    });
+
+    it('should allow AgentExecutionOptions<null> without structuredOutput', () => {
+      assertType<AgentExecutionOptions<null>>({ maxSteps: 50 });
+    });
+
+    it('should still require structuredOutput for an object OUTPUT', () => {
+      const schema = z.object({ value: z.string() });
+      // @ts-expect-error structuredOutput is required when OUTPUT is an object
+      assertType<AgentExecutionOptions<{ value: string }>>({ maxSteps: 50 });
+      assertType<AgentExecutionOptions<{ value: string }>>({
+        maxSteps: 50,
+        structuredOutput: { schema },
+      });
+    });
+
+    it('should not require structuredOutput for a nullable union (T | undefined)', () => {
+      // NonNullable<string | undefined> is `string`, which is not an object type,
+      // so structuredOutput stays optional for the nullable-union case.
+      assertType<AgentExecutionOptions<string | undefined>>({ maxSteps: 50 });
+    });
+  });
 });

packages/core/src/agent/agent.types.ts

@@ -652,14 +652,22 @@ export type AgentExecutionOptionsBase<OUTPUT> = {
  * Use this type for public method signatures.
  */
 export type PublicAgentExecutionOptions<OUTPUT = unknown> = AgentExecutionOptionsBase<OUTPUT> &
-  (OUTPUT extends {} ? { structuredOutput: PublicStructuredOutputOptions<OUTPUT> } : { structuredOutput?: never });
+  ([NonNullable<OUTPUT>] extends [never]
+    ? { structuredOutput?: never }
+    : OUTPUT extends {}
+      ? { structuredOutput: PublicStructuredOutputOptions<OUTPUT> }
+      : { structuredOutput?: never });
 
 /**
  * Internal agent execution options that require StandardSchemaWithJSON.
  * Use this type internally after converting from PublicSchema.
  */
 export type AgentExecutionOptions<OUTPUT = unknown> = AgentExecutionOptionsBase<OUTPUT> &
-  (OUTPUT extends {} ? { structuredOutput: StructuredOutputOptions<OUTPUT> } : { structuredOutput?: never });
+  ([NonNullable<OUTPUT>] extends [never]
+    ? { structuredOutput?: never }
+    : OUTPUT extends {}
+      ? { structuredOutput: StructuredOutputOptions<OUTPUT> }
+      : { structuredOutput?: never });
 
 export type InnerAgentExecutionOptions<OUTPUT = unknown> = AgentExecutionOptionsBase<OUTPUT> & {
   outputWriter?: OutputWriter;
@@ -673,4 +681,8 @@ export type InnerAgentExecutionOptions<OUTPUT = unknown> = AgentExecutionOptions
     snapshot: WorkflowRunState;
   };
   toolCallId?: string;
-} & (OUTPUT extends {} ? { structuredOutput: StructuredOutputOptions<OUTPUT> } : { structuredOutput?: never });
+} & ([NonNullable<OUTPUT>] extends [never]
+    ? { structuredOutput?: never }
+    : OUTPUT extends {}
+      ? { structuredOutput: StructuredOutputOptions<OUTPUT> }
+      : { structuredOutput?: never });