Handoff in the OpenAI Agents SDK: How One Agent Transfers a Conversation

In multi-agent architectures, the most critical piece is often not how smart any single agent is, but how they hand tasks off to each other. The OpenAI Agents SDK's answer is the handoff — letting one agent pass control of the conversation to another.

The Essence of Handoff: To the Model, It's Just a Tool

The most counterintuitive aspect of this mechanism is that to the model, a handoff is just an ordinary tool call.

Imagine a customer service scenario: a user requests a refund, and the triage agent doesn't need to handle the refund itself — it just needs to call a tool named transfer_to_refund_agent. That's what the model sees: the tool. When the model decides to call it, the handoff happens.

This means you don't need to teach the model a whole new "handoff protocol." The model is still doing what it does best — choosing the right tool to call at the right moment — except this time, the result of the tool call is that a different agent continues the conversation.

Tool Calling / Function Calling is a foundational capability of large models: developers declare a set of available tools in a request (names, parameter schemas, purpose descriptions), and the model can, when generating a response, choose to output a structured call request. An external program executes it and feeds the result back to the model, which then continues generating. It's essentially a protocol that lets the model express intent while code executes the action — the model itself doesn't actually perform anything.

Understanding this makes it clear why modeling handoff as a tool call is so natural: the SDK simply defines "switching to another agent" as yet another action the model can request, reusing the existing call-and-fill-back loop. The model doesn't need to understand the abstract concept of an "agent." It just needs to pick out a tool named transfer from among various tools and provide the call parameters. The actual transfer of control happens on the SDK side: upon receiving this particular call request, it doesn't execute an ordinary function — it switches the currently active agent.

Configuration: The handoffs Parameter and the transfer Tool

In the OpenAI Agents SDK, which agents an agent can hand off to is declared via the handoffs parameter.

You list the target agents allowed for handoff in this parameter, and the SDK generates a corresponding tool for each target, with a transfer name.

This design brings two direct benefits:

• Declarative configuration: The handoff relationships live in the code rather than being scattered throughout prompts, improving both readability and maintainability.
• Model-friendly: Target agents are exposed as tools, so the model can perform the handoff using its existing tool-calling ability without extra reasoning overhead.

Declarative vs. imperative describes two common configuration approaches. The imperative style requires describing step-by-step in prompts or flow code "what to do under what conditions"; the declarative style only describes "what relationships and targets exist," leaving the specific timing of triggering to the model's judgment.

The handoffs parameter belongs to the latter: you only declare whom an agent can hand off to, and the SDK automatically generates the corresponding transfer tools and their descriptions. As for when to call them, the model decides based on the current conversation content. The cost of this approach is coarser control granularity — you can't precisely specify "only after the Nth turn can a handoff occur." The benefit is centralized configuration that doesn't easily break as prompts change. If you do need to insert validation logic (such as permission checks or logging) before or after a handoff, you can use the callback hooks the SDK provides to execute custom code when a handoff occurs.

Context Passing: Full History by Default, Trimmed by Input Filters

After a handoff occurs, the newly taking-over agent by default sees the complete prior conversation history. This default matches intuition in most scenarios — the refund agent certainly needs to know what the user said earlier.

But when the context is too long, or contains sensitive information, or when the new agent only needs partial information, passing everything becomes a burden. The SDK provides an input filter that lets you decide what the new agent actually receives. This is also a key control point for the question "who continues the conversation after a handoff": who the handoff target is and what it sees are two things that can be configured separately.

In practice, the trade-off is:

• Full history gives the new agent a more complete understanding, but costs more tokens and may introduce irrelevant noise;
• Filtered input is more focused and cheaper, but requires you to judge what information is actually necessary for the next agent.

Context here refers to the sequence of messages an agent carries when making a request to the model, typically including the system prompt, all prior user and assistant messages, and the requests and results of tool calls. It's both the basis for the model's judgment and the primary source of token consumption — the longer the conversation, the more content each request carries, and the higher the cost and latency.

It's worth noting that in multi-agent systems there are two types of state that are easy to confuse: first, conversation history, i.e., the user-visible message stream, which after a handoff is by default passed in full; second, shared application-side state, such as user IDs, order numbers, and results of queries already executed. This kind of data is typically shared across agents through a context object provided by the SDK, and doesn't rely on message history for transmission. When designing responsibility boundaries, distinguishing "what information should go into the conversation history" from "what information should live in shared context" can significantly reduce unnecessary message bloat.

What This Design Tells Us

Modeling handoff as a tool call is a rather pragmatic choice by the OpenAI Agents SDK. It reuses a capability the model has already been well-trained on (tool selection) rather than requiring the model to learn a new collaboration semantics. For developers, the complexity of multi-agent systems thus shifts from "how to make the model understand handoffs" to "how to design clear responsibility boundaries and passing rules" — the latter being precisely where investment is more worthwhile.

If you're in the process of splitting a monolithic agent, start with clear responsibility divisions: who handles triage, who handles execution, who handles wrap-up — then use handoffs to explicitly write these relationships out.

One-line Summary

OpenAI Agents SDK models agent handoff as an ordinary tool call, using handoffs to declare relationships and input filters to control context.

Paragraph Summary

The article analyzes the design philosophy behind the handoff mechanism in the OpenAI Agents SDK. The core idea: to the model, a handoff is just calling an ordinary tool named transfer, so it doesn't need to learn a new collaboration protocol and can directly reuse its existing tool-selection ability. Developers declare via the handoffs parameter which targets an agent can hand off to, and the SDK generates a tool with a transfer name for each target, exposed to the model. After a handoff, the new agent by default inherits the full conversation history, and an input filter can trim the context actually passed. This design shifts the complexity of multi-agent systems from "making the model understand handoffs" to "designing clear responsibility boundaries and passing rules." The author suggests starting with clear divisions such as triage, execution, and wrap-up, using handoffs to explicitly express collaboration relationships.