migrating-deep-agents-to-pydantic-ai-harness

Deep Agents を Pydantic AI Harness に移行する

create_deep_agent の形ではなく、アプリケーションで観測された契約を維持します。Pydantic AI のプリミティブと Harness の機能を組み合わせ、インフラストラクチャは、すでにそれを所有しているアプリケーションに残します。

ソースの契約を確立する

1. これらのマッピングを適用する前に、deepagents のインポート元を特定します。ローカルモジュールまたはプロジェクト所有の create_deep_agent は、実装が通常の LangChain または LangGraph のセマンティクスを持つ場合に限り、通常の LangChain 移行の対象とします。Deep Agents の契約を再現するベンダー実装は、引き続き対象に含めます。リポジトリの指示、マニフェスト、ロックファイル、テスト、ランタイムのエントリーポイント、および特定したソースを確認します。Deep Agents、LangChain、LangGraph、Pydantic AI、Harness の正確なバージョンを記録します。
   ロックされたソースを利用できない場合は、ターゲットのロックファイルを変更せずに、その環境を再現します。それができない場合は、該当する動作を未検証として示し、同等性を主張しないでください。
2. 代表的なリクエストを、プロンプトとモデルプロファイル、ツールと統合、ミドルウェアと権限、バックエンドと実行、スキルとメモリ、委譲、状態、チェックポイントと承認、再試行と上限、イベント、副作用、パブリック境界を通じて追跡します。その境界を呼び出すすべての箇所を確認します。
3. 最も低コストで決定的なベースラインを実行します。証拠は結果と分けて記録します。source-inspected、probe-observed、regression-tested のいずれかを使います。
4. 検出したソースの機能に必要なマッピングだけを読み込みます。
   • 構築、モデルとプロファイル、プロンプト、ツールと MCP、ミドルウェア、状態、出力、キャッシュ、トレースには、コア移行を使用します。
   • コーディングエージェントのデフォルト、計画、ファイル、権限、バックエンド、サンドボックス、インタープリター、メディア、スキル、メモリ、検索、コンテキスト上限には、コンテキストと実行を使用します。
   • 同期、動的、またはバックグラウンドのサブエージェント、評価ループ、承認、チェックポイント、フォールトトレランス、耐久性のある実行、ストリーミングには、オーケストレーションと復旧を使用します。
   • Deep Agents Code、フロントエンド、ACP、A2A、またはデプロイ境界を移行する場合に限り、ホストとプロトコルを使用します。

Pydantic AI のターゲットを構築する

• 再利用可能な Agent を 1 つ用意します。Pydantic AI は、モデル／プロバイダーの境界、正規化されたメッセージ、エージェントのループ、型付きの依存関係と出力、ツールとツールセット、実行 API、使用量の上限、汎用フックを管理します。
• 認証済みの ID、サービスクライアント、設定は deps_type と RunContext に格納し、モデルが選択する入力のみを型付きツールで公開します。必要な履歴の動作に応じて instructions と system_prompt を選択し、フレームワークのメッセージがアプリケーション境界に漏れないよう、result.output を使用します。
• 実際に観察された任意の動作に合わせて、Harness の機能を 1 つずつ追加します。機能はエージェントに指示、ツールセット、フック、モデル設定を組み合わせるものであり、アプリケーションのインフラストラクチャや Pydantic AI の実行時セマンティクスを置き換えるものではありません。
• 呼び出し元の実際のライフサイクルに基づいて、run_sync、run、run_stream、run_stream_events、iter、遅延結果、メッセージ履歴を選択します。呼び出し元が移行する間は、境界アダプターを使って従来のワイヤ形式を維持します。
• コーディングの前に、ロック済みの pydantic_ai と pydantic_ai_harness について、選択したプロバイダー、Agent、ツール／ツールセット、機能、実行 API と遅延 API、永続化との統合に関する公開エクスポート、ドキュメント、ソースのシグネチャを確認します。機能はそれぞれが所有する公開サブモジュールからインポートし、非推奨の警告を拒否したうえで、実際のターゲット環境でインポートと構築のスモークテストを実行します。結果とともにインタープリター、および解決された pydantic_ai と pydantic_ai_harness のモジュールパスを記録します。必要な追加パッケージのみを追加し、LangChain オブジェクトを渡したり、記憶している例をコピーしたりしないでください。
• キュー、テナント管理、アーティファクトストレージ、リモートサンドボックスのライフサイクル、永続的なドメイン状態、デプロイ、外部副作用からの復旧は、アプリケーションサービスに保持します。
• SubAgents または DynamicWorkflow を選択する前に、オーケストレーションをモデル制御の委任、固定されたアプリケーションワークフロー、バックグラウンドワーカーのいずれかに分類します。固定された順序付けとワーカーキューはアプリケーションコードに保持します。
• 公開されている Pydantic AI のプリミティブで必要な汎用ランタイムセマンティクスを正しく実装できない場合は、Harness でランタイムを再作成するのではなく、コアプリミティブを提案します。

直接相当するものがない場合は、「未対応」と述べるだけで終わらせないでください。元の契約と影響を明示したうえで、既存の組み合わせ、限定的なアダプターまたはアプリケーションサービス、公開プリミティブを使った新しい Harness 機能、Pydantic AI のコア変更のいずれかを推奨します。選択肢によって動作、アーキテクチャ、公開 API、スコープが大きく変わる場合は、選択する前に確認を求め、推奨する選択肢とその残存リスクを明示します。

移行と検証

1. 既存のアプリケーション境界の内側で、型付き依存関係、1 つのツールファミリー、出力、代表的なリクエストを含む垂直スライスを 1 つ移植します。
2. 呼び出し元が移行する間は、小規模なアダプターを使って、元のリクエスト、結果、エラー、イベント、継続の形式を維持します。
3. 次の機能に拡張する前に、既存のテストスイートと、対象を絞った特性評価、同等性、評価のチェックを一緒に実行します。ターゲットが使用するのと同じインタープリターとインストール済みチェックアウトで、サポート対象の Agent 境界を検証します。別の環境で得た結果は受け入れないでください。ローカルのコーディングエージェントとの組み合わせが役立つ場合に限り、Tested Composition を読みます。
4. 例を公開したり、移行完了を主張したりする前に、Validation and Cutover を読みます。単純なスライスでは、該当するチェックのみを実施します。
5. 対象範囲内の各契約について、回帰テスト済み、合意のうえ意図的に変更済み、または明示的に該当なしとなった場合にのみ切り替えます。それ以外はすべて未検証として報告します。

検証内容は、観察された契約に合わせます。ステートレスなスライスであれば、対象を絞った特性評価テストと同等性テストで十分です。永続化、承認、並行処理、ストリーミング、外部副作用には、台帳と、該当する再起動および冪等性のチェックが必要です。