Why the OpenAI Agents SDK keeps Agent, Handoff, and Runner as its only three primitives

Flashcard·Easy·4.0 · 0·~30s·Asked atOpenAI Anthropic Microsoft

Attempt it

Larger agent frameworks ship dozens of abstractions (graph, node, edge, state, reducer, memory, manager, executor, planner) because they want to cover every topology and every coordination pattern. That gives you power and a learning curve.

The Agents SDK bets that 80 percent of production multi-agent workloads are 'a few agents that hand off to each other,' and that the framework's job is to make that case beautiful and stay out of the way. Agent is the persona plus tools unit, Handoff is the peer transfer primitive baked as a tool call, Runner is the loop that runs an agent and executes the tool and handoff calls until termination. Anything beyond that (parallel fan-out, state machines, durable resume) you build yourself or use a different framework. The smaller surface means lower onboarding cost and fewer ways to assemble the system wrong; the trade is less out of the box power.

Your answer

**The OpenAI Agents SDK** is the production successor to the experimental Swarm. It ships three primitives. - **Agent.** A system prompt plus a tool list plus a list of other agents it can hand off to. That is the unit of work. - **Handoff.** A typed transfer of control from one agent to another, implemented under the hood as a tool call that the runtime intercepts and uses to swap the active agent. - **Runner.** The loop. It runs the current agent's model, executes any tool calls or handoffs the model emitted, and continues until the agent stops calling tools. **Why so small?** Larger frameworks (LangGraph, AutoGen 0.4, CrewAI) ship many abstractions because they cover every topology. That gives power and adds a learning curve and many ways to wire things wrong. The Agents SDK bets that most production multi-agent workloads are a few agents handing off to each other. For that case, three primitives are enough and anything more is overhead. The trade is honest. Parallel fan-out, durable resume, state-machine topologies, and structured branching are not in the box. You build them yourself, or you pick a different framework. The smaller surface area means lower onboarding cost and fewer chances to assemble the system the wrong way.

**The Agents SDK makes a deliberate bet that most production multi-agent workloads are 'a few agents that hand off to each other', and that the framework's job is to make that case beautiful and stay out of the way.** **The three primitives.** `Agent` packages a persona (system prompt), a tool surface (functions, MCP tools), and a list of `Handoff` targets (other agents the agent is allowed to transfer to). `Handoff` is a typed peer transfer implemented as a tool call the runtime intercepts; the calling agent stops, the target agent starts with the transferred context. `Runner` is the loop. It calls the current agent's model, executes tool calls and handoff calls in order, and continues until the agent stops calling tools or a stop condition fires. **Why this shape.** Larger frameworks ship dozens of abstractions (StateGraph, nodes, edges, reducers, memory backends, managers, executors, planners) because they aim to cover every coordination pattern. That is power and a learning curve. The Agents SDK bets the 80 percent case is small enough to design for directly, and that beating the larger frameworks on that case is more valuable than matching their feature coverage. **What you give up.** Parallel worker fan-out, typed shared state with reducers, durable checkpointers with crash-safe resume, complex routing predicates, hierarchical supervisors, and any topology that does not reduce to 'one agent at a time with peer handoffs'. You can build these yourself with the SDK as building blocks, or you can use LangGraph or AutoGen 0.4 where they are first-class. **Why this is the right call for the workload.** Onboarding cost is lower (three primitives), system shapes are harder to mis-assemble (fewer ways to wire it), and the agent-handoff idiom maps directly to how teams actually decompose work. The minimal API is a thesis about which abstractions are worth carrying, not a sign of immaturity.

Quick reference

TL;DR

Three primitives cover the 'a few agents that hand off to each other' case beautifully and stay out of the way; anything beyond it you build yourself or pick a different framework.

Memory aid

Easy to grasp

Imagine the kitchen aisle. Some gadget brands sell you 40 different specialised tools (an avocado slicer, a strawberry huller, a banana peeler). Others sell you a really good knife and trust you with the rest. The Agents SDK is the really good knife brand. It says: most agent work is one agent doing the job until it hands the task to a teammate; we will make that one motion clean and let you bring your own kitchen for everything else. The trade is honest. You give up shelves of specialised gadgets in exchange for fewer ways to cut yourself.

Key concepts

Multi-Agent Systems

Detailed answer & concept explanation

~6 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.

3 to 5 min: name the three primitives, explain the workload bet, contrast with LangGraph and AutoGen 0.4 surface areas, name when each framework wins.

Code example

python

from agents import Agent, Runner

billing = Agent(name="billing",
    instructions="Handle billing questions.",
    tools=[lookup_invoice, issue_refund])

tech = Agent(name="tech",
    instructions="Handle technical issues.",
    tools=[search_kb, escalate_to_oncall])

triage = Agent(name="triage",
    instructions="Route the user to the right specialist.",
    handoffs=[billing, tech])

result = Runner.run_sync(triage, "My invoice looks wrong")
print(result.final_output)

Real-world examples

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

OpenAI's own documentation example builds a triage agent that hands off to billing, refund, and tech-support specialists.
Klarna and Stripe-style customer-support routing fits the agent plus handoff pattern cleanly.
Hugging Face's smolagents adopted a similar peer-handoff idiom via ManagedAgent wrappers.
LangGraph offers create_swarm as the corresponding shape on its typed state graph runtime.
Anthropic's published agent design guidance recommends the handoff as tool call pattern as a portable production idiom.

Interviewer follow-ups

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

QHow would you add structured shared state across multiple agents in the SDK?

QWhat is the safety story for peer handoffs in the SDK?

QHow does the SDK compare to LangGraph's create_swarm prebuilt?

Don't say this

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

Most common mistake

Expecting the SDK to cover parallel fan-out, durable resume, or graph topologies. It explicitly does not; that is the design centre, not a gap.

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.