Multi-agent orchestration

Multi-agent orchestration is running several tool-using agents instead of one, each scoped to a role or a slice of the work, and coordinating them toward a single goal. It is worth doing for two reasons, and only those two: parallelism — several agents make progress at once, for example one per module of a codebase — and focused context — an agent with a narrow job and a small tool set is more reliable than one agent juggling everything in a single, crowded context.

It is not free. Coordination has overhead, so reach for it when the work genuinely separates or genuinely benefits from focused context — not by default.

The common shapes

Most orchestration is one of these, or a mix:

• Manager and workers. One agent decomposes the goal, hands each slice to a worker agent, and combines the results. Good when the work splits cleanly into independent pieces (for example, “write tests for each of these ten files”).
• Pipeline. Each agent is a stage, and one stage’s output is the next one’s input — draft, then review, then fix. Good when the work is sequential and each step wants a different focus.
• Peers on a bus. Agents coordinate as equals over a shared channel, claiming tasks and warning each other before they collide. This is what the hcom bus provides across machines.
• Evaluator. A separate agent checks another’s output rather than producing work itself — a useful add-on to any of the above, since an agent reviewing with fresh context catches what the author missed.

A concrete instance: the multi-machine stack

The multi-machine agent stack in this handbook is this pattern, built out. amux gives each agent its own git worktree, so several can edit the same repository at once without overwriting each other — that is the isolation that makes parallelism safe. hcom is the peers-on-a-bus channel, letting agents on different machines claim work and flag collisions. Putting agents on separate machines is just the same pattern stretched across hardware. So if you want to see orchestration end to end, connect two machines and watch two agents coordinate.

Making it work

The failure modes are predictable, so design against them:

1. Give each agent a narrow job and only its tools. The point of splitting up is focus; handing every agent the whole toolbox throws that away.
2. Make collisions impossible or visible. Isolate the work — a worktree per agent — so two cannot overwrite each other, and surface what they tell each other (the bus, a dashboard) so you can see what is happening rather than guess.
3. Stay the integrator. The agents produce branches and partial results; you review and merge. Orchestration spreads the work out, but it does not move the final judgment off you.

Where to go next

• The foundation each agent uses: Tool use .
• Build it: Run agents on one machine , then Connect machines .
• The whole picture: A multi-machine agent stack .