migrating-claude-agent-sdk-to-pydantic-ai

Claude Agent SDK から Pydantic AI への移行

Claude Code のプロセスや API の形ではなく、観測可能な動作を維持してください。最小限の完全な呼び出し経路を移行し、アプリケーションのインフラストラクチャはそのまま維持してください。

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

1. リポジトリの指示、依存関係、テスト、ランタイムのエントリーポイントを確認します。インストールされている Claude Agent SDK、同梱の Claude Code CLI、Pydantic AI、Harness の各バージョンを記録します。
2. query() または ClaudeSDKClient から、プロンプト、ツール、イベント、結果、状態、永続化、承認、呼び出し元が利用する副作用まで、実際のリクエストを1つ追跡します。対象を絞ったベースラインまたは特性テストを用意します。
3. 次のソース契約が存在する場合は、個別に切り分けます。
   • 新しい query() 呼び出し、稼働中の ClaudeSDKClient による継続、ディスク／外部ストアからの再開、トランスクリプトの分岐、ファイルの巻き戻し
   • ツールの利用可否、自動承認、ポリシーコールバック、OS／コンテナーによる隔離
   • 完了メッセージ、生のトークン差分、ライフサイクルイベント、最終結果
   • 会話履歴、ワークフローチェックポイント、モデル所有の計画、長期メモリ、ワークスペースの状態
   • モデル主導のサブエージェントと、アプリケーション所有のループ、キュー、再試行、スケジューラー
4. 観測した各契約、その所有者、意味上の違い、実行可能な証明を記録します。観測されていない Claude Code の機能は移行対象に含めません。

検出されたソース機能については、Research and concept mapping を参照してください。実装前に Verification and cutover を確認してください。

最小限の移行先を選ぶ

• Core： モデル呼び出し、エージェントループ、型付き依存関係、ツール、出力、正規化されたメッセージ、汎用フック、ストリーミング、MCP、承認、使用量制限、計装、永続ランタイムとの統合には pydantic_ai.Agent を使用します。
• Harness： コーディング用ファイルシステム／シェルツール、リポジトリコンテキスト、計画、メモリ、モデル主導のサブエージェント、モデルに依存しないコンテキスト管理、Agent Skills など、観測された再利用可能なポリシーに限り pydantic-ai-harness を追加します。Harness の機能はコアのエージェントループと組み合わせて利用します。Harness は第2のランタイムではありません。
• Application： 要求された範囲に含まれない限り、認証、サービスクライアント、データベース、キュー、スケジューラー、デプロイ、製品状態、セッション検索、テナントポリシー、既存のトランスポートは維持します。
• Gap： サポートされている公開インターフェースでは維持できない動作を明示し、その影響を説明して、範囲を限定したアダプターをテストします。違いを隠すためだけに、見かけだけの ClaudeSDKClient を作ったり、Claude のトランスクリプトファイルをエミュレートしたりしないでください。

通常の移行では、再利用可能な Agent を1つ用意し、アプリケーションサービスを型付き依存関係として渡し、通常の Pydantic AI ツールを使います。呼び出し元が構造化データを想定している場合は型付き出力を使い、後続のターンでコンテキストが必要な場合は result.all_messages() をアプリケーション側で保存します。呼び出し元が移行できるよう、既存の公開リクエスト／レスポンス／イベント境界は小さなアダプターで維持してください。

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

• Claude Agent SDK の allowed_tools は自動承認を意味し、利用可能なツールの限定や隔離を意味するものではありません。利用可否、承認、ポリシー、サンドボックス化はそれぞれ独立して対応付けてください。
• Pydantic AI の message_history は、正規化されたメッセージを明示的に再生します。conversation_id は実行を関連付けるものであり、Claude のセッション再開トークンではありません。ID の名前を変えるだけではなく、再起動とフォークの動作を検証してください。
• Pydantic AI の承認では、検証済みのツール呼び出しが保留されます。認証済みの認可、ID、監査は引き続きアプリケーションが担い、承認前に保護対象の処理を実行してはなりません。
• フックは、発火点、入力、順序、変更、ブロック、エラー時の動作に基づいて対応付けてください。Claude のフックマッチャーは並行して実行されることがあります。Pydantic AI は before_* フックを機能の順序で、after_* フックを逆順で実行し、wrap_* フックは最初の機能が最外部になるようにネストします。フックから見える契約を変更する場合は、ゴールデントレースを必須としてください。
• ストリーミングでの利用者の意図を対応付けてください。Pydantic AI の出力ストリーミング、実行イベントストリーミング、グラフの反復処理はそれぞれ異なるインターフェイスであり、いずれも Claude SDK のメッセージ分類を保証しません。
• Harness の SubAgents は、モデル主導の委任に限って使用してください。決定論的なオーケストレーションと検証ループはアプリケーションコードに残してください。
• Harness の Skills は、必要に応じて SKILL.md の指示を提供します。Claude Code のスキルやプラグインの読み込みと同等だと仮定せず、リソースとスクリプトを個別に検証してください。
• Harness のコマンド制御はベストエフォートのポリシーであり、OS のセキュリティ境界ではありません。信頼できない実行には、適合する場合は ModalSandbox を使用するか、アプリケーションが管理するコンテナ、VM、サンドボックスによる隔離を維持してください。
• ファイルの巻き戻し、Claude Code のプロンプトプリセット、プラグインのパッケージ化、生のストリームイベントの識別性、動的な MCP 制御は、移行する呼び出し元が実際に必要としており、公開された移行先の接続点が実証されていない限り、未対応の機能です。

縦方向のスライスを1つ実装して検証する

1. サポート対象の呼び出し元との境界を維持し、エージェントが所有する内部実装のみを置き換えてください。
2. コア機能のみから始めてください。ソースの契約で必要になった場合に限り、必要最小限の Harness 機能を追加してください。
3. その境界で、入力、型付き出力、エラー、イベント順序、ツールの引数と結果、承認判断、ターンをまたぐ状態、副作用をテストしてください。オフラインテストでは決定論的なモデルと偽のアプリケーションサービスを使用し、プロバイダーの動作自体が契約である場合に限り、対象を絞った記録済みテストまたはライブテストを追加してください。
4. 再開、耐久性、承認、並行ツール、外部への副作用については、ソースが保証する正確な境界で、中断と再起動、系譜、認可、冪等性をテストしてください。
5. 保持する経路が claude-agent-sdk をインポートせず、Claude Code を起動せず、そのトランスクリプトを読み込まず、そのイベント型や結果型も利用しなくなってから、初めて claude-agent-sdk を削除してください。

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

完了

検証と切り替え に記載されている完了基準を適用してください。偽実装、記録、ライブプロバイダーから得た証拠は、正確に区別して明記してください。