← All notes

Summary

A handoff is one agent passing the live task to another agent that is better suited to it. Research described only in an abstract argues for explicit roles and written procedures so agents check each other's intermediate work. A Python agents SDK shows the mechanics: the model sees each handoff as a tool, and you decide what history the next agent receives.

Why a plain chain is a weak handoff

Language-model agent groups can already handle simple dialogue. Harder work breaks when one model's output is fed straight into the next and mistakes pile up. The MetaGPT abstract calls that cascading hallucinations from naively chaining models.

That framework writes standardized operating procedures into prompt sequences. Role-style agents check intermediate results. An assembly line assigns different roles and splits a large task into subtasks. On collaborative software-engineering benchmarks, the abstract says the solutions were more coherent than earlier chat-based systems. It does not include the prompt text or the scores.

Name the role, say what finished work looks like, and have a later role inspect it. Do not treat "pass the whole chat along" as a procedure.

How the SDK hands off

In the Agents SDK, a handoff delegates to a specialist, for example separate agents for order status, refunds, and common questions. The model sees each handoff as a tool. A handoff to an agent named Refund Agent defaults to the tool name transfer_to_refund_agent.

The handoffs parameter takes an agent directly or a Handoff object. A plain agent's handoff description, when set, is appended to the default tool description. The handoff helper sets the destination plus optional tool name, tool description, callback, input schema, input filter, enabled flag, and a nested-history override.

The helper always transfers to the agent you passed. Register one handoff per destination and let the model choose. Use a custom handoff only when your code must pick the destination at call time.

What crosses with the handoff

An optional input schema is the tool-call arguments, for a small piece of model-written metadata such as a reason, language, priority, or summary. The SDK exposes that schema, checks the JSON locally, and passes the parsed value to the callback. It does not replace the next agent's main input and does not choose another destination. Application state you already have belongs on the run context.

The enabled flag is evaluated while the SDK lists handoffs, before arguments come back, so it cannot authorize fields inside the payload. Check those fields at the start of the callback, before side effects, and raise on failure. A normal return continues the transfer. Tool input guardrails cover function tools, not handoffs.

By default the next agent sees the entire previous conversation. An input filter can replace that payload. A supplied filter removes structured tool items but not tool text already copied into ordinary messages. If both a per-handoff filter and a run-level filter exist, the per-handoff filter wins.

Nested handoff history is an opt-in beta, off by default. It changes how the transcript is packed. It does not redact sensitive data, and tool arguments can remain inside generated summaries. Server-managed conversation state does not support these filters; start a separate run with the input you selected, and do not reuse the original conversation identifiers.

Handoffs stay inside one run. Input guardrails apply only to the first agent. Output guardrails apply only to the agent that produces the final output. Put a short explanation of handoffs in agent instructions; the SDK offers a recommended prefix for that.

Claims

• id: C1 claim: Feeding language models into each other without a procedure can stack logic errors from cascading hallucinations. source: S1 evidence: "logic inconsistencies due to cascading hallucinations caused by naively chaining LLMs."
• id: C2 claim: MetaGPT writes operating procedures into prompt sequences and assigns roles so agents can check intermediate results. source: S1 evidence: "MetaGPT encodes Standardized Operating Procedures (SOPs) into prompt sequences for more streamlined workflows"
• id: C3 claim: A handoff lets one agent delegate work to another, and the model sees that handoff as a tool. source: S2 evidence: "Handoffs allow an agent to delegate tasks to another agent."
• id: C4 claim: The handoff helper always transfers to the specific agent you passed, so each destination needs its own handoff. source: S2 evidence: "helper always transfers control to the specific agent you passed in."
• id: C5 claim: Unless you filter it, the next agent sees the full conversation history from before the handoff. source: S2 evidence: "the new agent takes over the conversation, and gets to see the entire previous conversation history."
• id: C6 claim: Nested handoff history reshapes the transcript and does not remove sensitive data. source: S2 evidence: "Nested handoff history changes how the transcript is represented; it does not redact sensitive data."
• id: C7 claim: Handoffs remain inside one run, with input guardrails only on the first agent and output guardrails only on the final agent. source: S2 evidence: "Handoffs stay within a single run. Input guardrails still apply only to the first agent in the chain"

@misc{iil_note_rgdjfesq,
  author = {{iinventedlight}},
  title = {{Handoffs between agents}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-03},
  url = {https://iinventedlight.com/library/notes/ao-handoff/},
  note = {Permanent ID iil:note:rgdjfesq. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/ao-handoff.md.