Ai-engineering

Your agent handoff is an API boundary. Write it like one.

September 21, 2026 · 7 min read

Every multi-agent setup I see is organized around the same question: which model is the smartest one. The demos work because the person writing the plan is also the person writing the code.

Split those roles across two agents and the failure moves somewhere less flattering.

The breakdown is in the handoff, not the model

A research team built a taxonomy of multi-agent failures to find out where these systems actually break. The MAST paper ("Why Do Multi-Agent LLM Systems Fail?", arXiv 2503.13657, by Cemri, Pan, Yang and others) sorts 14 failure modes into three categories: system design, inter-agent misalignment, and task verification. In the summary I read, specification issues account for roughly 42% of failures and inter-agent misalignment for roughly 37%, drawn from more than 1,600 traces across seven multi-agent frameworks.

The largest bucket is not "the model was too weak." It is "the two agents did not agree on what the task was."

A practitioner hit that in the most ordinary way possible. In a September 20 Dev.to write-up, yureki_lab (Reid Marlow) describes a planner agent handing tasks to an implementer sub-agent with no shared context. About 31% of tasks came back with scope creep or the wrong target. His opening incident: the task read "fix the flaky date parsing in the export job," the implementer edited the legacy CSV exporter, the active exporter was the JSON one, and the flaky test kept failing for three more days while a verifier approved a diff that was internally consistent.

Nothing in that story is exotic. It is the same class of bug as a ticket that says "fix login" and then three days of changes land in the wrong service.

I still run into this with people, often. When a requirement is vague or still moving, someone changes a place that should not have been touched. The part that stings is that I already know which file needs to change and what the change should be. The information existed; it just never made it into the ticket. So the work goes back and forth: a diff in the wrong place, a review that turns into a second requirements conversation, and time spent on both.

The gap is rarely skill or knowledge. It is that the requirement lived in my head, or in a chat thread, instead of in the thing the other person was reading.

Treat the handoff like an API boundary

The fix was to stop passing prose between the two agents and pass a schema instead.

The contract is a YAML document. Writing it out makes the missing parts obvious. Most prompts I have seen say what to do and nothing about what to leave alone. This one has a field for that:

task_id: export-date-parsing-flaky
goal: Fix the flaky date parsing in the active export job.
why: Export failures page the on-call engineer about once a week.
scope:
  allowed_paths:
    - src/export/json/**
  forbidden_paths:
    - src/export/csv/**        # legacy exporter, do NOT touch
    - src/export/index.ts
context:
  - The active exporter is src/export/json/exporter.ts. The CSV one is legacy and unused.
acceptance:
  - run: npm test -- export/date-parsing
    expect: all tests pass
forbidden_moves:
  - Do not rename exported functions.
  - Do not change the export file format.
done_signal: The acceptance command passes and the diff touches only allowed_paths.
budget:
  max_turns: 12

Two details matter more than the rest. forbidden_paths names the negative space, which is the part a free-form prompt always loses. "Negative space beats positive space," Marlow writes, and that field is the clearest example of it. The context block is the second: it carries the facts an implementer cannot discover on its own, like which of the two exporters is live. That is the same information I used to keep in my head while a teammate guessed at it.

Marlow checks the contract with about 60 lines of Python instead of another model. The script validates the structure and rejects any spec where allowed_paths, forbidden_paths, or forbidden_moves is empty. A deterministic script can say no. A second LLM reviewing a first LLM's output is a much weaker guarantee, because it can always find a reason to agree.

Make the receiver echo the task back

Before the implementer touches a file, it has to repeat the task in its own words:

Before you change any file, reply with exactly these five lines:
1. Files I will change:
2. Files I will not touch:
3. Done means:
4. I will not:
5. Open questions:

If line 5 is not "none", stop and ask instead of writing code.

If the echo does not match the contract, the script rejects it and allows one retry. If the echo contains an open question, the task goes back to the planner instead of forward into code.

I have used a version of this with people for years without calling it a contract. A junior engineer who repeats the ticket back in their own words before starting catches the misunderstanding while it is still free to fix. For an agent, the echo costs one cheap turn, and it runs before any code exists to review.

A frontier lab ran into the same wall

This is not only a solo-practitioner problem. Anthropic's write-up on its multi-agent research system (June 2025) describes the same failure from the other end of the scale. Vague subagent instructions, the kind that just say "research the semiconductor shortage," led subagents to duplicate each other's work or drift off the task. The fix Anthropic describes is a contract in all but name: give each subagent an objective, an output format, tool guidance, and clear task boundaries. A deployment that real researchers use every day arrived at the same place as a one-person project on Dev.to.

The numbers, and what they do not prove

Over two periods of 120 tasks each, the write-up reports:

MetricBefore (spring 2026)After (August 2026)
Approved on first pass57%81%
Scope creep or wrong target31%7%
Gave up or produced nothing useful12%12%

Planner token cost rose about 20% per task. I would not quote the improvement as a result. It comes from one practitioner, one system, and two different time windows, so a model upgrade or a shift in task mix could explain part of the change. Nobody has reproduced it independently, as far as I can find.

The flat 12% is the honest detail in that table. The contract fixed misunderstanding, not difficulty. Tasks that were genuinely hard stayed hard, which is what you would expect if the mechanism is what the author says it is.

The hole: nothing enforces the forbidden paths

A reader asked in the comments how the verifier enforces forbidden_paths against the real git diff. That question did not get a clear answer in what I read, and I could not find evidence that anyone checks it mechanically. One 2026 write-up on handoff contracts makes the same argument from the other direction: a contract has to define "done," the output format, and what not to touch, and the agent needs a "stop and escalate" instruction when the situation does not fit.

A rule that only lives in a prompt is a request, not a control. If you add forbidden_paths to a handoff contract, something mechanical has to read that list and compare it to the changed files, in CI, where a mismatch fails the build. Otherwise you have written the prohibition down and still trust the same agent to respect it.

A starting checklist

  • Give every agent handoff a schema instead of a paragraph.
  • Include forbidden_paths and forbidden_moves, not just what to do.
  • Add the context an implementer cannot discover on its own.
  • Validate the structure with a deterministic script, not a second model.
  • Make the implementer echo the task back before it writes code.
  • Express acceptance as a command plus expected output, and have a separate verifier re-run it.
  • Check the real diff against the forbidden paths in CI.
  • Measure your own first-pass approval rate before and after, so you find out whether any of this works for your team.

Sources: