> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

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

> **最新の 0.x バージョンへ更新:** v1 へアップグレードする前に、Mastra の最新 0.x バージョンへ更新してください。まず[最新 0.x へのアップグレードガイド](https://mastra.ai/guides/v0/migrations/upgrade-to-latest-0x)に従い、その後このページに戻って v1 への移行を完了してください。

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

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

> **サポートが必要ですか？:** 移行についてサポートが必要な場合は、[Discord コミュニティ](https://discord.gg/BTYqqHKUrf)で質問してください。

> **Mastra Cloud から移行しますか？:** 従来の Mastra Cloud 製品は [Mastra platform](https://mastra.zisheng.pro/ja/docs/mastra-platform/overview) に置き換えられ、ホスティングは **Studio**（ビジュアル環境、Observability）と **Server**（本番 API）の 2 製品に分かれました。以前の Mastra Cloud アクセストークンは Mastra platform では使用できません。`mastra auth tokens create` で新しいトークンを作成してください。
>
> v1 パッケージへアップグレードするときに、`telemetry:` 設定から `observability:` 設定への移行と Studio プロジェクトの作成を行わないと、Observability データの送信が停止します。[Mastra Cloud 移行ガイド](https://mastra.zisheng.pro/ja/guides/migrations/mastra-cloud)のすべての手順に従ってください。

## 移行方針

### すべての Mastra パッケージを `latest` タグへ更新する

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

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

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Yarn**:

```bash
yarn add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Bun**:

```bash
bun add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

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

### Node.js のバージョンを更新する

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

### 移行チェックリストを進める

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

> **Codemod:** 自動化された [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) を用意しています。必要に応じて、すべての v1 codemod を一度に実行できます。
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

> **データベースの移行が必要:** PostgreSQL または LibSQL Storage を使用している場合は、データベースを移行する必要があります。詳しくは、[Storage 移行ガイド](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/storage)を参照してください。

## 領域別の破壊的変更

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

## 移行チェックリスト

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

> **Codemod:** 自動化された [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) を用意しています。移行ガイドの各所に、特定の変更に対応する codemod の使用方法を記載しています。
>
> 必要に応じて、すべての v1 codemod を一度に実行できます。
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

### 影響度：高

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

### 影響度：中

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

### 影響度：低

- Chunk オプションの `keepSeparator` を `separatorPosition` に改名 - [RAG](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/rag)
- `createRunAsync` を `createRun` に改名 - [Workflow](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/workflows)
- Voice パッケージ名を `@mastra/speech-*` から `@mastra/voice-*` へ更新 - [Voice パッケージ](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/voice)
- Scorer メソッドを更新：`runExperiment` → `runEvals`、`getScorerByName` → `getScorerById` - [Eval と Scorer](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/evals)
- 非推奨の CLI フラグを削除 - [CLI](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/cli)
- Client SDK の型を `Get*` から `List*` へ更新 - [Client SDK](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/client)
- `runCount` を `retryCount` に置き換え - [Workflow](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/workflows)
- カスタム Exporter のメソッド `exportEvent` を `exportTracingEvent` に更新（カスタム Exporter を使用している場合）- [Tracing](https://mastra.zisheng.pro/ja/guides/migrations/upgrade-to-v1/tracing)