Agent Handoff Testing: Failure Modes and Test Cases

What Is an Agent Handoff?

A handoff is a transfer of control between agents. The sending agent stops working on the task, and the receiving agent takes ownership of the conversation from that point forward.

The mechanism is worth knowing because it shapes what you can test. In the OpenAI Agents SDK, handoffs are presented to the model as tools with names in the form transfer_to_<agent_name>, which means the model itself decides when to delegate. That decision is non-deterministic, so a handoff is not a code path you can trace statically.

Two pieces of state cross the boundary, and each fails differently:

• The handoff payload - structured arguments the model generates for the transfer tool. The OpenAI Agents SDK validates this against a schema locally before passing it on, so a malformed payload is caught, but an incomplete schema is not.
• The conversation history - by default in the OpenAI Agents SDK, the new agent sees the entire previous conversation, as though it had taken over the dialogue. An input filter narrows that, and every field the filter removes is a field the receiving agent can no longer read.

LangChain takes the opposite default. Its handoff documentation states that unlike single-agent flows where message history moves along naturally, you must explicitly decide what messages pass between agents, and it recommends passing only the handoff pair rather than the full history. Explicit defaults make context loss a design decision instead of an accident, which is exactly why the decision needs a test.

If you are still deciding whether to split one agent into several, the tradeoffs are covered in our guide to multi-agent AI systems.

Are Handoffs and Routing the Same Thing?

They are different operations with different bugs, and conflating them produces tests that check the wrong thing. Routing picks a destination before work starts. A handoff moves control after work has already begun, which is why state has to travel with it.

A routing bug is loud. The billing question lands on the shipping agent and the very next sentence is wrong. A handoff bug is quiet, because the receiving agent is qualified and its reply reads as a competent request for more information. That asymmetry is why handoff coverage tends to be missing from suites that already test routing well. The wider pattern set is covered in our breakdown of agentic AI orchestration patterns.

What Actually Breaks at a Handoff?

Researchers at UC Berkeley built the Multi-Agent System Failure Taxonomy by annotating traces from seven multi-agent frameworks and grouping what they found into 14 failure modes across three categories. Their empirical analysis reports a 41% to 86.7% failure rate on those seven state-of-the-art open-source multi-agent systems, according to the MAST taxonomy paper. One of those three categories is inter-agent misalignment.

The per-mode numbers are more useful than the category total, because each one names a specific thing to assert. The modes below are the ones that surface at a transfer boundary, with shares reported in the same paper:

Two of these are worth separating, because they look identical in a transcript and need opposite fixes. Information withholding is a sender bug, so the fix is the payload schema. Ignored other agent's input is a receiver bug, so the fix is the receiving agent's prompt. A test that only reads the final reply cannot tell you which one you have.

Note also how small the individual shares are. No single handoff mode dominates, which means sampling a handful of conversations by hand is unlikely to surface any of them. Coverage has to be systematic, and the same argument applies across the broader problem of multi agent testing.

What Should You Assert at Every Handoff?

Five assertions cover the failure modes above. Each one is checkable without a model in the loop, which keeps the test fast and deterministic even though the agents are not.

• Payload completeness - declare the fields the receiving agent needs and fail when any is absent. This is the direct test for information withholding, and it catches the schema gap rather than the symptom three turns later.
• History validity - confirm every transfer tool call has a matching acknowledgement. LangChain's guidance is explicit that the AI message carrying the tool call and a ToolMessage with the same tool call id must both be present, and an orphaned call leaves the history in a state the next model call may reject.
• Hop budget - cap the number of transfers per run and fail above it. Without a cap, a handoff cycle ends only when tokens or wall-clock time run out, which reads as a slow run rather than a bug.
• No repeated questions - check that the receiving agent does not ask for a value already present in the payload or history. This turns conversation reset and ignored input into a failed assertion instead of a customer complaint.
• Terminal state reached - assert the run ends in a defined outcome such as resolved, escalated, or refused. An agent that hands off and then stops is a silent failure with no error to catch.

All five read from one artifact: a recorded trace of the transfers. Build that recording first, because assertions written against a final transcript can only report that something went wrong, never which hop did it.

How Do You Write a Handoff Test?

Wrap the transfer in a function that appends to a trace, then assert on the trace. The harness below models the refund scenario from the opening, with the bug deliberately left in: the triage agent extracts the order number but never writes it to the payload.

// handoff.test.mjs - records every transfer, then asserts on the record.
const trace = [];

function handoff(from, to, payload, history) {
  trace.push({ from, to, payload, historyLen: history.length });
  return { agent: to, payload, history };
}

