How it works
An agent team replaces a central router with a set of peers. Instead of one lead agent that plans, delegates, and reassembles, several agents run at once and coordinate laterally. The typical loop:
- A shared task list (a board, a queue, or a shared file) holds the units of work and their status.
- Each agent runs its own loop with its own context window, so no single context has to hold the whole job.
- Agents claim tasks, mark them in progress, and write results back to the shared state.
- Agents message each other directly to hand off, ask a question, or flag a blocker — peer to peer, not up to a manager and back down.
- The team converges when the task list is drained and dependent work has its inputs.
The defining traits are parallelism, private context per agent, direct messaging, and self-organization against shared state. Nobody holds the master plan in one head. That is the source of both the throughput and the risk: work advances on several fronts at once, but the only authoritative picture of "what is true right now" lives in the shared task list, and every agent is writing to it concurrently.
Why it matters in an agent harness
A team changes what your harness has to control. With a single agent, you reason about one trajectory. With a team, you reason about several trajectories plus their interactions — and interactions are where agent systems fail.
Three pressures show up immediately. First, shared state becomes a contention point. Two agents claiming the same task, or overwriting each other's status, produces silent duplicate work or dropped work. The task list needs claim semantics and idempotent writes, not a plain append log. Second, blast radius compounds. One agent with write access is a bounded risk; five agents with write access, coordinating on their own, multiply the ways a bad action lands before anyone reviews it. Permissions have to be scoped per agent, not granted to the team as a unit. Third, observability gets harder exactly when you need it more. A single transcript is legible; five interleaved transcripts plus a message bus are not. Without a merged, timestamped trajectory you cannot answer "why did the team do that," which means you cannot evaluate or roll back with confidence.
The upside is real: parallelism cuts wall-clock time, and private contexts avoid the compaction and context-window pressure that a single agent hits on a large job. But the harness earns that upside only if it treats the shared task list as the system of record and puts checkpoints around the team's writes.
Agent team vs. orchestrator-worker
Both run multiple agents. The distinction is where authority lives, and it changes your control design.
| Agent team (peer) | Orchestrator-worker | |
|---|---|---|
| Coordination | Direct, agent-to-agent | Routed through a lead |
| Plan ownership | Shared task list | Held by the orchestrator |
| Failure containment | Per-agent; team-wide effects are emergent | Choke point at the orchestrator |
| Legibility | Interleaved; needs a merged trajectory | One authoritative trajectory |
| Best when | Loosely coupled, parallelizable work | Work that needs a single decision-maker |
A peer team has no natural place to insert one approval gate — there is no single point every action flows through. An orchestrator-worker gives you that choke point for free. If your primary requirement is reviewable, gated behavior, the orchestrator pattern is easier to make safe. If your primary requirement is throughput on independent subtasks, the team pays off — provided you engineer the shared state.
The Rifty take
We treat an agent team as a throughput tool with a coordination tax, not a default. The tax is real: contention on shared state, a wider blast radius, and interleaved trajectories that resist review. We reach for a team only when the work is genuinely parallel and loosely coupled, and even then we scope permissions per agent and make the shared task list the single system of record with claim-and-idempotent-write semantics. When the job needs a reviewable decision, we keep a single point of authority instead — control you can inspect beats coordination you have to reconstruct.
Implementation checks
- Give the shared task list claim semantics (atomic claim, status, owner) so two agents cannot silently take the same work.
- Make every write to shared state idempotent; concurrent retries must not duplicate or corrupt tasks.
- Scope permissions per agent, not to the team — least privilege per role, not a blanket grant.
- Merge per-agent transcripts and the message bus into one timestamped trajectory you can replay and evaluate.
- Checkpoint before high-impact writes so you can roll back one agent's action without unwinding the whole team.
- Cap the team size and per-agent iteration budget; more agents raise coordination cost faster than they raise output.
- Define a convergence condition and a stall detector so the team terminates instead of looping on an unclaimable task.
Frequently asked questions
How is an agent team different from a subagent setup?
Subagents are spawned and owned by a parent agent that delegates work and collects results — authority stays with the parent. An agent team is peer-to-peer: agents run in parallel, message each other directly, and self-organize around a shared task list, with no single lead holding the plan.
When should I use an agent team instead of a single agent?
Use a team when the work is genuinely parallel and loosely coupled, or when a single context window can't hold the whole job. For work that needs one reviewable decision or a single approval gate, keep one agent or an orchestrator — a peer team has no natural choke point to gate.
What is the main failure mode of an agent team?
Contention on shared state. When multiple agents claim, update, or overwrite the same task list concurrently without claim semantics and idempotent writes, you get silent duplicate work or dropped work. The second failure mode is a compounded blast radius from several agents holding write access at once.
How do I keep an agent team observable?
Merge every agent's transcript and the inter-agent message bus into one timestamped, replayable trajectory. Interleaved private contexts are illegible on their own, so without a merged record you can't answer why the team acted, which blocks evaluation and rollback exactly when you need them.
Does an agent team need per-agent permissions?
Yes. Grant least privilege per agent by role rather than a blanket grant to the team, because several agents coordinating on their own multiply the ways an unreviewed write lands. Pair scoped permissions with checkpoints before high-impact actions so you can roll back one agent without unwinding the whole team.