How to Organise a Team of Agents

Suppose four agents are working on the same feature. One owns the data model, one the API, one the user interface and one the tests. It looks like a team until the API agent invents a field the data model does not provide, the UI agent relies on a different error contract, and the test agent helpfully changes both.

The problem is not that the agents lack roles. They have excellent role names. The problem is that we organised them around nouns rather than decisions and dependencies.

In the previous chapter, I covered the mechanics of parallel work: ownership, isolated workspaces and integration order. Once those exist, we can decide how agents coordinate. The right answer is rarely a miniature corporate hierarchy. It is the smallest topology that lets information reach the person or agent responsible for the next decision.

The work graph comes first

An agent team is a scheduling system laid over a graph of work. Nodes are tasks or decisions. Edges say that one node depends on the result of another.

That graph should determine the team, not the other way round. Before assigning roles, I would write down:

• which decisions affect the whole change;
• which tasks can finish without seeing each other’s work;
• which outputs become inputs to another task;
• where two agents might edit the same interface or resource;
• who decides whether a result is accepted, revised or discarded.

If the public API is unsettled, API consumers should not be independent implementation tasks yet. If three investigations can test separate explanations for the same fault, they are independent even when they all read the same files. “Backend”, “frontend” and “tester” do not tell us either of those things.

The graph also exposes an awkward truth: some useful teams contain only a lead and one worker. Extra agents are not a sign of maturity. They are extra context windows, communication paths and results to reconcile.

Centralised coordination: one owner, narrow workers

The simplest structured topology is a manager-worker tree. A lead owns the overall outcome, turns the current state into bounded tasks and receives a hand-off from each worker. Workers do not negotiate the architecture among themselves. They report discoveries to the lead, which decides whether the plan needs to change.

This works well when coherence matters more than local speed:

                 lead
              /    |    \
       research   API   migration
           |       |       |
        hand-off hand-off hand-off
              \    |    /
              lead decides

Centralisation gives us one place where the whole problem is supposed to fit. It also limits communication. Three workers need three relationships with the lead, rather than maintaining shared context across every possible pair.

Cursor’s research on long-running multi-agent coding arrived at a recursive version of this pattern. A root planner delegated bounded areas to subplanners, workers operated on their own repository copies, and information travelled upwards through hand-offs. Cursor also found that an agent asked to plan, explore, spawn, edit, merge and judge at once behaved poorly. The useful lesson is not that every team needs recursive planners. It is that ownership becomes meaningless when the owner is also doing every job.

The central lead has obvious failure modes:

• it can become a queue in front of otherwise independent work;
• its context can fill with low-level reports until the global view is the first thing lost;
• a mistaken decision from the lead can be copied into every branch;
• if it disappears, the team may have no durable account of what remains.

Cursor removed a single global integrator when it became a bottleneck in its particular large-scale experiment. For a normal product repository, an integration owner is still useful. The distinction is between owning integration decisions and serialising every mechanical action through one agent.

I would use a centralised topology when the work changes shared contracts, when discoveries are likely to alter the plan, or when one coherent design matters more than maximum fan-out. Keep the lead out of routine implementation, give it concise hand-offs, and persist the task graph somewhere other than its conversation.

Decentralised coordination: a shared queue and local decisions

At the other end is a flat pool. Agents claim ready work from a shared queue, update its state and communicate directly when necessary. There may still be a human owner of the final outcome, but no agent routes every intermediate decision.

Claude Code’s agent teams documentation describes a hybrid with some of these mechanisms: a lead and separate teammates share a task list, dependency status and mailboxes; tasks can be assigned or self-claimed. The feature is experimental, and the lead still creates the team and coordinates its work. It illustrates distributed task claiming, not a fully flat organisation or proof that self-claiming is always the correct policy.

A flat pool suits work that is plentiful, similar and weakly coupled. Dependency updates across unrelated packages, read-only issue triage, or a set of independent compatibility checks can be drawn from a queue without asking a central planner to narrate every move.

It becomes less attractive as shared judgement increases. With six peers there are fifteen possible pairwise communication paths. Nobody needs to use all of them, but an instruction to “coordinate with the team” provides no clue about which paths matter. Messages multiply, agents repeat context, and two local agreements can quietly contradict a third.

Decentralisation also needs harder coordination primitives than a chat room:

• an atomic claim so two workers do not take the same task accidentally;
• explicit dependency state so blocked work is not treated as available;
• stable ownership of shared files and external resources;
• a durable result attached to the task, not hidden in one conversation;
• a policy for stale claims when an agent crashes or loses its session.

