8月末、mastra から generateVNext, streamVNext のサポートが発表されました。これは mastra が基盤として使う Vercel AI SDK の v5 に対応するためのものであり、名前の通り今後は VNext で採用される形式のAPIがスタンダードに（ほぼ）なります。
普段から mastra を触っていると VNext に対しては「またか・・・」と思わざるを得ません。なぜなら、この機能はまだ実験的であると表記されているものの、「まだ実験的な機能だから、後でいいや」と思っていてはいけません。
VNext はほぼ移行が必要な機能アップデートと認識しておく方が望ましく、事実としても 9月に入って久しぶりに mastra を触っていると、以下のようなメッセージが出るようになっていました。あまりに移行の期間が短いような気がしないでもないのですが、mastra を触る以上よくあることのようにも思え、受け入れる他ありません。新しい機能に置き換わるのは今日です
Generate method will switch to use generateVNext implementation September 23rd, 2025. Please use generateLegacy if you don't want to upgrade just yet.
とはいえ、「VNext で何が変わるのかを理解しておきたい」というニーズもあるでしょう。本記事では、そのような方々に向けて、この対応で一体何が変わるのかをご紹介しようと思います。
Vercel AI SDK v5 とは
Vercel が提供している AI SDK の新しいバージョンです。7月末に発表され、現在は最新版として扱われています。
主な変更内容としては以下が挙げられます。そのほか、zod v4 対応やツールの改善などもありますが、上記を認識しておけば概ね問題ないと思います。
- チャットの再設計（UIとの統合がよりスムーズに）
- Agentic Loop Control（エージェントの挙動制御が簡単に）
- 音声生成と書き起こし
- AI SDK の仕様自体が V2 へ変更
今回のアップデートでは、 Vercel AI SDK が TypeScript で AI を書く時のデファクトスタンダードに近づいている一方で、AI 領域の加速度的な発展もあり使いづらくなっていたポイントが解消されています。特に、仕様が変わるというのは大きな変化であり、意気込みを感じる変更内容となっています。なお、Vercel AI SDK v4 と v5 の差分についてはマイグレーションガイドも用意されており、詳細な差分を知る上では有益です。
v5 以降は UI と AI の関心が分離される
今回の変更でおそらく一番大きな変更は AI SDK UI との統合が更新されたことではないでしょうか。以下のページでも詳細に解説されていますが、 AI SDK では AI が返却する Message を UI と Model で明確に役割を分けて今後は取り扱うようです。
具体的に例で示されている通り、ModelMessages が Data Transfer Object (DTO) として機能します。今後は、付与されているメソッドを呼び出すことでデータ形式を変換して、UI用のメッセージオブジェクトを生成して用いるようになるわけです。これによって、 UI 側で求められるデータモデルと AI で用いるデータモデルに差異があったとしても、どちらも犠牲にすることなく体験を構成できるようになるわけです。
// Explicitly convert your UIMessages to ModelMessages
const uiMessages: UIMessage[] = [ /* ... */ ]
const modelMessages = convertToModelMessages(uiMessages);
const result = await streamText({
model: openai('gpt-4o'),
// Convert the rich UIMessage format to ModelMessage format
// This can be replaced with any function that returns ModelMessage[]
messages: modelMessages,
});
// When finished: Get the complete UIMessage array for persistence
return result.toUIMessageStreamResponse({
originalMessages: uiMessages,
onFinish: ({ messages, responseMessage }) => {
// Save the complete UIMessage array - your full source of truth
saveChat({ chatId, messages });
// Or save just the response message
saveMessage({ chatId, message: responseMessage })
},
});
UI と AI の部分が明確に分離できるようになる（かも？）
上記によって、UI と AI の関心の分離が計りやすくなるのではと私は考えています。UIMessages はカスタマイズに対応しており、型を拡張することが容易です。
今までは、よくも悪くも AI が生成した結果をそのまま活用するか、AIの結果をある程度犠牲にして UI に最適化するか、の取捨選択をしないといけませんでした。なぜなら、チャットのような連続性のあるやり取りを AI と行う場合は、タイムラインの情報を全て保持して、プロンプトを生成しないとコンテキストが正しく伝わらないためです。
しかし、正直言って AI が生成するレスポンスの JSON はデータ量も多いわ、構造も複雑だわ、で別途取得した JSON を変換するアダプター層を UI 側で用意することになっていました。Next.js などで同一アプリ内でモデルを提供する場合はまだしも、別で分かれている場合は「そもそもツールには何があるのか」や「どういう時にツールは、何個まで使えるのか」などを明示的に共有しておく必要もあり、その多くは API 仕様には表出してきません。（リクエスト時に選択することは可能です）
結果として、現在まで AI Agent を書く際は「API定義をある程度決めて、振る舞いを固定する」か「UI側が力技で頑張るか」の二つに一つ、という状況だったわけです。今回のアップデートを用いると、UI 側は UIMessages に必要な型を宣言しておけば、レスポンス時にその型に格納してくれるようになる点で、非常に魅力的なアップデートとなるわけです。
mastra の generateVNext, streamVNext は何が変わるのか
上記を踏まえて、mastra の今回のアップデートを見てみましょう。streamVNext をみてみると以下のような変更点があることがわかります。
- streamVNext に
formatの option が増えている - stopWhen のパラメータが増えている （Agentic Loop Control の機能です）
- レスポンスを stream で受け取ったあと、UIMessage に変換し直している
import { stepCountIs } from 'ai-v5';
const stream = await agent.streamVNext("Tell me a story", {
format: 'aisdk',
stopWhen: stepCountIs(3), // 3ステップ後に停止
modelSettings: {
temperature: 0.7,
},
});
// AI SDK v5 互換のインターフェースで使用
for await (const part of stream.fullStream) {
if (part.type === 'text-delta') {
console.log(part.text);
}
}
// フロントエンド統合用の API ルート内で
return stream.toUIMessageStreamResponse();
VNext に移行すれば自然に AI SDK のエコシステムと統合可能に
Vercel AI SDK の v5 と相互運用可能になることで、 mastra を利用している時でも Vercel AI SDK の UI 機能の恩恵を受けられるようになります。以下で紹介されているマイグレーションの手順を踏むと、 v4 で行っていたのと同じような体験が実現できるわけです。
また、 assistant-ui などを活用しチャット機能を実装していた方々も、format パラメータを変更しない限り従来と同じレスポンスが返却されます。 mastra のアップデートをやめることなく対応できる点も非常にクールであると言えるでしょう。
また、これをきっかけに Vercel AI SDK v5 で書き始めた AI 機能を mastra に置き換える場合も、UIのコードは変更せず、LLMのモデル部分を素の Vercel AI SDK から、mastra に置き換えるだけで移行が完了しそうです。その意味で、かなり後方互換性をケアした機能提供となっていると言えるでしょう。
まとめ 〜今回のアップデートは怖くない〜
mastra の generateVNext, streamVNext をきっかけに Vercel AI SDK v5 の変更点や mastra の対応がどのようなものであったかをみてきました。以前のように、丸っと色々を書き換える必要はなく、今回に関してはかなり後方互換性が考えられたアップデートとなっており非常に好感が持てる内容でした。
mastra は関連ライブラリが多く、周辺のアップデートを行うと全体のライブラリのアップデートを行わないといけないケースもあるかと思います。そういう場合でも安心して利用していただけるのではないでしょうか。
Unreliable では、巷であふれる AI ニュースを実務家がピックアップし、調査を行って情報発信を行っております。記事を投稿したい方、こういうネタを取り上げてほしいなどあれば、コメントをお寄せいただけましたら非常にありがたいです！次回もお楽しみに
Discussion