# 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#