Multi-agent handoffs with the OpenAI Agents SDK: pick the runtime, then wire the loop

Runtime choice, then handoffs

The steps

1. Pick the runtime before writing agent code:

   • Agents API: OpenAI runs the managed harness and saves progress. Best for long-running tasks you do not want to babysit.
   • Agents SDK: the loop runs inside your application with your tools, your storage, your approvals. Best when you need control over deployment and data.
   • Responses API: you own the loop entirely. Best when you are building custom orchestration or the agent is thin.
2. With the SDK, define each agent with its instructions, tools, and handoff targets. A handoff is a typed delegation: the triage agent hands the billing question to the billing agent with context attached, not a free-text forward.
3. Keep handoff targets narrow. An agent that can hand off to twelve others will hand off wrong; three to five well-described specialists beat a directory.
4. Let the runner own the loop: it runs the agent, executes tools, follows handoffs, and returns when the task completes. Do not reimplement turn-taking around it.
5. Persist session state in your storage between tasks. SDK sessions are yours to save and restore; a dropped session that loses the whole conversation is a bug in your persistence, not the SDK.
6. Add guardrails at handoff boundaries: validate inputs before a specialist agent acts, especially before anything irreversible. The handoff is the cheapest place to catch a misrouted task.

The trap

One mega-agent with every tool, or handoffs with no context attached. The mega-agent confuses tools; the context-free handoff makes the specialist re-ask everything the triage agent already learned.

Checklist

• Runtime chosen deliberately (Agents API vs SDK vs Responses).
• Handoff graph is small and typed, with context passed along.
• The runner owns the loop; no custom turn-taking wrapper.
• Session persistence implemented and tested across restarts.
• Guardrails sit at handoff boundaries before irreversible actions.

OpenAI's agents guide compares the three runtimes and documents that the SDK runner handles the agent loop and handoffs. Verified live at https://developers.openai.com/api/docs/guides/agents.