# Practical and Useful Patterns for OpenAI Agent SDK 🌍 When handing off between agents, wouldn't it be great to pass structured reasons and metadata along? Handoff inputs and on_handoff let you transfer context-rich data for seamless agent transitions. 📌 Title: Handoffs – Handoff inputs 🔗 URL: 🧩 Overview Handoff inputs allow the model to generate structured data (via a Pydantic model) that gets passed to the target agent during a handoff. Combined with the `on_handoff` callback, you can log escalation reasons, prefetch data the target agent needs, and inject additional context — all before the target agent starts processing. 🛠 Usage Define a Pydantic model `EscalationData(BaseModel)` with `reason: str`, `priority: str = "normal"`, and `customer_tier: str = "standard"` as structured handoff data. The `on_escalation(ctx: RunContext, input_data: EscalationData)` callback logs `input_data.reason` and `input_data.priority`, prefetches customer data using `ctx.context["customer_id"]`, and stores it in `ctx.context["customer_data"]`. Define `Agent(name="escalation", instructions="...")` as the escalation target and `Agent(name="triage", handoffs=[Handoff(agent=escalation_agent, input_type=EscalationData, on_handoff=on_escalation, handoff_description="Complex inquiries or urgent cases requiring escalation")])` as the triage agent. Execute with `await input="I was double-charged. I need this resolved immediately.", context={"customer_id": "C-12345"})`. 🏗 Practical Patterns **Structured Escalation Reasons** Define handoff reasons as typed Pydantic models like `EscalationData(reason, priority)`. Instead of free-text reasoning buried in conversation history, you get structured data that's easy to log, analyze, and act on programmatically. **Data Prefetching in on_handoff** Use the `on_handoff` callback to fetch data from databases or APIs that the target agent will need. This eliminates an extra tool-call round-trip after handoff, reducing latency. The target agent starts with all the context it needs. **Metadata Transfer** Pass `{"reason": "duplicate_charge", "priority": "high"}` to a refund agent so it can make policy decisions based on structured metadata rather than inferring from conversation history. More accurate, more reliable. **Audit Logging** Record handoff reasons, timing, and priority in `on_handoff` for audit trails. This data powers SLA dashboards and escalation trend analysis in customer support operations. 💡 Use Cases 🔄 Customer support escalation with structured reason and priority 💳 Refund processing handoffs with explicit cause (duplicate charge / defective item / cancellation) 📊 Escalation analytics via on_handoff logging to dashboards ⚡ Reduced target agent latency through on_handoff data prefetching ⚠️ Caveats - Too many required fields in `input_type` makes it harder for the model to generate accurate data. Keep required fields minimal and use defaults for optional ones. - Exceptions in `on_handoff` will fail the entire handoff. Wrap external API calls in try-except with fallback logic. - `on_handoff` runs synchronously. Heavy processing increases handoff latency — keep it lightweight. - Without `input_type`, the `on_handoff` callback does not receive an `input_data` argument. ✨ Use handoff inputs to pass structured context between agents and make your multi-agent transitions seamless! #OpenAIAgentSDK# #AIAgent#