> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-agent patterns

> Coordinating multiple agents within one task — when to compose, when to keep separate.

A complex task often has more than one kind of work — planning, coding,
testing, writing. You can do it all with one agent and a long system
prompt, but it's usually better to split into specialized agents that
hand off to each other. This page covers the patterns that work.

## Why split

A single agent has to be everything: a planner, a coder, a writer, a
reviewer. The system prompt grows; the tool catalog grows; the model
gets distracted between modes. Performance degrades.

A multi-agent setup gives each agent a focused identity and a focused
toolset. You also get cleaner traces — when something goes wrong, you
can tell which agent it went wrong in.

## The shapes that work

### Planner + executor

The most common pattern. A planner agent breaks the task into steps; an
executor agent runs each step.

```mermaid theme={null}
flowchart TB
    Msg["user message"]
    Plan["planner reads task,<br/>emits charter"]
    Step{"for each step<br/>in charter"}
    Exec["executor runs<br/>the step"]
    Done["planner concludes<br/>when charter done"]
    Msg --> Plan --> Step
    Step -- next step --> Exec --> Step
    Step -- charter complete --> Done
```

The Engine has built-in support for this pattern via the
[planner sub-agent](../agents-and-tools/agent-loop) and `PLANNER_MODEL`.

### Specialist team

A coordinator agent dispatches to specialists.

```mermaid theme={null}
flowchart TB
    Coord["coordinator<br/>(gpt-4o)"]
    Coder["coder<br/>(sonnet)"]
    Research["researcher<br/>(gemini)"]
    Writer["writer<br/>(sonnet)"]
    Coord --> Coder
    Coord --> Research
    Coord --> Writer
```

Each specialist has its own system prompt and tools. The coordinator
holds the conversation with the user; specialists do the focused work.

### Reviewer-of-reviewer

For quality-critical output, an agent produces work and a reviewer
agent critiques. Optionally, a third agent arbitrates disagreements.

```mermaid theme={null}
flowchart LR
    Draft["draft agent"]
    Reviewer["reviewer agent"]
    Final["final"]
    Arb["arbitrator"]
    Draft --> Reviewer --> Final
    Reviewer -. on conflict .-> Arb --> Final
```

Useful for legal review, content moderation, code review at production
quality.

### Pair-of-pairs (planner + critic, executor + tester)

Each functional role has a critic. The planner is critiqued by a plan-
critic; the executor is critiqued by a test-runner. The system as a
whole is more reliable than any single agent.

## How the Engine implements this

The Engine ships with one main agent loop. Sub-agents run as nested
calls. From the outside, you see one `/execute` and one stream of
events; internally, the main loop's tool calls invoke sub-agents:

```
event: tool_call
data: {"tool": "delegate_to_coder", "input": {"task": "implement auth"}}

[sub-agent runs internally — its events surface as nested]

event: tool_result
data: {"output": "Done. PR opened: #1234"}
```

The sub-agent gets its own system prompt, tools, and (optionally) its
own model.

## Memory across agents

In one task, all agents share memory:

* The same brain.
* The same conversation history.
* The same working memory.

This is usually what you want — the planner sees what the coder did
because the coder's tool calls are in shared context.

If you want isolation (e.g. a critic agent that should evaluate
independently), use a fresh `task_id` for the critic and pass the work
to be reviewed as the user message.

## Costs and limits

Multi-agent setups multiply token use. Each sub-agent call has its own
context — its own system prompt, its own tools, its own assembled
history. The benefit (focused performance) usually outweighs the cost,
but the math matters at scale.

Ways to keep cost down:

* **Use cheaper models for planners and critics.** Set `PLANNER_MODEL`
  and similar to a smaller model.
* **Cap depth.** Don't allow infinite delegation. Set a maximum depth
  in the parent's system prompt.
* **Cache aggressively.** Sub-agents with stable system prompts hit
  cache as well as the main agent does.

## Anti-patterns

### Too many specialists

If your team has 8 specialists, they spend more time coordinating than
doing the work. A general-purpose agent with good tools beats a council.
Stop at 2–4 specialists for any one task.

### Specialists that don't specialize

If the planner and the executor have nearly the same system prompt and
nearly the same tools, you don't have two agents — you have one agent
called twice. Either differentiate or merge.

### Talking among themselves

If specialists end up in a loop debating each other, you've built a
committee. Pick a tiebreaker (the coordinator decides, the user
decides, a fixed rule decides). Don't let the agents reach consensus
endlessly.

### Hidden state between agents

If specialist A relies on side effects from specialist B that aren't in
shared context, your system is fragile. Make all hand-offs explicit
through the shared memory or through the parent's tool calls.

## Patterns by use case

### Coding agent

```mermaid theme={null}
flowchart TB
    Planner["planner<br/>(sonnet 4.7)"]
    Explorer["explorer (haiku)<br/>reads codebase, builds map"]
    Impl["implementer (sonnet 4.7)<br/>writes the change"]
    Test["tester (haiku)<br/>runs tests, reports results"]
    Review["reviewer (sonnet 4.7)<br/>reviews the diff"]
    Planner --> Explorer
    Planner --> Impl
    Planner --> Test
    Planner --> Review
```

The cheaper models do the throughput-heavy work (reading, testing). The
strong model does design and review.

### Research agent

```mermaid theme={null}
flowchart TB
    Planner["planner"]
    Searcher["searcher (gemini, long context)<br/>broad web/doc search"]
    Synth["synthesizer (sonnet)<br/>distills findings"]
    Check["fact-checker (haiku)<br/>verifies citations"]
    Planner --> Searcher
    Planner --> Synth
    Planner --> Check
```

Gemini's long context shines for searcher. Sonnet's reasoning shines
for synthesis. Haiku's speed shines for fact-checking individual claims.

### Customer support agent

```mermaid theme={null}
flowchart TB
    Cls["classifier (haiku)<br/>routes tickets by category"]
    T1["tier-1 agent (haiku)<br/>answers common questions"]
    T2["tier-2 agent (sonnet)<br/>handles escalations,<br/>can use MCP tools"]
    Cls --> T1
    Cls --> T2
```

Cheapest model handles the bulk; strong model handles the hard cases.

## See also

* [The agent loop](./agent-loop) — what's happening inside one agent.
* [Cost and latency](../build-with-engine/cost-and-latency) — the
  multipliers that matter.
* [Build a coding agent](../guides/build-a-coding-agent) — a concrete
  multi-agent example.