migrating-langchain-to-pydantic-ai

LangChain、LangGraph、Deep Agents から Pydantic AI への移行

フレームワークの構成ではなく、動作を維持してください。動作として完結する最小の範囲を移行し、その範囲外のアプリケーション基盤は変更せずに残してください。LangChain、LangGraph、Deep Agents は同じ移行元エコシステムに属します。Pydantic AI、pydantic_graph、Pydantic AI Harness は対応する移行先エコシステムであり、このスキルはその全体を対象にしています。

実行中のアプリケーションを基準に作業する

1. リポジトリの指示、依存関係ファイル、テスト、実際のランタイムエントリーポイントを確認します。インストールされている LangChain、LangGraph、Deep Agents、Pydantic AI、Harness のバージョンを特定します。
2. 代表的なリクエストについて、プロンプト、検索、モデルとツールの呼び出し、状態、永続化、中断、出力イベント、トレース／メトリクスのコールバック、公開結果まで追跡します。移行するコンポーネントを使用するすべての呼び出し元と関連エンドポイントを調べます。実装範囲が狭くても、公開契約は複数存在することがあります。呼び出し元が実際に使用しているキーワードパラメーター名と、同期、非同期、コールバック、ストリーミングの各形式を含めます。それらの経路で実際に使用されている契約だけを記録します。
3. コストが最も低く、有用なベースラインを実行します。移行範囲が広い、または不明確な場合は、依存関係ファイルとソースコードから langchain、langgraph、langsmith、deepagents を検索し、インポート、ファクトリー、呼び出し箇所で見つかった内容を確認します。create_deep_agent の提供元を特定します。上流パッケージと、その契約を再現するベンダー版のどちらも Deep Agents として扱います。
4. 移行先を選ぶ前に、対象範囲を分類します。
   • Chain または LCEL パイプライン： 決定論的な検索と変換は通常の Python のまま維持し、モデル／ツールのループに価値がある場合にのみ Pydantic AI のエージェントを使用します。
   • LangChain エージェント： 通常は、型付き依存関係、ツール、出力を備えた再利用可能な単一の pydantic_ai.Agent を使用します。
   • LangGraph ワークフローを直接使用： 固定された単純な制御フローには通常の非同期 Python を使用し、明示的な型付きノードや分岐が引き続き役立つ場合は pydantic_graph を使用します。永続化は別途設計上の判断として扱います。
   • Deep Agents Harness： create_deep_agent は、LangChain エージェントのループを基盤として、ファイルツール、シェル実行、サブエージェントへの委任、要約、スキル、メモリ、権限、プロンプトキャッシュ、承認ミドルウェアをまとめて提供します。また、Harness プロファイルによって機能が追加されたり非表示になったりすることがあります。LangChain の対応付けに従ってループを移行し、対象範囲で実際に使用されているバンドル機能を、Deep Agents の対応付けに従って Harness の機能、コアプリミティブ、またはアプリケーションサービスに対応付けます。アプリケーションコードに明記されていない暗黙のデフォルトも洗い出します。
   • プロダクトのランタイム： ユーザーが対象範囲に含めた場合を除き、キュー、構成済みデータベースバックエンド、サンドボックス、認証、スケジューラー、Webhook、トレーシング、トランスポートアダプターは維持します。永続化やプロバイダーの仕組みを別途作る前に、既存のアプリケーション境界を拡張します。
5. 決定論的な特性テストを追加または維持したうえで、既存の公開境界の内側で垂直スライスを一つずつ移行します。
6. 元のテストと、範囲を絞った同等性テストを実行します。観測された各契約を、それを裏付ける根拠に応じて分類します。正常系やトレースの形が似ているだけで、移行を一対一の対応だと説明してはいけません。

検出された移行元の機能については、概念の対応付けを参照してください。対象範囲に deepagents が含まれる場合は、Deep Agents の対応付けを参照してください。状態、ミドルウェア、リトライ、承認、並行処理、ストリーミングなど、似た API でも動作が異なる可能性がある場合に限り、意味上の差異を参照してください。具体的な差異が特定された後で回避策のレシピを使用し、必須のチェックリストとして扱わないでください。オブザーバビリティを追加するとき、移行元と移行先の実行を比較するとき、または意味上の違いをデバッグするときは、Logfire の検証を参照してください。本番環境へ切り替える前に、検証と切り替えを参照してください。

セマンティクスの違いを説明する

観察されたソースの契約に直接対応するものがない場合、重大な設計上の判断を下す前に、その違いをユーザーに説明してください。ソースの動作、提案する Pydantic AI の設計との違い、ユーザーから見た影響または運用上の影響、選択肢を明示してください。1 つの選択肢を推奨し、その選択に残るリスクも示してください。説明は必要な範囲にとどめてください。通常のインポートや名前の変更を、セマンティクス上の警告にしないでください。

「サポートされていない」と伝えるだけで終わらせないでください。直接対応するものがない場合は、既存のコアまたは Harness の組み合わせ、範囲を絞ったアダプターまたはアプリケーションサービス、公開プリミティブを使った新しい機能、コアの変更の順に推奨してください。選択肢によって動作、アーキテクチャ、公開 API、またはスコープが大きく変わる場合に限り、選択する前に確認してください。

リスクに応じて厳密さを調整する

