Migration Guide: VNext to Standard APIs

Overview

As of v0.20.00, the streamVNext() and generateVNext() methods in Mastra agents have been renamed to stream() and generate() respectively.

These are now the standard APIs with full AI SDK v5 compatibility. The original stream() and generate() methods have been renamed to streamLegacy() and generateLegacy() to maintain backward compatibility with AI SDK v4.

Migration Paths

Choose the migration path that fits your needs:

If you're using AI SDK v4 models and want to keep using them:

Rename all your stream() and generate() calls to streamLegacy() and generateLegacy() respectively. No other change is needed.

If you're using AI SDK v5 models:

Rename all your streamVNext() and generateVNext() calls to stream() and generate() respectively. No other change is needed.

If you want to upgrade from AI SDK v4 to v5:

Bump all your model provider packages by a major version. This will ensure that they are all v5 models now.
Follow the guide below to understand the key differences and update your code accordingly.

Key Differences

1. Model version support

Legacy APIs (generateLegacy, streamLegacy): Only support AI SDK v4 models (specificationVersion: 'v1')
Current APIs (generate, stream): Only support AI SDK v5 models (specificationVersion: 'v2')
This is enforced at runtime with clear error messages

2. Return types

Legacy methods return AI SDK v4 types

generateLegacy():
- GenerateTextResult or GenerateObjectResult
streamLegacy():
- StreamTextResult or StreamObjectResult

New stream methods return Mastra/AI SDK v5 types

generate():
- When format: 'mastra' (default): Returns MastraModelOutput.getFullOutput() result
- When format: 'aisdk': Returns AISDKV5OutputStream.getFullOutput() result (AI SDK v5 compatible)
- Internally calls stream() and awaits getFullOutput()

stream():
- When format: 'mastra' (default): Returns MastraModelOutput<OUTPUT>
- When format: 'aisdk': Returns AISDKV5OutputStream<OUTPUT> (AI SDK v5 compatible)

Format Control

Legacy: No format control, always returns AI SDK v4 types
New stream: Can choose format via format option ('mastra' or 'aisdk')

 1// Mastra native format (default)
 2const result = await agent.stream(messages, {
 3  format: 'mastra'
 4});
 5
 6// AI SDK v5 compatibility
 7const result = await agent.stream(messages, {
 8  format: 'aisdk'
 9});

3. New Options in Non-Legacy APIs

The following options are available in stream() and generate() but NOT in their legacy counterparts:

format - Choose between 'mastra' or 'aisdk' output format

 1const result = await agent.stream(messages, {
 2  format: 'aisdk' // or 'mastra' (default)
 3});

system - Custom system message (separate from instructions)

 1const result = await agent.stream(messages, {
 2  system: 'You are a helpful assistant'
 3});

structuredOutput - Enhanced structured output with model override and custom options

If no model is added it will use the agent's default model.
Error strategy when the object does not conform to the schema is warn (log a warning), error (throw an error), or fallback (return a default fallback value of your choice).

 1const result = await agent.generate(messages, {
 2  structuredOutput: {
 3    schema: z.object({
 4      name: z.string(),
 5      age: z.number()
 6    }),
 7    model: openai('gpt-4o-mini'), // Optional model override for structuring
 8    errorStrategy: 'fallback',
 9    fallbackValue: { name: 'unknown', age: 0 },
10    instructions: 'Extract user information' // Override default structuring instructions
11  }
12});

stopWhen - Flexible stop conditions (step count, token limit, etc.)

 1const result = await agent.stream(messages, {
 2  stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000
 3});

providerOptions - Provider-specific options (e.g., OpenAI-specific settings)

 1const result = await agent.stream(messages, {
 2  providerOptions: {
 3    openai: {
 4      store: true,
 5      metadata: { userId: '123' }
 6    }
 7  }
 8});

onChunk - Callback for each streaming chunk

 1const result = await agent.stream(messages, {
 2  onChunk: (chunk) => {
 3    console.log('Received chunk:', chunk);
 4  }
 5});

onError - Error callback

 1const result = await agent.stream(messages, {
 2  onError: (error) => {
 3    console.error('Stream error:', error);
 4  }
 5});

onAbort - Abort callback

 1const result = await agent.stream(messages, {
 2  onAbort: () => {
 3    console.log('Stream aborted');
 4  }
 5});

activeTools - Specify which tools are active for this execution

 1const result = await agent.stream(messages, {
 2  activeTools: ['search', 'calculator'] // Only these tools will be available
 3});

abortSignal - AbortSignal for cancellation

 1const controller = new AbortController();
 2const result = await agent.stream(messages, {
 3  abortSignal: controller.signal
 4});
 5
 6// Later: controller.abort();

prepareStep - Callback before each step in multi-step execution

 1const result = await agent.stream(messages, {
 2  prepareStep: ({ step, state }) => {
 3    console.log('About to execute step:', step);
 4    return { /* modified state */ };
 5  }
 6});

requireToolApproval - Require approval for all tool calls

 1const result = await agent.stream(messages, {
 2  requireToolApproval: true
 3});

4. Options That Still Exist But Have Been Moved

`temperature` and Other Model Settings

Unified in modelSettings

 1const result = await agent.stream(messages, {
 2  modelSettings: {
 3    temperature: 0.7,
 4    maxTokens: 1000,
 5    topP: 0.9
 6  }
 7});

`resourceId` and `threadId`

Moved to memory object.

 1const result = await agent.stream(messages, {
 2  memory: {
 3    resource: 'user-123',
 4    thread: 'thread-456'
 5  }
 6});

5. Options That Are Deprecated or Removed

`experimental_output`

Use structuredOutput instead to allow for tool calls and an object return.

 1const result = await agent.generate(messages, {
 2  structuredOutput: {
 3    schema: z.object({
 4      summary: z.string()
 5    })
 6  }
 7});

`output`

The output property is deprecated in favor of structuredOutput, to achieve the same results use maxSteps 1 with structuredOutput.

 1const result = await agent.generate(messages, {
 2  structuredOutput: {
 3    schema: {
 4      z.object({
 5        name: z.string()
 6      })
 7    }
 8  },
 9  maxSteps: 1
10});

`memoryOptions` was removed

Use memory instead

 1const result = await agent.generate(messages, {
 2  memory: {
 3    ...
 4  }
 5});

6. Type Changes

`context`

Legacy: CoreMessage[]
New format: ModelMessage[]

`toolChoice` uses the AI SDK v5 `ToolChoice` type

 1type ToolChoice<TOOLS extends Record<string, unknown>> = 'auto' | 'none' | 'required' | {
 2    type: 'tool';
 3    toolName: Extract<keyof TOOLS, string>;
 4};