Order the steps of one handoff in the OpenAI Agents SDK Runner loop

Order steps·Medium·4.0 · 0·~1 min·Asked atOpenAI Anthropic Microsoft

Attempt it

1Runner resumes the loop with research_agent as the active agent
2Runner intercepts the call, recognises it as a Handoff rather than a regular tool
3Runner seeds research_agent's input with the handoff payload (and optional conversation context)
4Runner ends the current agent's turn and swaps the active agent to research_agent
5The agent's model emits a tool call named transfer_to_research_agent with a structured payload
6Runner invokes the current agent with the conversation and the agent's tool set including handoff tools

The **OpenAI Agents SDK** uses a thin loop called the **Runner**. The Runner repeatedly calls the active agent until the agent emits a final answer or a handoff. The handoff flow in one cycle: 1. The Runner invokes the active agent with the current conversation and the agent's tool set, which includes any handoff tools that have been registered (`transfer_to_research_agent`, for example). 2. The agent's underlying model emits a tool call. In this case it emits `transfer_to_research_agent` with a structured payload (a brief, a question, whatever the schema says). 3. The Runner intercepts the call before executing it as a normal tool. Because the call name matches a registered Handoff, the Runner recognises it as a control-flow operation, not a regular tool. 4. The Runner ends the current agent's turn and swaps the active agent reference to `research_agent`. 5. The Runner seeds `research_agent`'s input with the handoff payload and optionally any conversation context the handoff configuration specified. 6. The Runner resumes the outer loop with `research_agent` as the active agent and goes back to step 1 on the next iteration. The whole point is that the model treats handoffs like normal tool calls (familiar API, no new primitive to learn), but the runtime treats them as control flow. That separation is what makes the SDK feel simple to use.

**The Runner loop and the handoff mechanism are the two pieces you have to understand together.** The Runner is a thin while-loop; the handoff is a tool call the Runner intercepts. **Step 1.** The Runner invokes the current agent with the conversation and the agent's tool set. The tool set includes regular tools (search, calculator, code interpreter) and any handoff tools the developer registered. From the LLM's perspective they are indistinguishable, both are JSON-schema tool definitions. **Step 2.** The model emits a tool call. In a handoff scenario it picks the handoff tool (e.g., `transfer_to_research_agent`) and produces a structured payload matching that tool's schema (a brief, a question, an objective). **Step 3.** The Runner reads the tool call and checks the name against its registry of handoffs. A match means this is a control-flow operation, not a function call that returns a value. **Step 4.** The Runner ends the current agent's turn cleanly (records the tool call in the trace, no tool result emitted) and swaps the `current_agent` reference to the target agent. **Step 5.** The Runner seeds the new agent's input with the handoff payload. The handoff configuration determines whether the prior conversation is also forwarded; the default is a structured brief only, which is the cleanest pattern for avoiding role bleed. **Step 6.** The Runner returns to the top of the loop with the new agent active. Subsequent iterations run the new agent until it either emits a final answer, calls another handoff, or hits a termination condition. The elegance: from the model's perspective there is no new primitive; from the runtime's perspective there is a clean control-flow swap. That is why the Agents SDK is the minimal-API peer-handoff runtime and why it became the canonical reference for handoff as tool call in 2026.

Quick reference

TL;DR

Runner invokes the agent, the model emits a handoff tool call, the Runner intercepts and swaps active agents, then seeds the new agent's input and continues the loop.

Memory aid

Easy to grasp

Think of a customer-service desk. A representative is helping you, sees that your problem is really a billing question, and writes a referral card to the billing specialist. The receptionist takes the card, calls the billing specialist over, hands them the card so they know what you came in for, and the conversation continues with the new specialist. The model is the rep, the Runner is the receptionist, the referral card is the handoff payload, and the swap is invisible to you. The whole point is that the rep does not have to walk you over personally; the system handles that part.

Key concepts

Multi-Agent Systems

Detailed answer & concept explanation

~5 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Quick scan · 2–4 min

Everything important, quickly.

5 to 7 min: the six-step cycle in order + why each step matters + how interception distinguishes handoffs from tools + payload seeding behaviour + design wins of handoff as tool call.

Real-world examples

Real products, models, and research that use this idea.

OpenAI's published Agents SDK tutorials walk through this exact six-step flow for the canonical triage / specialist / escalation pattern.
Customer-support agent demos route a query through a triage agent that hands off to billing, technical, or returns specialists via this mechanism.
OpenAI's TypeScript Agents SDK mirrors the same Runner / Handoff design as the Python version, with the same six-step cycle.
Anthropic's published agent traces show similar handoff semantics in their Claude-based tooling, even though the implementation differs.
LangGraph's swarm prebuilt implements the same mechanism with conditional edges and a designated handoff tool registry.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QWhat happens if the model emits a handoff call to a target that is not in the registered handoffs?

QHow would you let the second agent hand control back to the first agent after completing its subtask?

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Confusing a handoff with a tool call. From the model's perspective they look identical (both are tool calls), but the Runner treats handoffs as a control-flow primitive that swaps the active agent, not as a function that returns a value.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.