• ステートレスなチェーンや通常のエージェントの移植では、対象を絞った特性テストと短い残存リスクの注記で十分です。ソースにない動作について、セマンティクス上の差異の台帳や耐久性の検証を求めないでください。
• ミドルウェア、構造化出力の転送、検索拡張、ツールの再試行、ストリーミングでは、インストール済みのバージョンを使って、影響を受ける契約を検証してください。
• チェックポイント付きグラフ、中断、承認、耐久性のある実行、並行ファンアウト、外部副作用では、移行台帳を作成してください。依存関係、メッセージ、ワークフローの状態、チェックポイントの状態、長期記憶を分けてください。可能な場合は、それらの所有者をリポジトリ既存のバックエンド選択およびサービスインターフェースに適合させてください。再起動、リプレイ、相関付け、認可、冪等性は、ソースが保証する範囲に限ってテストしてください。
• deepagents の依存関係があるだけでは、何も変わりません。アクティブなスライスが create_deep_agent を呼び出す場合、またはその計画、ファイルシステム、サンドボックス、スキル、メモリ、サブエージェント、権限、デプロイメントに関する契約に依存する場合、それらは Harness またはアプリケーションの所有者が担う対象範囲内の機能であり、作業を止める理由にはなりません。ファイル、サンドボックス、権限、サブエージェント、バックグラウンド作業にも、チェックポイント付きグラフと同じ台帳および再起動の要件が適用されます。

Pydantic AI のデフォルト

• 認証済みのアイデンティティ、サービスクライアント、設定は、モデルが選択するツール引数ではなく、型付き依存関係に格納します。
• アプリケーション全体ではなく、観測された不安定な境界を強化します。エージェントの依存関係と出力の型をパラメーター化し、最終的な選択、永続化されたワークフロー記録、フレームワークアダプターを検証します。安定した公開ワイヤー形式は維持し、移行対象の範囲外にあるパスに新たな型を導入しないでください。
• 呼び出し元が移行する間は、小規模なアダプターを使って公開リクエスト、レスポンス、エラー、イベントの形式を維持します。
• 要求された範囲外にある場合は、検索、ストレージ、プロバイダー、トランスポートの統合をそのまま維持します。移行期間中の LangChain 統合は、名称が明示され、範囲が限定されていれば許容されます。
• 契約の維持につながる場合は、最終的な構造化出力に Pydantic モデルを使用します。ワイヤー契約の変更によって移行範囲が拡大する場合は、既存のパーサーを維持します。
• 決定論的な LCEL に Agent を無理に適用したり、すべての StateGraph に pydantic_graph を適用したりしないでください。
• モデルクラス、プロバイダートランスポート、フック、ストリーミングメソッド、永続化統合を選ぶ前に、インストール済みの Pydantic AI API を確認します。
• pydantic-ai-harness は、計画、ワークスペースファイル、シェルまたはサンドボックス化された実行、Agent Skills、メモリノートブック、リポジトリコンテキスト、モデル主導のサブエージェント、モデルに依存しない圧縮、ツール出力の上限、ガードレール、利用料金の上限、ステップの永続化など、ハーネスの動作が実際に確認された場合にのみ追加します。機能は一度に1つずつ追加し、それぞれを所有する公開サブモジュールからインポートします。pydantic_ai_harness.experimental.* はバージョンによって変わり得るものとして扱い、対象環境でインポートと構築のスモークテストを実行します。ハーネスはコアのエージェントループに組み合わせて使用するものであり、別のランタイムではなく、アプリケーションのインフラストラクチャに取って代わるものでもありません。
• Pydantic AI を追加する際は、現在サポートされている安定版リリースを優先します。無関係なメジャーアップグレードやランタイムアップグレードを通じて移行範囲が拡大する場合を除き、互換性のある最新リリースを使用します。例外を選ぶ場合は、その理由を説明し、バージョンを固定します。既存の環境によって互換性のない推移的依存関係が隠れることがあるため、クリーンな環境からプロジェクト全体の依存関係を解決し、インポートプローブを実行します。依存関係の範囲が限定されている場合は、必要なプロバイダーと統合用のエクストラのみを含む pydantic-ai-slim を優先し、より広範な統合が実際に必要な場合はフルディストリビューションを使用します。記憶にある例に合わせるためだけに、古いリリースを固定しないでください。
• ソースですでに LangSmith、Langfuse、その他の可観測性システムを使用している場合は、説明なしに置き換えないでください。Logfire は Pydantic AI のファーストパーティ統合であり、通常、エージェント、モデル、ツール、リトライ、エラー、利用状況、タイミングを最も直接的に把握できます。一方、現在のシステムを維持すれば、ダッシュボード、アラート、評価、保持ポリシー、エクスポートパイプラインを継続して利用できます。この違いを説明し、切り替える前に推奨案を示して合意を得ます。トレースシステムがない場合、またはユーザーが選択した場合は、アプリケーションの起動時に Logfire を提案します。コンテンツの記録はプライバシーに関する明示的な判断事項とし、同等性の判断には実行可能な契約テストを基準として使用します。

完了

観測されたすべての契約について、実行可能なチェックで維持されているか、合意された判断によって意図的に変更されているか、または明示的に該当しないとされている場合に、この範囲は完了です。テストされていない契約は同等とはみなされず、unverified です。要求された契約が未解決の場合は、完了の根拠ではなく未完了の作業です。範囲を限定するか、延期についてユーザーに承認を求めてください。保持するパスで必要とされなくなった後にのみ、LangChain、LangGraph、または Deep Agents の依存関係を削除します。