Building AI Agents That Survive Production · Part 22 of 44

Handoffs: Passing Work Between Agents Without Losing State

A handoff is not a message forward. Control does not return, so anything the caller knew and did not write down is gone the moment the transfer lands. OpenAI ships a filter to cut the trace, LangChain tells you to forward exactly two messages, and Google ADK isolates each subagent in its own session branch — three frameworks admitting the same thing. What travels across a handoff, and the three things that must never.

A handoff is a transfer of ownership, not a message forward

Ask most candidates how a handoff works and you get: agent A sends the conversation to agent B. That is a message forward, and it is precisely the version that loses state. The property that makes a handoff a handoff is that control does not return. There is no stack frame waiting, no caller to fill in the gaps, so anything the first agent knew and did not write down is gone the instant the transfer lands.

That single property is why the two delegation primitives in every SDK are not interchangeable. Agent-as-tool returns, so the caller stays the author of the answer. A handoff does not, so the receiver becomes the author. OpenAI’s Agents SDK draws the line at the type level: a handoff() appears to the model as a tool named transfer_to_<agent_name>, and once it is called the run continues as the new agent. Google’s ADK, as of Python v2.0.0, made the same distinction a declared mode on the subagent — chat returns only through an explicit transfer, task runs until it calls finish_task and then returns control automatically, and single_turn returns immediately with its result and can run in parallel.

So the design question is never what should I send. It is what will the receiver need, given that nobody is coming back to supply the rest. Everything below follows from that.

Three payloads, three lifetimes

Three distinct things cross a handoff, and they do not share a lifetime. Collapsing them into one message blob is the root of most lost state.

The task is the only mandatory payload and the shortest-lived: what the receiver must do, in its own terms, now. It is prose, and that is the uncomfortable part — the task description is the entire interface between two agents, and it has no schema unless you give it one. The context is the evidence that keeps the receiver from re-deriving what is already established; it is the expensive payload and the one you have to filter. The artifacts are the durable outputs — a document, a diff, a dataset. They outlive the run, and they should travel by reference rather than by value.

Write that down as a type and a whole class of handoff bugs turns into schema violations instead of quality mysteries. OpenAI’s SDK gives you the hook directly: input_type on a handoff() makes the handoff arguments a schema the model must fill, exposed as the tool’s parameters, validated locally, and passed parsed into on_handoff. The model stops improvising the interface.

# Three payloads, three lifetimes. Make the model fill a schema, not improvise.
from typing import Literal
from pydantic import BaseModel
from agents import Agent, handoff, RunContextWrapper

class ArtifactRef(BaseModel):
    artifact_id: str            # identity, not content. the receiver fetches it.
    name: str                   # stable across versions (A2A: reuse artifact-name)
    version: int

class HandoffEnvelope(BaseModel):
    task: str                   # what to do NOW, in the receiver's terms
    purpose: Literal["continue", "verify", "route"]   # this picks the filter
    established: list[str]      # observations a tool actually produced
    open_questions: list[str]   # NOT conclusions. the receiver resolves these.
    artifacts: list[ArtifactRef] = []

async def on_handoff(ctx: RunContextWrapper[None], env: HandoffEnvelope) -> None:
    authorize(ctx, env)         # is_enabled ran BEFORE these args existed
    log_crossing(ctx, env)      # raising here means the transfer never lands

refunds = Agent(
    name="Refund Agent",
    handoff_description="Issues refunds. Owns eligibility policy.",  # routing hint
)

to_refunds = handoff(
    agent=refunds,              # model sees a tool: transfer_to_refund_agent
    input_type=HandoffEnvelope, # parsed and validated locally, then on_handoff
    on_handoff=on_handoff,
)

What the frameworks actually forward

The defaults differ, and the default is what you ship if you never look at it.

The OpenAI Agents SDK forwards the conversation and hands you input_filter, a function from HandoffInputData to HandoffInputData. Its fields are worth memorising because they name the four things you can cut independently: input_history, everything that existed before the run started; pre_handoff_items, items from earlier turns; new_items, this turn including the handoff call and its output; and input_items, an override that forwards something other than new_items while leaving new_items intact for session history. It ships one prebuilt filter, handoff_filters.remove_all_tools.

LangGraph forwards nothing by default: a handoff tool returns a Command with goto set to the target, graph set to Command.PARENT so the route resolves in the parent graph, and an explicit update. LangChain’s guidance is to forward exactly two messages — the AIMessage carrying the handoff tool call, and a ToolMessage acknowledging it with the matching tool_call_id — and to put any summary the receiver needs into that ToolMessage content. Forward the full subagent history and you pay tokens to confuse the receiver with another agent’s internal reasoning. The tool_call_id is not cosmetic: without the matching ToolMessage the history is malformed, not merely lossy.

