AI SDK v5 (beta) Migration Guide

This guide covers Mastra-specific considerations when migrating from AI SDK v4 to v5 beta.

Please add any feedback or bug reports to the AI SDK v5 mega issue in Github.

Official Migration Guide

Follow the official AI SDK v5 Migration Guide for all AI SDK core breaking changes, package updates, and API changes.

This guide covers only the Mastra-specific aspects of the migration.

Warnings

Data compatibility: New data stored in v5 format will no longer work if you downgrade from the beta
Backup recommendation: Keep DB backups from before you upgrade to v5 beta
Production use: Wait for the AI SDK v5 stable release before using in production applications
Prerelease status: The Mastra ai-v5 tag is a prerelease version and may have bugs

Memory Storage

Your existing AI SDK v4 data will run through our internal MessageList class which handles converting to/from various message formats. This includes converting from AI SDK v4->v5. This means you don’t need to run any DB migrations and your data will be translated on the fly and will just work when you upgrade.

Migration Strategy

Migrating to AI SDK v5 with Mastra involves updating both your backend (Mastra server) and frontend. We provide a compatibility mode to handle stream format conversion during the transition.

Backend Upgrade

Bump Mastra to the new ai-v5 prerelease version for all Mastra packages:


npm i mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5 [etc]


pnpm add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5 [etc]


yarn add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5 [etc]


bun add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5 [etc]

Then configure your Mastra instance with v4 compatibility so your existing frontend will continue to work:


import { Mastra } from '@mastra/core';
 
export const mastra = new Mastra({
  agents: { myAgent },
  aiSdkCompat: 'v4', // <- add this for compatibility
});

Dependencies

You will need to upgrade all AI SDK dependencies to use the new v5 beta versions in your backend when you bump to the Mastra ai-v5 prerelease tag.

In most cases this will only involve bumping your model provider packages. For example: npm i @ai-sdk/openai@2.0.0-beta.1 - refer to the AI SDK v5 documentation for more info. Some model providers do not yet have V5 versions (Openrouter for example).

Also note that you need to bump all your Mastra dependencies to the new ai-v5 tag, and you must upgrade zod to the latest version if you have it installed.

Using Stream Compatibility Manually

If you have a frontend that calls Mastra agents in an endpoint, you can wrap the new response.toUIMessageStreamResponse() manually.


import { mastra } from "@/src/mastra";
import { createV4CompatibleResponse } from "@mastra/core/agent";
 
const myAgent = mastra.getAgent("weatherAgent");
export async function POST(req: Request) {
  const { messages } = await req.json();
  const stream = await myAgent.stream(messages);
 
  return createV4CompatibleResponse(stream.toUIMessageStreamResponse().body!);
}

Using Mastra Playground

Currently playground is still an AI SDK v4 frontend. For now you need to set aiSdkCompat: 'v4' for it to work. We’ll handle this automatically for you soon.