migrating-google-adk-to-pydantic-ai

Google ADK から Pydantic AI への移行

ADK のクラスツリーではなく、呼び出し元から見える動作を維持してください。完全なリクエスト経路のうち、最小の範囲を移行し、プロダクトのインフラストラクチャはアプリケーション側に残してください。

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

1. リポジトリの指示、依存関係、テスト、実行時のエントリーポイントを確認します。インストール済みの Google ADK、Pydantic AI、オプションの pydantic-ai-harness のバージョンを記録します。
2. Runner.run_async() またはデプロイ済みエンドポイントから、ルートエージェント、指示、コラボレーションモード、モデル呼び出し、ツール、ワークフローノード、コールバック／プラグイン、セッションサービス、出力イベント、状態／アーティファクトの差分、最終レスポンスまで、実際のリクエストを1つ追跡します。その経路で使用する動作のみを記録します。
3. 移行先を選ぶ前に、以下の契約を切り分けます。
   • モデルコンテキストとして使用される Session.events
   • セッション、ユーザー、アプリケーション、呼び出しの各スコープの状態
   • 検索可能な長期メモリ
   • ワークフロー／ノードのチェックポイントと再開 ID
   • バージョン管理されたアーティファクトと外部副作用
4. 対象のスライスを分類します。
   • 通常の LlmAgent： 通常は、型付き依存関係、ツール、出力を持つ再利用可能な Agent を1つ使用します。
   • ADK のグラフまたは動的ワークフロー： 単純で決定的な制御フローは通常の非同期 Python に残します。明示的な型付きノード、分岐、またはグラフの検査が引き続き有用な場合は、pydantic_graph を使用します。
   • マルチエージェントへの委譲： Python 2.x では ADK のコラボレーション mode を確認します。1.x の sub_agents は chat 動作を使用します。chat の引き継ぎセマンティクスには、コアのマルチエージェントパターンを使用します。Harness の SubAgents は、分離されたコンテキスト、戻り値、対話、並行処理の動作が一致する場合に限り、task または single_turn に適合する可能性があります。
   • プロダクトのランタイム： 明示的に対象範囲に含まれない限り、認証、セッション／状態ストア、アーティファクトストア、キュー、トランスポート、A2A エンドポイント、評価、可観測性、デプロイはそのまま維持します。
5. 決定的な動作特性テストを追加し、既存の呼び出し元との境界の内側で、垂直スライスを1つ移行します。
6. 元のテストと対象を絞った同等性テストを実行します。検証していない動作には unverified と記載します。同じような名前であることは、同等性の根拠にはなりません。

対象スライスで使用する機能については、概念の対応関係を確認してください。ワークフロー、状態、再開、確認、コールバック／プラグイン、イベントストリーム、スキル、実行環境については、セマンティクスの差異を確認してください。ADK を削除したり、本番トラフィックを変更したりする前に、検証と切り替えを確認してください。

高リスクのゲート

• ADK の Session オブジェクトや可変状態辞書を、モデルが選択するツール引数を介して渡さないでください。認証済みの ID とサービスクライアントは型付き依存関係に格納し、製品およびワークフローの状態はアプリケーション所有のストアを通じて永続化してください。
• message_history はモデルのコンテキストを継続します。ADK のセッション状態、メモリ、アーティファクト、イベント記録、ノードのチェックポイント、呼び出しの再開に代わるものではありません。
• ADK の再開機能は記録済みのノード／ツールの結果を再生し、ツールを複数回実行する場合があります。耐久実行の設計を明示的に選択し、副作用について再起動と冪等性を検証してください。
• 会話入力、承認、認可を明確に区別してください。ツールの確認は保留中のツール承認に対応付け、ID とアクセスのチェックは信頼されたアプリケーションコード内に保持してください。
• コールバック／プラグインの順序と短絡ルールを意図的に維持してください。Pydantic AI のフックには独自の機能順序と、例外に基づくスキップ／復旧のセマンティクスがあります。見た目が似たフックを並べるだけでは同等性を保てません。
• ADK の部分イベントは状態差分を適用せずに配信され、部分イベントでない各イベントは追加時に差分が適用されます。アーティファクトの書き込みはアーティファクト操作中、現在のイベントに返されたバージョンが記録される前に行われます。呼び出し側が ADK のイベントフィールドや最終イベントの判定を利用する場合は、境界アダプターを維持し、正確なストリームと永続化の順序をテストしてください。
• Harness は、再利用可能な機能が確認された場合にのみ使用してください。通常のエージェントにはコアのみで十分です。また、コマンドの許可リストは OS のセキュリティ境界ではありません。

Pydantic AI のデフォルト

• instruction を instructions に対応付けてください。信頼された実行時データに依存する場合は、RunContext の instructions 関数を使用してください。
• 関数ツールは、型付きの Pydantic AI ツールに対応付けてください。呼び出し側が依存する範囲に限り、ツール名、説明、検証動作、エラー形式、再試行、確認、並行性を維持してください。
• 終端出力の契約が構造化されている場合は、output_schema を output_type に対応付けてください。応答形式の変更によって移行範囲が広がる場合は、既存のワイヤーアダプターを維持してください。
• ModelMessage の履歴は、ワークフローおよび製品の状態とは分けて永続化してください。新たな永続化サブシステムを追加する前に、アプリケーションの既存のストアを再利用してください。
• ローカルなライフサイクルのインターセプトには Hooks を使用してください。ツール、指示、設定、イベントも管理する再利用可能なポリシーには、カスタム機能を使用してください。
• 変更が依頼されていない限り、アクティブなモデル／プロバイダーを維持してください。プロバイダーのプレフィックスが付いた Pydantic AI のモデル ID を使用し、インストール済みの API に照らして、プロバイダー固有のツール、設定、ストリーミング、リアルタイム動作を検証してください。

完了条件

このスライスが完了となるのは、確認されたすべての呼び出し側の契約が、実行可能な証拠によって preserved と示されるか、明示的に changed として承認されるか、not applicable となった場合に限ります。unverified と blocked の契約は未完了として扱ってください。保持されるランタイム、セッション移行、デプロイコマンド、評価、互換性パスのいずれかが引き続き google-adk をインポートまたは呼び出している間は、google-adk を削除しないでください。