TypeScriptで書かれたMastraアプリケーションをPythonに移行する際に、Pydantic AIを使用します。必要に応じて、Pydantic AI Harness（複数の処理を統合するツール）の利用も検討してください。 次のような場合に使用: - ソースコードが`@mastra/*`をインポートしている - Mastraのエージェント（自動実行機能）、ツール、ワークフロー（処理の流れ）、メモリ、プロセッサー、ストリーミング（連続データ送信）、承認機能、スキル、またはサブエージェント（階層化されたエージェント）に依存している
Migrate TypeScript Mastra applications to Python with Pydantic AI and, only when needed, Pydantic AI Harness. Use when source code imports `@mastra/*` or relies on Mastra agents, tools, workflows, memory, processors, streaming, approvals, skills, or subagents.
観測可能な動作を保つこと。TypeScriptやMastraのオブジェクトモデルではなく、呼び出し元が依存している実際の動作を保ちます。最小の完全な呼び出しパスを移行し、アプリケーション基盤は現状のまま保ちます。
リポジトリの説明書、依存パッケージ、テスト、実行時の入口を読みます。インストール済みのMastra、Pydantic AI、Harnessのバージョンを記録します。
実際のリクエストを公開入口から1つ追跡します。Agent.generate()やAgent.stream()の呼び出し、またはワークフロー実行から始まり、ツール、プロセッサ、メモリ、イベント、結果、状態、副作用を通じて、呼び出し元が使う部分まで追跡します。ベースラインテストまたは特性テストを確立します。
存在するこれらのソースコントラクト（呼び出し元との契約）を分離します：
観測されたコントラクト、その所有者、意味的差異、実行可能な証明をそれぞれ記録します。使用されていないMastra機能は移行対象外です。
検出されたソース機能の調査とマッピングを読みます。実装前に検証とカットオーバーを読みます。
コア： pydantic_ai.Agentをエージェントループ、型付き依存関係、ツール、出力、正規化メッセージ、一般的なフック、ストリーミング、MCPクライアント、承認、使用制限、計測、リアルタイム、耐久性ランタイム統合に使用します。
グラフ： pydantic_graphは、明示的な型付きノード、分岐、結合が有用な場合のみ使用します。単純で固定的な制御フローには、普通のPythonの非同期関数を使用します。
Harness： メモリノート、計画、モデル指向のサブエージェント、エージェント スキル、コーディングツール、ガードレール、モデル非依存な圧縮戦略、ステップ永続化など、観測された再利用可能なポリシーがある場合のみ、pydantic-ai-harnessを追加します。Harnessの機能はコアエージェントループを通じて構成されます。Harnessはワークフローエンジンや第2のランタイムではありません。
評価： 観測されたデータセット、テストケース、評価器に対して、別のpydantic-evalsパッケージを追加します。
アプリケーション： 認証、データベース、ベクトル検索、キュー、スケジューラ、デプロイ、プロダクト状態、API/UIトランスポート、セッション検索、テナント管理ポリシーは保持します。リクエストされた部分に含まれている場合を除きます。
ギャップ： サポート対象の公開インターフェースで保証されない動作に名前を付け、その影響を説明し、限定的なアダプタをテストします。違いを隠すためだけにMastraレジストリ、サーバ、ストレージスキーマ、またはイベント分類を再現しないでください。
標準的な移行は、1つの再利用可能なAgent、型付き依存関係で提供されたアプリケーションサービス、通常のPydantic AIツール、呼び出し元が構造化データを期待する場合の型付き出力、result.all_messages()のアプリケーション所有ストレージで後続のターンに備えることです。既存のHTTP、ジョブ、またはUIの境界を小さなアダプタと現在のフィールド名で保持します。Mastraの呼び出しがプロセス内のみの場合は、同じスライス内の最も近い呼び出し元に移行するか、新しいアプリケーション所有のサービス境界を明示的に合意します。デフォルトでトランスポートを追加しないでください。
Mastra RequestContextは信頼されたランコンテキストであり、モデル入力ではありません。認証済みアイデンティティとサービスを型付き依存関係にマッピングします。モデルが選んだ値のみをツールパラメータとして公開します。
Mastraメモリは異なる動作を統合しています。スレッドメッセージを直列化されたPydantic AIメッセージ履歴にマッピングし、意味論的検索はアプリケーションサービスまたはツールの背後に保ち、HarnessのMemory（モデル所有の作業メモ）は観測された作業メモ契約を保つ場合のみ使用します。既存のMastraレコードについては、1回限りの変換、読み取りを通したアダプタ、または新規開始を明示的に選択しテストします。メッセージ履歴、ノート、またはHarnessのStepPersistenceをワークフロースナップショットとして扱わないでください。
Mastraワークフローは決定的なアプリケーション制御フローです。普通のPythonまたはpydantic_graphを使用します。.branch()、.parallel()、.foreach()、ループ、中断条件をエージェントプロンプトに移さないでください。並行性、集約、失敗、キャンセルセマンティクスを明示的に保ちます。
Mastraワークフロー中断は再開可能なスナップショットを永続化します。分岐とワークフロー状態の永続化をアプリケーションまたは基盤となる耐久性エンジンに保ち、約束されたステップでの再開を証明します。Pydantic AI耐久性統合は、そのワークフロー内でエージェントモデル、ツール、MCP操作を耐久化します。周囲の制御フローを所有しません。遅延ツールはエージェントツール呼び出しを保ち、任意のワークフロー状態ではありません。
プロセッサを発火ポイント、入出力変更、警告挙動、順序、ストリーミング可視性、永続化でマッピングします。コア履歴プロセッサ、出力検証器、フック、Harness入出力・ツールガードレール、カスタム機能、またはアプリケーションアダプタの最小限のものを使用し、呼び出し元に見える動作またはエラーについてゴールデンテストを行います。
承認は検証済みアクションを一時停止します。承認者を認証しません。アイデンティティ、認可、監査、相関、べき等性をアプリケーションに保ち、承認前に動作が実行されないことを証明します。
ストリーミングの消費者意図をマッピングします。Pydantic AI出力ストリーミング、実行イベントストリーミング、UIアダプタ、グラフ反復は異なるインターフェースです。MastraのfullStreamチャンク分類を約束するものはありません。
SubAgentsはモデル指向の委譲にのみ使用します。決定的なファンアウト、集約、リトライ、スコアラー駆動の検証ループはアプリケーションまたはグラフコードに保ちます。
Mastra エージェント スキルは参照と動的解決を含む場合があります。HarnessのSkillsはSKILL.md命令を要求時にロードするのみで、.agentsまたは.claudeを自動スキャンしません。必要な参照にはHarnessのFileSystemまたはアプリケーションツールを使用し、リクエストごとの選択を個別にテストします。
Mastra Studio、サーバアダプタ、ストレージプロバイダ、デプロイメントターゲット、ログ、トレースストレージ、ライブ評価スケジューリングはプロダクト基盤です。エージェント移行を同等と見なすのではなく、意識的に保持または置き換えます。
Mastra耐久性エージェント、ワークフロー時間旅行、完全スナップショット互換性、観測メモリ圧縮、完全な生イベント同一性は、サポート対象のターゲットシームが観測呼び出し元について証明されない限り、ギャップです。
サポート対象の呼び出し元の境界を保ち、エージェント所有の内部のみを置き換えます。
コアのみから始めます。ソースコントラクトが必要な場合のみ、pydantic_graph、Harness、Pydantic Evals、または耐久性ランタイムを追加します。
その境界での入力、型付き出力、エラー、イベント順序、ツール引数・結果、プロセッサ決定、複数ターン間の状態、副作用をテストします。決定的モデルと偽のアプリケーションサービスをオフラインで使用します。プロバイダ動作がコントラクトである場合のみ、限定的な記録またはライブテストを追加します。
永続化、承認、並行ワークフロー、外部動作については、中断と再開、系統、認可、失敗集約、べき等性をMastraが約束する正確な境界でテストします。
保持されたパスが不要になった後のみ、@mastra/*、Mastraサーバセットアップ、Mastraストレージまたはイベントアダプタを削除します。
実装前に重大な意味的変化を説明します。ソース動作、ターゲット動作、呼び出し元への影響、推奨選択肢、残存リスクを述べます。
検証とカットオーバーの完了基準を適用します。偽、記録、ライブプロバイダからの証拠に正確にラベルを付けます。
Preserve observable behavior, not TypeScript or Mastra's object model. Migrate the smallest complete caller path and keep application infrastructure in place.
Agent.generate() / Agent.stream() call or a workflow run, through the tools, processors, memory, events, results, state, and side effects that callers use. Establish a focused baseline or characterization test.Read Research and concept mapping for the detected source features. Read Verification and cutover before implementation.
pydantic_ai.Agent for the agent loop, typed dependencies, tools, outputs, normalized messages, generic hooks, streaming, MCP clients, approvals, usage limits, instrumentation, realtime, and durable-runtime integrations.pydantic_graph only when explicit typed nodes, branches, and joins remain useful; use plain async Python for simple fixed control flow.pydantic-ai-harness only for observed reusable policy such as memory notebooks, planning, model-directed subagents, Agent Skills, coding tools, guardrails, model-agnostic compaction strategies, or step persistence. Harness capabilities compose through the core agent loop; Harness is not a workflow engine or second runtime.pydantic-evals package for observed datasets, cases, and evaluators.The normal migration is one reusable Agent, application services supplied through typed dependencies, ordinary Pydantic AI tools, a typed output when callers expect structure, and application-owned storage of result.all_messages() for later turns. Preserve an existing HTTP, job, or UI boundary with a small adapter and its current field names. If the Mastra call is only in-process, migrate its nearest caller in the same slice or explicitly agree on a new application-owned service boundary; do not add a transport by default.
RequestContext is trusted run context, not model input. Map authenticated identity and services to typed dependencies; expose only model-chosen values as tool parameters.Memory only when its model-owned notebook semantics preserve the observed working-memory contract. For existing Mastra records, explicitly choose and test one-time conversion, a read-through adapter, or starting fresh as an accepted change. Do not treat message history, a notebook, or Harness StepPersistence as a workflow snapshot.pydantic_graph; do not move .branch(), .parallel(), .foreach(), loops, or suspend conditions into an agent prompt. Preserve concurrency, aggregation, failure, and cancellation semantics explicitly.fullStream chunk taxonomy.SubAgents only for model-directed delegation. Keep deterministic fan-out, aggregation, retries, and scorer-driven verification loops in application or graph code.Skills loads on-demand SKILL.md instructions only and does not automatically scan .agents or .claude; use Harness FileSystem or an application tool for required references, and test per-request selection separately.pydantic_graph, Harness, Pydantic Evals, or a durable runtime only after a source contract requires it.@mastra/*, Mastra server setup, and Mastra storage or event adapters only after no retained path needs them.Explain any consequential semantic change before implementing it: state the source behavior, target behavior, caller impact, recommended choice, and remaining risk.
Apply the completion criterion in Verification and cutover. Label evidence from fakes, recordings, and live providers accurately.
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。