migrating-agno-to-pydantic-ai

Agno から Pydantic AI への移行

Agno のオブジェクトモデルではなく、観察可能な動作を維持してください。最小限の完全な呼び出し経路を移行し、アプリケーションのインフラストラクチャはそのまま維持してください。

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

1. リポジトリの指示、依存関係、テスト、実行時のエントリーポイントを確認します。インストール済みの Agno、Pydantic AI、Harness のバージョンを記録します。
2. Agent.run() / arun()、Team.run() / arun()、Workflow、または AgentOS エンドポイントから、指示、モデルおよびツールの呼び出し、フック、セッションの読み込み、メモリーやナレッジの取得、イベント、結果、状態、副作用まで、実際のリクエストを1つ追跡します。対象を絞ったベースラインまたは特性テストを用意します。
3. 該当する場合は、次のソース契約を切り分けます。
   • 信頼された依存関係、モデルが選択するツール入力、セッション状態、ワークフロー状態；
   • 会話履歴、セッションの要約、ユーザーメモリー、ナレッジの取得、ワークフローのチェックポイント、モデルが所有する計画；
   • 最終コンテンツ、構造化出力、トークン差分、実行イベント、一時停止、終了状態；
   • 確認、ユーザー入力、外部ツールの実行、認証済みの認可、プロセス分離；
   • チームの委任、決定論的なワークフロー制御、AgentOS のトランスポート、キュー、デプロイ。
4. 観察された各契約、その所有者、意味上の違い、実行可能な検証方法を記録します。使用されていない Agno の機能は移行対象ではありません。

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

最小限の移行先を選ぶ

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

通常の移行では、再利用可能な Agent を1つ用意し、アプリケーションのサービスを型付き依存関係として提供し、型付きツールと出力を使用します。また、後続のターンに備えて、result.all_messages() をシリアライズし、アプリケーション側で保存します。既存の HTTP、ジョブ、UI の境界は、小さなアダプターと現在のフィールド名を使って維持します。

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

• Agno の dependencies、user_id、session_id、および認証済み ID は、信頼できるランタイムコンテキストであり、モデル引数ではありません。型付き依存関係に格納し、ストレージや副作用の認可はアプリケーションコードで行います。
• Agno のセッションには、それぞれ別の所有者が含まれます。チャット履歴はシリアライズされた Pydantic AI メッセージに対応付け、変更可能な製品／セッション状態はアプリケーションストアに保持し、要約、ユーザーメモリ、ナレッジ検索、ワークフローチェックポイント、Harness の Memory はそれぞれ別の契約として扱います。レコード変換、読み取りスルーアダプター、または新規開始のいずれかを、許容される変更として選択し、テストします。
• Team の実際の委譲モードと、呼び出し元から見えるメンバーイベントを確認します。モデル主導で分離されたタスク委譲にのみ、Harness の SubAgents を使用します。同等性が証明されない限り、ルーティング、ブロードキャスト、決定論的なファンアウト、共有コンテキストでの協調、集約、リトライは、アプリケーションコードまたはグラフコードに残します。
• Agno の Workflow のステップ、条件、ルーター、ループ、並列処理の結合は、決定論的なままにします。これらをエージェントのプロンプトに移してはいけません。グラフ状態だけでは、チェックポイントは永続化されません。
• Agno の確認、一部のユーザー入力、外部実行に伴う一時停止では、ペイロードと所有者がそれぞれ異なります。コアの延期ツールでは、保留中のモデルツール呼び出しを保持できますが、ID、認可、UI、監査、永続化、相関付け、冪等性は引き続きアプリケーションが担います。ソースの一時停止状態が再起動後も維持される場合は、再起動後も維持されることを証明します。
• 前後のフック、ツールフック、ガードレールは、発火タイミング、変更内容、短絡動作、順序、リトライ、ストリーミングでの可視性、永続化に基づいて対応付けます。フック名が似ているだけでは、ライフサイクルの同等性は証明されません。
• ストリーミングの利用者の意図を対応付けます。Pydantic AI の出力ストリーミング、実行イベントのストリーミング、機能イベント、UI アダプター、グラフの反復処理は、それぞれ異なるインターフェースです。いずれも Agno の実行イベント分類や再開カーソルを保証するものではありません。
• Agno の Skills は、指示、参照資料、スクリプトを公開できます。Harness の Skills は SKILL.md の指示をオンデマンドで読み込みますが、同梱リソースの読み込みやスクリプトの実行は行いません。観察された信頼できる動作に必要な場合に限り、明示的な FileSystem、Shell、またはアプリケーションツールを追加します。
• AgentOS のルーティング、認証、セッション API、テレメトリ、コントロールプレーン、データベース選択、デプロイは、製品インフラストラクチャです。エージェントの移植を AgentOS の移植とみなさず、それぞれを意図的に維持するか置き換えます。
• ツールの許可リスト、パスチェック、ガードレールはポリシーであり、OS の隔離ではありません。信頼できない実行が対象に含まれる場合は、コンテナー、VM、またはクラウドサンドボックスを使用します。

垂直スライスを1つ実装し、動作を証明する

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

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

完了

検証と切り替えの完了基準を適用します。偽のデータ、記録、ライブプロバイダー、運用テストから得た証拠は、それぞれ正確に区別して表示します。