migrating-mastra-to-pydantic-ai

Mastra から Pydantic AI への移行

TypeScript や Mastra のオブジェクトモデルではなく、外部から観測できる動作を維持してください。最小限で完結する呼び出し経路を移行し、アプリケーションのインフラストラクチャはそのまま残します。

移行先を選ぶ前にソースを追跡する

1. リポジトリの指示、依存関係、テスト、実行時のエントリーポイントを確認します。インストールされている Mastra、Pydantic AI、Harness のバージョンを記録します。
2. 公開エントリーポイントから始まる実際のリクエストを1つ追跡します。エントリーポイントは Agent.generate() ／ Agent.stream() の呼び出しでも、ワークフローの実行でもかまいません。呼び出し元が利用するツール、プロセッサー、メモリ、イベント、結果、状態、副作用まで追跡します。焦点を絞ったベースラインテストまたは特性テストを確立します。
3. 該当する場合、次のソース契約を分けて整理します。
   • リクエストコンテキスト、モデルが選択したツール入力、ワークフローの入出力、共有ワークフロー状態
   • 会話メッセージ、意味検索による想起、作業用または観察用メモリ、ワークフローのスナップショット、モデルが管理する計画
   • 最終的なテキストまたはオブジェクト、トークン差分、ライフサイクルイベント、トリップワイヤー、ワークフローの終了状態
   • ツールの承認、認証済みの認可、プロセスまたはサンドボックスによる分離
   • 決定的なワークフロー、エージェントが選択する委譲、キュー、スケジュール、永続的な実行
4. 観測した各契約、その所有者、意味上の違い、実行可能な証明を記録します。使用されていない Mastra の機能は移行対象ではありません。

検出されたソース機能については、調査と概念の対応付けを参照してください。実装の前に検証と切り替えを読んでください。

最小限の移行先を選ぶ

• コア： エージェントのループ、型付き依存関係、ツール、出力、正規化されたメッセージ、汎用フック、ストリーミング、MCP クライアント、承認、使用量制限、計装、リアルタイム機能、永続ランタイムとの統合には pydantic_ai.Agent を使用します。
• グラフ： 明示的な型付きノード、分岐、結合が引き続き有用な場合に限り pydantic_graph を使用します。単純で固定された制御フローには通常の非同期 Python を使用します。
• Harness： 観測された再利用可能なポリシーがある場合に限り、pydantic-ai-harness を追加します。対象となるのは、メモリノートブック、計画、モデル主導のサブエージェント、Agent Skills、コーディングツール、ガードレール、モデルに依存しないコンパクション戦略、ステップの永続化などです。Harness の機能はコアのエージェントループと組み合わせて使います。Harness はワークフローエンジンでも、2つ目のランタイムでもありません。
• 評価： 観測されたデータセット、ケース、評価器には、別パッケージの pydantic-evals を追加します。
• アプリケーション： 対象の移行範囲に含まれない限り、認証、データベース、ベクトル検索、キュー、スケジューラー、デプロイ、製品の状態、API／UI トランスポート、セッション検索、テナントポリシーは維持します。
• ギャップ： サポートされている公開シームでは維持できない動作を特定し、その影響を説明したうえで、範囲を限定したアダプターをテストします。違いを隠すためだけに Mastra のレジストリ、サーバー、ストレージスキーマ、イベント分類を再現してはいけません。

通常の移行では、再利用可能な Agent を1つ用意し、型付き依存関係を通じてアプリケーションサービスを提供し、通常の Pydantic AI ツールを使います。呼び出し元が構造化データを期待する場合は型付き出力を使い、後続のターンに備えて result.all_messages() をアプリケーション側で保存します。既存の HTTP、ジョブ、UI の境界は、現在のフィールド名を維持した小さなアダプターで保ちます。Mastra の呼び出しがプロセス内だけで行われている場合は、同じ移行範囲で最も近い呼び出し元も移行するか、アプリケーションが所有する新しいサービス境界に明示的に合意します。デフォルトでトランスポートを追加してはいけません。

高リスク項目のゲートを適用する