function runTriage(userTurn, history) {
  history.push({ role: "user", content: userTurn });
  const orderId = (userTurn.match(/#(\d+)/) || [])[1] || null;
  history.push({ role: "assistant", tool_call: "transfer_to_refunds_agent", tool_call_id: "call_1" });
  // BUG under test: orderId is collected but never placed on the handoff payload.
  return handoff("triage_agent", "refunds_agent", { reason: "refund request" }, history);
}

const history = [];
const result = runTriage("I want a refund for order #48812", history);

const required = ["reason", "order_id"];
const failures = [];

for (const key of required) {
  if (!(key in result.payload)) failures.push(`CONTEXT LOSS: required field "${key}" missing from handoff payload`);
}

const lastToolCall = history.filter(h => h.tool_call).pop();
const ack = history.find(h => h.role === "tool" && h.tool_call_id === lastToolCall?.tool_call_id);
if (lastToolCall && !ack) failures.push(`ORPHANED TOOL CALL: "${lastToolCall.tool_call}" has no ToolMessage acknowledgement`);

if (trace.length > 3) failures.push(`HANDOFF LOOP: ${trace.length} transfers exceeded the budget of 3`);

console.log("handoff trace:", JSON.stringify(trace, null, 2));
console.log(`\nassertions run: ${required.length + 2}   failed: ${failures.length}`);
for (const f of failures) console.log("  FAIL  " + f);
process.exit(failures.length ? 1 : 0);

Running it with node handoff.test.mjs produces this output:

handoff trace: [
  {
    "from": "triage_agent",
    "to": "refunds_agent",
    "payload": {
      "reason": "refund request"
    },
    "historyLen": 2
  }
]

assertions run: 4   failed: 2
  FAIL  CONTEXT LOSS: required field "order_id" missing from handoff payload
  FAIL  ORPHANED TOOL CALL: "transfer_to_refunds_agent" has no ToolMessage acknowledgement

$ echo $?
1

Two failures from one transfer, and both name the hop and the field. The first is the refund bug from the opening scenario, caught at the boundary instead of at the customer. The second was not the bug being hunted: the harness pushes a tool call with id call_1 and nothing ever acknowledges it, which is precisely the invalid-history state LangChain's documentation warns about.

That is the argument for trace-based assertions in one run. A transcript check would have reported a single vague failure. Asserting on the record found a second defect nobody was looking for, and printed the tool call id needed to fix it.

How Do You Run Handoff Tests in CI?

The harness exits non-zero when an assertion fails, so any CI runner already knows how to gate on it. What matters is the trigger list, because handoff behavior changes through edits that never touch application code.

• Agent prompt changes - a rewritten system prompt changes when the model chooses to delegate, and handoffs are model decisions rather than code paths.
• Handoff schema changes - adding or renaming a payload field silently breaks the receiving agent until an assertion declares the field required.
• Tool definition changes - a renamed transfer tool changes what the model sees in its tool list, which changes the delegation it picks.
• Model or version upgrades - the same prompts and schemas produce different delegation behavior on a different model, so the suite is the regression net for the swap.

Keep the deterministic assertions in the fast job that runs on every commit, and put the model-graded checks such as tone or completeness in a slower scheduled job. A fast gate people trust catches more than a thorough one they learn to skip, which is the same reasoning behind agent smoke testing.

Once handoff runs are in the pipeline, keep the traces. Production handoff failures are hard to reproduce from a user report, and a stored trace turns a vague complaint into a specific hop. Our guide to agent observability covers moving from evals to production traces.

How Does TestMu AI Test Agent Handoffs?

The harness above proves the boundary contract holds. It cannot tell you whether the receiving agent sounded confused, invented a policy, or quietly dropped a constraint, because those need judgment rather than an equality check. That is the gap TestMu AI's AI agent testing platform fills, by deploying autonomous evaluators against the agent you already have.

Three capabilities map directly onto the failure modes in this article:

• Multi-agent handoff configuration - the tester follows a conversation that switches between agents mid-run rather than treating the transfer as the end of the session, which is what makes post-handoff turns gradeable at all.
• Context awareness scoring - one of nine quality dimensions applied to every chat and voice conversation, measuring whether an agent retains and correctly uses information from earlier in the dialogue. A refunds agent re-asking for a known order number scores against this dimension.
• Escalation quality - part of the phone-call metric set, scoring the smoothness and accuracy of a handoff to a human agent, which is the same boundary problem with a person on the receiving end.

Handoff trends are tracked alongside metrics like containment rate, so a decline in transfer quality shows up as a trend line rather than a scattering of individual complaints. For pipeline runs, testmu-a2a-cli documentation covers triggering evaluations from a terminal and wiring them into CI. Note that this CLI is TestMu AI's agent-to-agent testing tool and is unrelated to Google's Agent2Agent protocol, despite the shared initials.

Use both layers rather than choosing between them. Deterministic assertions on the trace are cheap enough to run on every commit and tell you exactly which field died at which hop. Model-graded scoring is slower and costs more, and it is the only thing that catches a handoff that was technically complete and still left the user worse off.

Conclusion

Start by recording your transfers. Wrap whatever function moves control between agents so it appends the sender, receiver, payload, and history length to an array, then write the payload-completeness assertion for your single busiest handoff. That one assertion covers the failure mode users notice first, and it takes less time to write than reproducing the bug by hand.

Add history validity and a hop budget next, wire the harness into the job that runs on prompt changes, and keep the traces from failed runs. When you need scoring that a deterministic check cannot provide, TestMu AI's autonomous evaluators grade conversations that switch agents mid-run across nine quality dimensions including context awareness, and the agent testing documentation covers connecting an agent over REST, WebSocket, or a realtime transport.