# OpenAI Agent SDKの便利で実践的な使い方 🌍 エージェント間の引き継ぎで、理由やメタデータも一緒に渡したいことはありませんか？ Handoff inputsとon_handoffを使えば、構造化されたデータとともにスムーズな引き継ぎが実現できます。 📌 タイトル：Handoffs – Handoff inputs 🔗 URL： 🧩 概要 Handoff inputsは、handoff時にモデルが生成する構造化データを引き継ぎ先エージェントに渡す仕組みです。`on_handoff`コールバックと組み合わせることで、引き継ぎ理由のログ記録、メタデータの事前取得、引き継ぎ先エージェントへのコンテキスト注入が可能になります。 🛠 使い方 Pydanticモデル `EscalationData(BaseModel)` で `reason: str`, `priority: str = "normal"`, `customer_tier: str = "standard"` を定義し、handoff時の構造化データとします。`on_escalation(ctx: RunContext, input_data: EscalationData)` コールバックでは、`input_data.reason` や `input_data.priority` をログ出力し、`ctx.context["customer_id"]` から顧客データを事前取得して `ctx.context["customer_data"]` に格納します。エスカレーション先の `Agent(name="escalation", instructions="...")` と、トリアージ用の `Agent(name="triage", handoffs=[Handoff(agent=escalation_agent, input_type=EscalationData, on_handoff=on_escalation, handoff_description="複雑な問い合わせや緊急対応が必要な場合")])` を定義します。`await input="二重請求されました。すぐに対応してほしいです。", context={"customer_id": "C-12345"})` で実行します。 🏗 実践的な使い方 **エスカレーション理由の構造化** `EscalationData(reason, priority)`のようにPydanticモデルで引き継ぎ理由を型安全に定義できます。モデルが自由文で理由を生成するのではなく、構造化されたデータとして受け取れるため、後続処理やログ分析が容易になります。 **on_handoffでのデータ事前取得** `on_handoff`コールバック内で、引き継ぎ先エージェントが必要とするデータをDBやAPIから事前に取得できます。これにより、引き継ぎ先エージェントが改めてデータ取得ツールを呼ぶ必要がなくなり、レイテンシを削減できます。 **メタデータの伝達** 返金エージェントに`{"reason": "duplicate_charge", "priority": "high"}`を渡すことで、返金ポリシーの判断に必要な情報を構造化された形で引き継げます。自由文の会話履歴からモデルが推測するよりも正確です。 **監査ログの記録** `on_handoff`内で引き継ぎの理由・タイミング・優先度を監査ログに記録できます。カスタマーサポートのSLA管理や、エスカレーション傾向の分析に活用できます。 💡 ユースケース 🔄 カスタマーサポートのエスカレーション（理由と優先度を構造化して引き継ぎ） 💳 返金処理への引き継ぎ（二重請求/商品不良/キャンセルなどの理由を明示） 📊 引き継ぎ理由の集計・分析（on_handoffでログ記録→ダッシュボード化） ⚡ 引き継ぎ先エージェントのレイテンシ削減（on_handoffでデータプリフェッチ） ⚠️ 注意点 - `input_type`に指定したPydanticモデルのフィールドが多すぎると、モデルが正確にデータを生成できなくなります。必須フィールドは最小限にし、オプショナルフィールドにはデフォルト値を設定してください。 - `on_handoff`内で例外が発生するとhandoff全体が失敗します。外部API呼び出しにはtry-exceptを入れ、フォールバック処理を用意してください。 - `on_handoff`は同期的に実行されます。重い処理を入れるとhandoffのレイテンシが増加するため、必要最小限の処理に留めてください。 - `input_type`を指定しない場合、`on_handoff`のコールバックは`input_data`引数を受け取りません。 ✨ Handoff inputsで構造化されたコンテキストを引き継ぎ、エージェント間の連携をスムーズにしましょう！ #OpenAIAgentSDK# #AIAgent#