ADK’s answer is isolation by construction. A task or single-turn agent operates in its own isolated session branch, and parallel peers cannot see what each other is doing; the parent receives the collected results. Three philosophies — forward and filter, construct and choose, isolate and collect — and all three are conceding the same point. The full trace is the wrong default.

# Same boundary, three defaults.

# 1. OPENAI AGENTS SDK - forwards the conversation; you cut it with input_filter.
from agents.extensions import handoff_filters

def continuation_filter(data):            # HandoffInputData -> HandoffInputData
    data = handoff_filters.remove_all_tools(data)   # structured tool items only
    return data.clone(
        input_history=(),                 # pre-run history: never asked for
        pre_handoff_items=compress(data.pre_handoff_items),
        input_items=(summary_item(data),),# forward THIS; new_items stays intact
    )

h = handoff(agent=specialist, input_filter=continuation_filter)

# 2. LANGGRAPH - forwards nothing; you construct the update explicitly.
@tool
def transfer_to_sales(runtime) -> Command:
    ai = runtime.state["messages"][-1]                   # the handoff tool call
    ack = ToolMessage("-> sales: upgrade request, acct 1182 verified",
                      tool_call_id=runtime.tool_call_id) # the summary lives HERE
    return Command(
        goto="sales_agent",
        graph=Command.PARENT,                   # resolve in the parent graph
        update={"messages": [ai, ack],          # these two. not the history.
                "active_agent": "sales_agent"},
    )

# 3. GOOGLE ADK (python v2.0.0) - isolates by construction.
coordinator = LlmAgent(
    name="coordinator",
    sub_agents=[
        LlmAgent(name="weather", mode="single_turn"),  # returns result; parallel
        LlmAgent(name="booking", mode="task"),         # runs until finish_task
    ],                             # each gets its own isolated session branch
)
# mode is for sub-agents only, and task-mode agents must be leaves.

Share the context, or filter it? Ask why the receiver exists

Here two pieces of well-known advice appear to collide. Cognition’s rule is share context, meaning the full traces of prior agents and not just their final messages, because actions carry implicit decisions. LangChain’s rule is forward two messages and summarize. Both are right, and the variable they disagree about is not framework taste. It is the receiver’s job.

An agent that continues work needs the trace, because the decisions it must stay consistent with were never stated — they were implied by earlier actions. An agent that verifies work must not have the trace, because a reviewer handed the author’s context inherits the author’s blind spots. An agent that is merely routed to — support triage, a billing desk, a refund specialist — needs the task and the user-visible facts, and nothing about how the previous agent reasoned.

So the filter is a function of the handoff’s purpose, which makes purpose a field you declare rather than a thing you infer at 2am. Continuation: forward the trace, compressed. Verification: forward the artifact and the acceptance criteria, nothing else. Routing: forward the task and the user’s own words.

The three things that must never cross

Raw tool results. A forwarded tool trace lands on the receiver as undifferentiated text, and the receiver cannot separate what was observed from what was concluded, or when. A stale balance, a search result from three turns ago, a query that half-finished — all of it reads as current fact. remove_all_tools exists for exactly this, and its documented limit is the lesson: it removes structured tool items only, so anything a prior agent quoted into an ordinary message, or that got folded into a nested-history summary, survives untouched. Filtering the trace and redacting the content are two jobs.

The caller’s authority. A handoff must never widen what the receiver may do, so capability has to be re-derived from the receiver’s own grant rather than inherited from the caller’s. This is not theoretical: ADK has an open issue in which disallow_transfer_to_peers=True can be bypassed. And OpenAI’s is_enabled is evaluated before the model has produced the handoff arguments — it can gate whether a handoff is offered, but it cannot authorize the values inside one, which is why the docs point you at validating at the start of on_handoff and raising. Authorization belongs after the arguments exist, on the receiving side.

A conclusion dressed as a premise. The quiet one, and the expensive one. Forward the customer is eligible for a refund and the receiver cannot know eligibility was never checked; it is a premise now, and every downstream action inherits it. Forward customer requested a refund of $240 on order 1182, eligibility not checked, and the receiver does the check. A handoff carries observations and open questions, and carries a verdict only when a tool actually produced one. No trace marks that difference for you, which is why it belongs in the envelope’s type.

# The three things that must never cross, as code.

SENSITIVE = ("authorization", "api_key", "bearer", "card_number")

def sanitize(data, purpose: str):
    # 1. RAW TOOL RESULTS. remove_all_tools drops STRUCTURED tool items only --
    #    anything a prior agent quoted into a normal message survives it.
    data = handoff_filters.remove_all_tools(data)
    items = [redact(i, SENSITIVE) for i in data.pre_handoff_items]
    if purpose == "verify":
        items = []   # a reviewer with the author's trace inherits its blind spots
    return data.clone(input_history=(), pre_handoff_items=tuple(items))

