# OpenAI Agent SDKの便利だけど知られていない機能
🌍 ハンドオフの理由や追加情報を、会話テキストだけで伝えようとしていませんか?
構造化入力を使えば、ハンドオフ時にPydanticモデルで型安全なメタデータを受け渡しできます。
📌 タイトル:handoff の構造化入力
🔗 URL:
🧩 概要
`handoff()` の `input_type` にPydanticの `BaseModel` を指定すると、そのスキーマがモデルにツールパラメータとして公開されます。モデルはハンドオフ時にスキーマに沿った構造化データを生成し、`on_handoff` コールバックでバリデーション済みのデータを受け取れます。これにより、ハンドオフの理由、優先度、ユーザー情報などの構造化されたメタデータを型安全に受け渡しできます。
🛠 使い方
```python
from pydantic import BaseModel
from agents import Agent, handoff
# ハンドオフ時のメタデータを定義
class EscalationData(BaseModel):
reason: str
priority: str # "high" | "medium" | "low"
customer_tier: str
# コールバックでバリデーション済みデータを受け取る
async def handle_escalation(ctx, data: EscalationData):
print(f"エスカレーション: {data.reason} (優先度: {data.priority})")
# データに基づいた処理(例: 優先キューに追加)
escalation_handoff = handoff(
agent=Agent(name="Senior Support", instructions="上級サポート担当"),
input_type=EscalationData,
on_handoff=handle_escalation,
)
triage_agent = Agent(
name="Triage",
instructions="問題を評価し、必要に応じてエスカレーションしてください。",
handoffs=[escalation_handoff],
)
```
🏗 本番システムへの組み込み方
・エスカレーションの理由と優先度を構造化して、後続処理の自動化に活用する
・`on_handoff` コールバック内でデータベースへの記録やアラート送信を行う
・Pydanticのバリデーションにより、不正なハンドオフデータを自動的に検出する
・ハンドオフメタデータを分析し、エージェントの判断品質を評価する
💡 ユースケース
🎫 カスタマーサポートのエスカレーション理由・優先度の構造化記録
🏥 医療トリアージでの症状・緊急度の型安全な受け渡し
📊 ハンドオフパターンの分析によるエージェント設計の改善
🔄 マルチステップワークフローでの中間結果の構造化伝達
⚠️ 注意点
`input_type` のスキーマが複雑すぎると、モデルが正確な構造化データを生成しにくくなります。フィールドは明確で少数に保ち、説明的なフィールド名を使いましょう。`on_handoff` コールバック内での重い処理は、エージェントの応答速度に影響する可能性があります。
✨ 構造化入力で、ハンドオフに「意図」と「文脈」を明確に乗せましょう。
#
OpenAIAgentSDK# #
AIAgent#