migrating-openai-agents-sdk-to-pydantic-ai

OpenAI Agents SDK から Pydantic AI への移行

OpenAI Agents SDK のオブジェクト形状ではなく、呼び出し元から見える動作を維持してください。最小限の完全なランタイムスライスを移行し、アプリケーションのインフラストラクチャはそのまま残します。

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

1. リポジトリの指示、依存関係ファイル、テスト、ランタイムのエントリーポイントを読みます。インストールされている openai-agents、Pydantic AI、Harness のバージョンを記録します。
2. 代表的な Runner.run、run_sync、または run_streamed の呼び出しを、指示、コンテキスト、モデル設定、ツール、ハンドオフ、ガードレール、セッション状態、承認、イベント、トレーシング、公開される結果まで追跡します。final_output、last_agent、new_items、to_input_list()、割り込み、ストリーミングイベントを使用する呼び出し元を調べます。
3. 既存のアプリケーション境界で決定論的なベースラインを確立します。現在の実行経路で使われる動作だけを記録します。
4. 設計に着手する前に、スライスを分類します。
   • 通常のエージェント： 型付き依存関係、ツール、出力を備えた、再利用可能な Pydantic AI Agent を使用します。
   • スペシャリストを持つマネージャー： 最終応答を誰が担うべきかに応じて、明示的なアプリケーションオーケストレーション、エージェントツール、または Harness SubAgents を使用します。
   • ハンドオフワークフロー： まず、アクティブなエージェント、その指示、次のターンの担当者を変更することが、外部から観測可能かどうかを判断します。ネストされたエージェントツールはハンドオフではありません。
   • サンドボックスまたはコーディングエージェント： Harness Coder とそのコンポーネント機能を評価します。実行環境は別途選択してください。シェルの許可リストは隔離ではありません。
   • リアルタイムまたは音声経路： Pydantic AI のリアルタイムエージェントを使用する別個の移行スライスとして、トランスポート、割り込み、音声、ライブセッションの動作を扱います。
   • プロダクトのランタイム： 明示的に対象範囲に含めない限り、認証、ストレージ、キュー、デプロイ、サービス連携は維持します。
5. 特性テストを追加または維持し、既存の公開境界の背後で垂直スライスを1つ移行して、元のテストと焦点を絞った同等性テストを実行します。

見つかったソース機能については、概念の対応付けをお読みください。永続化、ハンドオフ、承認、ストリーミング、セキュリティ、本番トラフィックを変更する前、および移行完了を宣言したり openai-agents を削除したりする前に、検証と切り替えをお読みください。

セマンティックゲートで止める

• コンテキスト： RunContextWrapper.context は信頼できるアプリケーション状態であり、通常は型付きの deps になります。モデルが生成したハンドオフフィールドやツール引数は依存関係ではありません。
• ハンドオフ： OpenAI のハンドオフは、1 回の実行内でアクティブなエージェントを切り替え、継続のために last_agent を公開します。Pydantic AI のエージェント委譲は通常、ツール呼び出しを通じて戻ります。明示的なアプリケーションのルーティングで転送のセマンティクスを維持するか、意図的な変更として記録してください。
• 会話状態： 手動の to_input_list() の履歴、SDK の Session ストレージ、OpenAI の conversation_id、OpenAI の previous_response_id、シリアライズされた中断状態の RunState を区別してください。Pydantic AI のメッセージ履歴、プロバイダー側の継続、Harness のステップ永続化、耐久性のある実行は、それぞれ異なる問題を解決します。
• ガードレール： どの境界をチェックするか、作業の開始前にブロックするか、失敗時の形式、置換動作、実行順序を維持してください。OpenAI の入力ガードレールはデフォルトで並列実行されることがあるため、モデルの処理やツールの副作用が始まった後にトリップワイヤーが作動する場合があります。
• 承認： OpenAI HITL はシリアライズされた RunState を再開します。同じ呼び出し中に判定結果を利用できる場合は、HandleDeferredToolCalls を使用して Pydantic AI の実行をインラインで続行してください。先に実行を終了する必要がある場合は、output_type に DeferredToolRequests を含めてから、メッセージと完全なリクエスト、またはカテゴリ、検証済み引数、メタデータを含む同等の保留アクションレコードを永続化し、その後 DeferredToolResults で再開してください。保護対象のツール内で再認可してください。承認は認可ではありません。
• ツールの完了： tool_use_behavior によって、通常のツール結果を最終結果にできます。Pydantic AI では、成功した最終アクションを出力関数または ToolOutput としてモデル化してください。ツールから成功値を持ち出すために例外をスローしないでください。
• ストリーミング： Responses API の生イベント、run-item イベント、ライフサイクルイベント、出力デルタ、最終完了は、それぞれ別の契約です。エージェントのループ全体を完了させる必要がある場合は、run(event_stream_handler=...)、run_stream_events()、または iter() を使用してください。最初に一致した出力を確定し、後続のツール呼び出しをスキップしてもソースの契約を維持できる場合に限り、run_stream() を使用してください。選択したインターフェースを公開スキーマに適合させてください。
• トレース： OpenAI のトレースと Pydantic AI の OpenTelemetry インストルメンテーションは、運用上異なる製品です。ユーザーがより広範な移行を了承しない限り、既存のテレメトリを維持してください。Pydantic AI のファーストパーティエクスペリエンスを選ぶ場合は、Logfire を推奨してください。

Pydantic AI のデフォルト

• 認証情報、認証済みの ID、クライアント、設定は型付き依存関係に保持し、モデル層より下の層で権限を適用してください。
• ワイヤー契約を維持できる場合は、構造化された最終出力に Pydantic モデルを使用してください。ソースがプレーンテキスト、構造化出力、最終ツール出力のどれを使用していたかを確認してください。
• アプリケーションが実行するツールには、コアの関数ツールと MCP ツールセットを使用してください。選択したプロバイダーが必要なツールをサポートし、観測された結果やイベントの契約を維持できる場合に限り、プロバイダー固有の機能を使用してください。
• 通常のエージェントはコア上に維持してください。ガードレール、サブエージェント、メモリ、スキル、ファイルシステム／シェルツール、プランニング、ステップ永続化、サンドボックスなど、再利用可能な機能が実際に必要な場合にのみ Harness を追加してください。
• プロバイダーの移行が範囲に含まれない限り、既存のモデル／プロバイダーの経路を維持してください。OpenAI 固有のオプションを移行する前に、インストール済みの Pydantic AI のモデル設定を確認してください。
• ソースの有効な max_turns を確認してください。省略されている場合は、SDK のデフォルト値も含めて確認します。カウント方法と失敗時の契約を検証してから、UsageLimits.request_limit でその上限を維持してください。Pydantic AI の異なるデフォルトをそのまま引き継がないでください。

完了

クリーンな環境に移行後のプロジェクトをインストールしてインポートし、依存関係ファイルが実行時の環境と一致するようにします。観測されたすべての公開契約が、実行可能なチェックによって維持されるか、影響が受け入れられたうえで意図的に変更されるか、名前が明示された外部コンポーネントの責任範囲に含まれるか、または明示的に該当しないものとして扱われたとき、このスライスは完了です。テストされていない契約は未検証であり、必須の契約が未解決の場合は切り替えを実施できません。