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

TL;DR

Add guardrails at handoff boundaries: validate inputs before a specialist agent acts, especially before anything irreversible. Keep handoff targets narrow.

When to use

You are seeing this: Pick the runtime before writing agent code: - Agents API: OpenAI runs the managed harness and saves progress. Use this skill when you run into "Multi-agent handoffs with the OpenAI Agents SDK: pick the runtime, then wire the loop".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.