Without those controls, the shared queue is merely a hopeful document with several writers.

I would use a decentralised pool when tasks are interchangeable, their acceptance criteria are local, and duplicate work is cheap. I would not use it to discover a system-wide architecture by committee.

Pipelines separate stages, not personalities

Another common shape is a pipeline: researcher, implementer, verifier, integrator. Each stage receives an artefact from the previous one and applies a different acceptance rule.

This can be useful because generation and verification have different failure modes. An implementer is rewarded for making the change work; a verifier should try to disprove that claim against the specification. Keeping those contexts separate reduces the temptation to reinterpret a failing check as acceptable.

Yet a role should exist because it owns a distinct decision, not because a diagram has space for it. A separate test agent for every small change may create a slow argument about intent while the implementation agent waits. The implementer should normally write and run the closest tests. Add independent verification when the risk justifies another perspective or when the acceptance artefact can be checked without renegotiating the feature.

Pipelines have their own queueing problem. If five implementers feed one reviewer, completed work piles up before the gate. If every reviewer response sends the change back to the beginning, a minor naming issue may rerun an expensive sequence. Set a work-in-progress limit and distinguish rejection, correction and a newly discovered requirement.

Competing agents are an experiment, not a team

Sometimes the right topology gives the same task to several agents. This is useful for uncertain investigations, design alternatives or a high-value change where comparing independent approaches is worth the cost.

The outputs are alternatives. We should budget to discard most of them.

Define the comparison before starting: correctness against the same tests, operational complexity, performance under the same workload, or the quality of evidence supporting an explanation. If the judge is another model applying a vague preference, we have added a fourth opinion rather than resolved the first three.

Competitive work also needs isolation. Two agents implementing alternatives on one branch will converge accidentally, overwrite evidence or produce a hybrid nobody intended. Separate workspaces and a common base make the comparison meaningful.

Communication should follow decision rights

The goal is not maximum agent conversation. Communication consumes context and creates another version of the truth. Its purpose is to move evidence to whoever can act on it.

For routine work, a structured hand-off is usually enough:

task: api-error-contract
status: blocked
base: 4d3c2b1
changed: []
checks:
  - name: contract tests
    result: not-run
finding: The specification allows retries, but does not define idempotency.
decision_needed: Choose an idempotency key and retention period.

This is more useful than a transcript. It identifies the task, status, provenance, evidence and the next decision. The receiving owner can answer once and update the shared contract before dependent work resumes.

Direct messages are valuable for exceptions: a newly discovered dependency, a contradiction in the specification, or a request for an owned artefact. They are a poor substitute for persistent task state. If completion, ownership and blockers exist only in conversation, recovery means asking every surviving agent what it remembers.

Broadcasts deserve particular suspicion. “The interface changed” may be relevant to three workers and noise to seven others. Update the authoritative interface, notify the owners of dependent tasks, and let unrelated work continue.

A practical hybrid

Most useful arrangements are neither completely centralised nor completely flat. I prefer a hybrid with centralised decisions and decentralised execution:

1. one owner maintains the overall goal, dependency graph and integration order;
2. ready tasks are narrow enough for workers to execute without constant permission;
3. workers own their local implementation and tests;
4. discoveries travel to the owner of the affected decision, not to everybody;
5. independent verification is added at risky boundaries;
6. durable task state lets another agent or human recover the run.

Consider a database migration with an API change and two consumers. The schema and compatibility policy should have one owner. Once fixed, the API adapter and consumers can proceed in parallel. A verifier can test old and new records against the integrated result. There is no reason for both consumer agents to debate the migration, nor for the lead to write their code.

If one consumer reveals that the compatibility policy is impossible, that information returns to the schema owner and dependent tasks pause. This is dependency-aware coordination: we do not continue producing code against a decision known to be unstable.

Choose the topology by its failure mode

Centralised coordination risks a bottleneck and a single bad decision. Decentralised coordination risks conflicting local decisions and noisy communication. Pipelines risk queues between stages. Competing agents deliberately pay for discarded work.

There is no universally superior shape. Choose the failure mode you can observe and afford:

• use a lead when global coherence is the scarce resource;
• use a flat pool when ready tasks are abundant and genuinely independent;
• use a pipeline when stages have distinct evidence and decision rules;
• use competition when reducing uncertainty is worth duplicate execution.

Then remove any role, message path or shared state that does not improve a decision. Agent teams become easier to operate when we stop imitating an organisation chart and start respecting the work graph.

The next question is what happens when that team runs without anyone present to correct it. An overnight run changes coordination into a hand-off across time. That is the subject of the next chapter.