# 2. AUTHORITY. Re-derive from the RECEIVER's grant. Never inherit the caller's.
def authorize(ctx, env: HandoffEnvelope) -> None:
    granted = POLICY[ctx.context.receiving_agent]        # receiver's own policy
    asked = capabilities_implied_by(env.task)
    if asked - granted:
        raise PermissionError(f"handoff widens scope: {sorted(asked - granted)}")

# 3. CONCLUSIONS AS PREMISES. Only tool-backed facts may enter `established`.
def established_from(trace) -> list[str]:
    return [f"{t.name} -> {t.summary}" for t in trace if t.kind == "tool_result"]

#  bad:  established  = ["customer is eligible for a refund"]   <- never checked
#  good: established  = ["get_order -> 1182, $240, placed 2026-10-29"]
#        open_questions = ["is order 1182 inside the 30-day refund window?"]

Artifacts need identity, not inlining

The payload people get most wrong is the artifact, because inlining it feels like being helpful. A2A is the useful reference, since it had to make these decisions explicit to work across organizational boundaries: work is grouped by a contextId spanning multiple Task and Message objects, a specific unit of work is a taskId, and follow-on work points back with referenceTaskIds rather than resending content.

Two spec details carry the design lesson. Once a task reaches a terminal state — completed, canceled, rejected, or failed — it cannot restart, so a refinement is always a new task inside the same contextId. And a refined output reuses a consistent artifact name while getting a new artifactId, with the spec noting that this version linkage is not part of the protocol. Identity and version history are yours to maintain.

Practically: hand off a pointer plus enough metadata to resolve it — id, version, location, what it is — not a forty-kilobyte document pasted into a message. The receiver fetches what it needs. The alternative is a context window that grows with every hop and a receiver that cannot tell which of three pasted versions is current.

Instrument the crossing, not the turns

A handoff failure almost never raises. The receiver answers confidently from a premise nobody checked, or re-runs a tool call the caller already paid for, or hands back to the caller, which hands straight back to it. None of that is an exception. So the thing worth logging is the boundary crossing.

Five fields catch the real handoff bugs: the task text as sent, because it is the whole interface and you will diff it when quality moves; what was forwarded and what was filtered, as two numbers, since either alone is meaningless; whether the receiver called a tool the caller had already called in this run; and the hop count on this context. Duplicate tool calls across the boundary mean the filter cut something load-bearing. A rising hop count with no artifact produced is a routing loop, the one failure that quietly consumes an entire rate limit before anybody notices.

# Handoffs do not raise. Log the crossing.
from dataclasses import dataclass

@dataclass
class Crossing:
    task: str               # the whole interface. diff it when quality moves.
    purpose: str            # continue | verify | route -> which filter ran
    forwarded_tokens: int   # what the filter let through
    filtered_items: int     # what it cut. one number without the other lies.
    repeat_tool_calls: int  # receiver re-called a tool the caller already paid for
    hop: int                # position in this context

def report(xs: list[Crossing]) -> dict:
    n = len(xs) or 1
    return {
        "repeat_rate": sum(x.repeat_tool_calls > 0 for x in xs) / n,
        "max_hop": max((x.hop for x in xs), default=0),
        "tokens_per_hop": sum(x.forwarded_tokens for x in xs) / n,
    }

# repeat_rate high      -> filter cut something load-bearing, or task text is thin
# max_hop climbing      -> ping-pong. cap hops and fail LOUDLY, not silently.
# tokens_per_hop rising -> you are forwarding the trace, not a summary.

The default, and the interview answer

Default to a typed envelope — task, context reference, artifact references, purpose — with the filter chosen by purpose and authorization re-derived on the receiving side. Prefer agent-as-tool whenever you want the caller to remain the author, which is more often than the word handoff suggests. Reach for a real transfer of ownership when the receiver owns a policy the caller has no business reimplementing — which is also the line where just give it another tool starts hiding a responsible subsystem behind a function signature.

The interview answer is three sentences. A handoff is a transfer of ownership rather than a message forward, so control does not return and anything the caller knew but did not write down is lost. Three things cross, with different lifetimes: the task, which is prose and deserves a schema; the context, filtered by why the receiver exists — forward the trace to continue work, withhold it to verify work, send only the task and the user’s words to route; and artifacts, which travel by reference, the way A2A points back with referenceTaskIds instead of resending content. And three things must never cross: raw tool results, because the receiver cannot separate observation from conclusion; the caller’s authority, because capability must be re-derived against the receiver’s own policy after the arguments exist; and a conclusion dressed as a premise, the failure that produces a confident wrong answer with no error anywhere in the trace.

The one-line version for a design doc: a handoff is a contract, and the context is the part of it you have to argue about.

PRACTISE IT · SYSTEM DESIGN LABS

Work the same ideas as a full interview case study, with pressure questions and model answers.

Keep reading

Related articles