A common pattern is to give AI agents job titles. One agent researches, another writes code, a third reviews, and a coordinator decides what happens next. The pattern is easy to describe and easy to demo. Running it for weeks on real work is harder, and most of the difficulty lives in the handoffs between roles.
This article is about the design of such a team, not a report on any particular setup. I have not run a multi-agent system of this size, so the points below come from how these systems are built and where they usually fail.
Roles need a clear job and a clear output
Each agent should have one job, a defined input, and a defined output. "Research competitors and write a summary with three sources" is a role. "Help with marketing" is not. A role that cannot say what it produces will produce something, and no one can check it.
Write the output format down. A researcher that returns a table of claims with a source column gives the next agent something it can verify. A researcher that returns a long essay gives the next agent a guess.
Boundaries belong in the tools
An agent's permissions are part of its role. A reviewer should be able to read the diff and post comments, but not merge. A developer should be able to change a branch, but not change production. Enforce that through the tools the agent can call, not through a sentence in its instructions. Instructions can be ignored or misread. A missing tool cannot be used.
The handoff is where work gets lost
Most failures happen between agents, not inside one. A handoff that passes a summary instead of the actual artefact loses detail. A handoff that passes the artefact without its context forces the next agent to guess what matters.
Make each handoff explicit. Name the artefact, the reason it moved, and what the receiver must check. Keep a log of handoffs, so you can see where a decision changed hands and why.
Coordinators need limits
A coordinator agent that assigns work and decides when it is done is useful, and also a single point of failure. It can loop, reassign the same task, or declare victory on a result nobody checked. Give the coordinator a budget: a maximum number of reassignments, a time limit, and a rule that says what to do when a task fails twice.
The coordinator should also report evidence, not summaries. A coordinator that says "all tasks complete" should be able to point at the output of each one.
Measure what each role produces
Track the output of each role, not just the total. A reviewer that approves everything is not reviewing. A researcher whose sources fail spot checks is not researching. Spot-check a sample of each role's work on a schedule, and keep the results.
Where to start
Start with two roles and one handoff. Get that handoff reliable, with a clear artefact, a clear check, and a log. Add a third role only when the first two are boring to run.
Most teams find that the second role is harder to design than the first, and the third is harder again. That is the signal to slow down, not to add more agents.
Summary
A team of agents is a set of roles, boundaries, and handoffs. Give each role one job and a checkable output, enforce boundaries through tools, make handoffs explicit with the artefact attached, cap the coordinator, and measure each role's output. Keep the team small until the handoffs are reliable.
Top comments (1)
A useful negative control for the two-role starting point: keep the task and patch fixed, but give the reviewer the implementer's write permissions. The handoff can look complete while the separation has disappeared. I'd check the declared role mapping before launch, then separately inspect the credentials and tools actually supplied to each process.
One boundary worth adding to 'a missing tool cannot be used': a general shell or raw API credential can recreate an operation that is absent from the named tool list. The review-only test should therefore include those execution paths too.
For the coordinator's acceptance record, I'd bind the verdict to the exact patch revision and list checks not run. A new patch needs a fresh applicability check before an earlier approval carries forward. These are proposed test cases, not results from your setup.