Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 21 of 37

Agent handoffs

0 of 37 complete

Why it matters

Splitting work across agents only helps if each one gets a context small enough to reason in and complete enough to act. In practice the receiver lacks a constraint stated three turns earlier, or both agents believe they still own the task and duplicate the work. The design question is the contract at the boundary: which fields cross, who holds authority, and what condition returns control.

Mental model

A handoff is a shift change in a control room: the outgoing operator briefs the incoming one on state, alarms and open actions. The metaphor breaks because a human briefing can be questioned in real time, while an agent handoff is a one-shot payload unless you build a return path.

How it works

Ownership moves, the payload is a contractInteractive

A handoff moves ownership along one edge; the payload is a contract, and a hand-back without new evidence is a loop.

Step 1/5 · Read the shape

Step 1 of 5

Read the shape

The task record sits under the agents, not inside them. Every ownership change is an edge to it, and the return edge is a first-class path rather than an exception.

Narrow layout: nodes in reading order, each followed by its outgoing edges. The wide drawing shows the same graph as geometry.

    agent

    4 connections

    Triage agent

    owner: triage

    Classifies the request and either acts or transfers it. While it owns the task it is the only agent allowed to act, which is the rule that prevents two owners duplicating a side effect.

callasyncreturnconflictwider stroke + "this step" = current path

user · agent · store · 5 nodes · 9 edges · fixed authored layout, no simulation · list

Figure. A handoff is a transfer of ownership, not a function call. Triage hands the task to billing; billing records the new owner, and triage's ownership is revoked. The return edge is a first-class path, and it becomes a loop when the same pair repeats with no new evidence. The policy agent is consulted without taking ownership.

What to notice. Every ownership change is an edge to the task record, and the record holds exactly one owner plus the mandatory constraints. The figure omits message transport, retry policy and the byte size of payloads; it shows one task, not a fleet. Order numbers, agent names and the handoff count are illustrative.

Text version

Five nodes. The requester connects to a triage agent, which hands the task to a billing agent. Billing can return a blocked result to triage or consult a policy agent, which returns a ruling. Billing writes the new owner to a task record below; the record returns the current owner to billing and receives the policy constraint. A conflict edge from billing back to triage is labelled loop. Steps light the whole graph, the ownership transfer, the payload crossing, the return path and loop, and the accountability record.

  1. Define the payload as a schema: goal, constraints, current state, evidence, open questions and what was already tried.
  2. Name the owner explicitly and revoke the sender's authority to act on the task after transfer.
  3. Pass references to artifacts and logs rather than re-sending their contents.
  4. Give the receiver defined reasons to hand back (blocked, out of scope, complete) and require one.
  5. Cap handoffs per task and require new evidence before any further transfer.
  6. Emit a span per handoff with sender, receiver, reason and payload size.

Trade-offs

ChoiceGood forCostFails when
Full transcript handoffNothing is omittedContext bloat, cost, diluted attentionRuns are long and most detail is irrelevant
Structured summaryFocused and cheapRequires deciding what matters in advanceThe receiver hits an edge case the summary dropped
Handoff to a specialistBetter tools and prompts for the subtaskBoundary cost and lost contextThe subtask is not cleanly separable
One agent with several rolesNo boundary at allA single context must hold every roleRoles need conflicting instructions or tools
Trade-off mapInteractive

Good for

Nothing is omitted

Cost

Context bloat, cost, diluted attention

Fails when

Runs are long and most detail is irrelevant

  1. Runs are long and most detail is irrelevant
  2. The receiver hits an edge case the summary dropped
  3. The subtask is not cleanly separable
  4. Roles need conflicting instructions or tools

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Full transcript handoff is good for Nothing is omitted, costs Context bloat, cost, diluted attention, and fails when Runs are long and most detail is irrelevant. Structured summary is good for Focused and cheap, costs Requires deciding what matters in advance, and fails when The receiver hits an edge case the summary dropped. Handoff to a specialist is good for Better tools and prompts for the subtask, costs Boundary cost and lost context, and fails when The subtask is not cleanly separable. One agent with several roles is good for No boundary at all, costs A single context must hold every role, and fails when Roles need conflicting instructions or tools

Failure modes

  • Handoff loop. Two agents pass the task back and forth without progress. Debug: count handoff edges per task and alert when a pair repeats more than twice.
  • Dropped constraint. The receiver violates a rule stated before the transfer. Debug: assert the payload contains every mandatory field and diff it against the task record.
  • Two owners. Both agents act on the task and duplicate a side effect. Debug: check that the ownership field has exactly one holder at each step.

In production

Monitor handoff count, payload size and time spent between handoffs. Cap depth and total transfers per task, and treat a rising handoff rate as evidence that the split is wrong.

Common misconceptions

People think: More agents means better specialisation.

Actually: Every boundary loses context and adds latency; specialisation pays only when the subtask has distinct tools or instructions.

People think: A handoff is a tool call that returns another agent.

Actually: A tool call returns a result to the caller; a handoff moves responsibility and changes who acts next.

Interview angle

Strong answers specify the payload, the ownership rule and the return path, then explain how a loop is detected, treating the boundary as a contract with a cost. Weak answers describe a framework's handoff primitive and never say what context survives it.

Sources