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

Flashcard·Easy·4.0 · 0·~30s·Asked atCopy Ai Intel Moveworks

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.

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

Concept explanation~2 min read

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

API surface area is an architectural choice. Frameworks that ship dozens of abstractions are betting that no single shape covers enough of the workload to justify a minimal API. Frameworks that ship three are betting the opposite: that one shape covers most of the workload and the win is in making that shape beautiful.

The OpenAI Agents SDK takes the second bet. It evolved from the experimental Swarm project (2024) into a production-grade SDK with deliberate minimalism: Agent, Handoff, Runner. Understanding why this choice was made tells you when to reach for it and when to pick something with a larger surface.

One-line summary: the SDK bets that most multi-agent work is a few agents handing off to each other, and that betting on that shape produces a better day to day experience than covering every topology. Everything follows from that bet.

The three primitives and what each one carries

Agent

An Agent is a system prompt plus a tool list plus a list of other agents it is allowed to hand off to. The handoff list is an ACL on transfers: an agent can only invoke handoffs to peers explicitly named in its config. This bounds the handoff graph to what you have declared, which is a real safety property compared to free-form peer chat.

Agents can be reused across workflows because they are just configuration objects. A billing agent is the same agent whether you call it from a triage agent in workflow A or directly in workflow B.

Handoff

A Handoff is a typed peer transfer. Under the hood, the SDK exposes a synthetic tool to the model named transfer_to_<agent_name> for each allowed peer. When the model calls it, the runtime intercepts the call, packages the transferred state (the conversation and any context object), and swaps the active agent.

The critical design decision is that handoff lives in the model's native action space. There is no separate side channel for transfers; they are tool calls. That means transfers show up uniformly in tracing, in token accounting, and in the model's own planning, which makes the agent's behaviour interpretable in the same lens you already use for tool use.

Runner

Runner.run (or run_sync) is the loop. It calls the current agent's model with the running conversation, parses the response, executes any tool calls and handoff calls in order, and repeats until the model emits no further tool calls (the agent decided it is done) or a max_turns cap fires. Streaming is supported with the same shape.

The loop is single active agent by design. At any moment one agent owns the turn; handoffs swap which agent owns it, but never run two in parallel. This is the architectural opinion that makes the rest of the API work.

Why a minimal API is the right choice for this workload

What you give up, and what to use instead

Where the SDK sits in the 2026 framework landscape

Situations where this technique stops working.

2–4 min · Everything important, quickly.

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

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?

Pass a context object through Runner.run that each agent's tools can read and write. It is not a reducer-backed graph, but for shared-counter, shared-cache, or running-budget patterns it is enough. For anything more structured, lift to LangGraph state.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases 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 bullets to scan on the way to the call.

What each of Agent, Handoff, and Runner is and what it does
Why Handoff being a tool call (not a side channel) matters for tracing

Primary sources. Browse if you want the original framing.