メインコンテンツへ移動

Mastra v1 へアップグレードする

最新の 0.x バージョンへ更新

v1 へアップグレードする前に、Mastra の最新 0.x バージョンへ更新してください。まず最新 0.x へのアップグレードガイドに従い、その後このページに戻って v1 への移行を完了してください。

Mastra v1 は 2026 年 1 月にリリースされました。新しいプロジェクトでは Mastra v1 を使用し、既存のプロジェクトでは更新とサポートを引き続き受けられるようアップグレードすることを推奨します。

このガイドでは、Mastra 0.x から v1.0 へアップグレードする際の破壊的変更を扱います。コードベースを体系的に更新できるよう、移行内容をパッケージと機能領域ごとに整理しています。

サポートが必要ですか？

移行についてサポートが必要な場合は、Discord コミュニティで質問してください。

Mastra Cloud から移行しますか？

従来の Mastra Cloud 製品は Mastra platform に置き換えられ、ホスティングは Studio（ビジュアル環境、Observability）と Server（本番 API）の 2 製品に分かれました。以前の Mastra Cloud アクセストークンは Mastra platform では使用できません。mastra auth tokens create で新しいトークンを作成してください。

v1 パッケージへアップグレードするときに、telemetry: 設定から observability: 設定への移行と Studio プロジェクトの作成を行わないと、Observability データの送信が停止します。Mastra Cloud 移行ガイドのすべての手順に従ってください。

移行方針
移行方針への直接リンク

すべての Mastra パッケージを latest タグへ更新する
update-all-mastra-packages-to-latest-tagへの直接リンク

パッケージマネージャーを使用して、プロジェクトのバージョンを更新します。互換性を確保するため、すべての Mastra パッケージ（すべての @mastra/* パッケージと mastra）をまとめて更新してください。

よく使用されるパッケージを更新する方法は次のとおりです。

npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest

その他の Mastra パッケージも @latest タグ付きでインストールすると、利用可能な最新の v1 バージョンが取得されます。バージョンの不一致を避けるため、すべての Mastra パッケージを必ず更新してください。特に monorepo では注意が必要です。

Node.js のバージョンを更新する
Node.js のバージョンを更新するへの直接リンク

Mastra v1 には Node.js 22.13.0 以降が必要です。開発環境と本番環境を更新してください。

移行チェックリストを進める
移行チェックリストを進めるへの直接リンク

以下の移行チェックリストに沿ってコードベースを更新してください。各項目から、その変更の詳細ガイドへ移動できます。

Codemod

自動化された codemod を用意しています。必要に応じて、すべての v1 codemod を一度に実行できます。

npx @mastra/codemod@latest v1
データベースの移行が必要

PostgreSQL または LibSQL Storage を使用している場合は、データベースを移行する必要があります。詳しくは、Storage 移行ガイドを参照してください。

領域別の破壊的変更
領域別の破壊的変更への直接リンク

  • Mastra クラス - import の再構成とプロパティアクセスの変更。
  • Agent クラス - Voice メソッドの名前空間への移動と Streaming API の更新。
  • Tool - CreateTool の execute シグネチャを入力とコンテキストに分割。
  • Workflow - 関数名の変更とレガシー機能の削除。
  • Memory - 設定で明示的なパラメーターが必須になり、デフォルトを変更。
  • Storage - ページネーションを標準化し、メソッド名を list パターンへ変更。
  • Vector - Vector Store のメソッド名を list パターンへ変更。
  • RAG - 明確性を高めるためパラメーター名を更新。
  • MCP - Tool コンテキストを再構成し、非推奨のクライアントクラスを削除。
  • Tracing - OTEL Telemetry を専用の Observability パッケージと Exporter に置き換え。
  • Eval と Scorer - Scorer API を統合し、新しい命名規則を導入。
  • CLI - インターフェースを簡素化するためコマンドとフラグを削除。
  • デプロイ - CloudflareDeployer 設定を標準の wrangler.json プロパティ名へ更新。
  • Client SDK - 一貫性を保つため型とユーティリティを改名。
  • Voice パッケージ - パッケージ名を speech から voice へ変更。

移行チェックリスト
移行チェックリストへの直接リンク

ほとんどのアプリケーションに影響する変更から順に、このチェックリストを進めてください。

Codemod

自動化された codemod を用意しています。移行ガイドの各所に、特定の変更に対応する codemod の使用方法を記載しています。

必要に応じて、すべての v1 codemod を一度に実行できます。

npx @mastra/codemod@latest v1

影響度：高
影響度：高への直接リンク

  • createTool の Tool シグネチャを (inputData, context) 形式へ更新 - Tool
  • @mastra/core の import をサブパス import へ再構成 - Mastra クラス
  • ページネーションを offset/limit から page/perPage へ更新 - Storage
  • @mastra/observability をインストールし、設定を new Observability() でラップ - Tracing
  • telemetry: から observability: 設定へ移行（0.x OTEL からアップグレードする場合）- Tracing

影響度：中
影響度：中への直接リンク

  • コードベース全体で RuntimeContext を RequestContext に改名 - Agent クラス、Tool、Workflow
  • Storage メソッドを get* から list* パターンへ更新 - Storage
  • プロパティへの直接アクセスを getter メソッドへ置き換え - Mastra クラス、Agent クラス
  • デフォルトの thread スコープに依存している場合は Memory スコープを更新 - Memory
  • Vector Store の呼び出しを名前付き引数を使用するよう更新 - Storage
  • Agent メソッドから format パラメーターを削除 - Agent クラス
  • Voice メソッドを agent.voice 名前空間を使用するよう更新 - Agent クラス
  • 設定プロパティ processors を spanOutputProcessors に改名（カスタム Processor を使用している場合）- Tracing

影響度：低
影響度：低への直接リンク

  • Chunk オプションの keepSeparator を separatorPosition に改名 - RAG
  • createRunAsync を createRun に改名 - Workflow
  • Voice パッケージ名を @mastra/speech-* から @mastra/voice-* へ更新 - Voice パッケージ
  • Scorer メソッドを更新：runExperiment → runEvals、getScorerByName → getScorerById - Eval と Scorer
  • 非推奨の CLI フラグを削除 - CLI
  • Client SDK の型を Get* から List* へ更新 - Client SDK
  • runCount を retryCount に置き換え - Workflow
  • カスタム Exporter のメソッド exportEvent を exportTracingEvent に更新（カスタム Exporter を使用している場合）- Tracing
On this page