• Mastra の RequestContext は信頼された実行コンテキストであり、モデル入力ではありません。認証済みの ID とサービスを型付き依存関係にマッピングし、モデルが選択した値のみをツールパラメーターとして公開します。
• Mastra のメモリには、異なる動作が組み合わされています。スレッドのメッセージはシリアライズされた Pydantic AI のメッセージ履歴にマッピングし、セマンティック検索はアプリケーションサービスまたはツールの背後に配置します。また、モデルが所有するノートブックのセマンティクスによって、観測されたワーキングメモリの契約が維持される場合に限り、Harness Memory を使用します。既存の Mastra レコードについては、一度限りの変換、読み取り時アダプター、または変更として受け入れた上での新規開始のいずれかを明示的に選択し、テストします。メッセージ履歴、ノートブック、Harness StepPersistence をワークフローのスナップショットとして扱わないでください。
• Mastra ワークフローは、決定論的なアプリケーション制御フローです。通常の Python または pydantic_graph を使用し、.branch()、.parallel()、.foreach()、ループ、または中断条件をエージェントのプロンプトに移さないでください。並行処理、集約、失敗、キャンセルのセマンティクスを明示的に維持します。
• Mastra ワークフローの中断では、再開可能なスナップショットが永続化されます。分岐とワークフロー状態の永続化は、アプリケーションまたは基盤となる耐久性エンジンに保持し、約束したステップから再起動できることを証明します。Pydantic AI の耐久性インテグレーションは、そのワークフロー内のエージェントのモデル、ツール、MCP 操作を耐久化しますが、ワークフローを取り巻く制御フローは管理しません。遅延ツールが保持するのはエージェントのツール呼び出しであり、任意のワークフロー状態ではありません。
• プロセッサーは、発火時点、入力・出力の変更、トリップワイヤーの動作、順序、ストリーミング時の可視性、永続化の観点でマッピングします。コアの履歴プロセッサー、出力バリデーター、フック、Harness の入力・出力・ツールのガードレール、カスタム機能、アプリケーションアダプターのうち、最も限定的なものを使い、呼び出し元から見えるイベントやエラーについてはゴールデンテストを行います。
• 承認は、検証済みのアクションを一時停止します。承認者の認証は行いません。ID、認可、監査、相関、冪等性はアプリケーションで管理し、承認前に副作用が実行されないことを証明します。
• ストリーミングに関する利用者の意図をマッピングします。Pydantic AI の出力ストリーミング、実行イベントのストリーミング、UI アダプター、グラフの反復処理は、それぞれ異なるインターフェースです。いずれも Mastra の fullStream のチャンク分類を保証するものではありません。
• Harness SubAgents は、モデル主導の委任にのみ使用します。決定論的なファンアウト、集約、再試行、スコアラー主導の検証ループは、アプリケーションまたはグラフのコードに保持します。
• Mastra Agent Skills には、参照情報や動的解決が含まれる場合があります。Harness Skills がオンデマンドで読み込むのは SKILL.md の指示のみであり、.agents や .claude を自動的にスキャンすることはありません。必要な参照情報には Harness FileSystem またはアプリケーションツールを使用し、リクエストごとの選択を個別にテストします。
• Mastra Studio、サーバーアダプター、ストレージプロバイダー、デプロイ先、ログ、トレースストレージ、ライブ評価のスケジューリングは、プロダクトのインフラストラクチャです。エージェントの移植で同等になると見なさず、意図的に維持または置換します。
• Mastra の耐久性エージェント、ワークフローのタイムトラベル、厳密なスナップショット互換性、観測メモリの圧縮、厳密な生イベント ID は、観測された呼び出し元に対応するサポート済みの移行先の拡張ポイントが実証されない限り、ギャップとして扱います。

垂直スライスを1つ実装して検証する

1. サポート対象の呼び出し元との境界を維持し、エージェントが所有する内部実装のみを置き換えます。
2. まずコアだけで始めます。ソースの契約で必要とされる場合に限り、pydantic_graph、Harness、Pydantic Evals、または永続ランタイムを追加します。
3. その境界で、入力、型付き出力、エラー、イベントの順序、ツールの引数と結果、プロセッサの判断、ターン間の状態、サイドエフェクトをテストします。オフラインでは決定論的なモデルとアプリケーションサービスのフェイクを使用し、プロバイダーの動作が契約となる場合に限り、対象を絞った記録済みテストまたはライブテストを追加します。
4. 永続化、承認、並行ワークフロー、または外部への作用については、Mastra が保証する境界で、中断と再起動、系譜、認可、失敗の集約、冪等性をテストします。
5. 残す経路で必要とされなくなった後にのみ、@mastra/*、Mastra サーバーのセットアップ、Mastra のストレージまたはイベントアダプターを削除します。

実装に入る前に、重大な意味上の変更について説明します。ソースの動作、移行先の動作、呼び出し元への影響、推奨する選択肢、残るリスクを示してください。

完了

検証と切り替えに記載された完了基準を適用します。フェイク、記録データ、ライブプロバイダーによる証拠は、それぞれ正確に区別して明記してください。