Map / Outline
Multi-agent patterns
Several model roles with separate context, tools, and budgets, coordinated by code.
What it is and why it exists
What
A multi-agent system splits work across model calls that each have their own instructions, tools, and context. Coordination is done by an orchestrator: fan-out to workers, independent judges, or handoffs between specialists.
Why
One context window cannot hold everything, and one role cannot check itself. Separate roles give isolation of context and independence of judgment. They also multiply cost and failure modes, so each split needs a measured reason.
How it works
- Orchestrator and workers: the planner fans out sub-tasks as nodes, each with a narrow tool set, then merges the results.
- Independent judges: two separate votes on whether a claim is supported by its source. A claim leaves service only when both fail it.
- Maker and checker: one model writes, a different and stronger model checks against the source.
- Role by dimension: specialist prompts selected by the kind of question, sharing one tool registry.
- Scheduling is part of the design. Background agents pause while a live request holds the busy marker.
Where it sits in the build order
Needs first
- Harness engineeringA sub-agent is a harness loop run as a node. You need one working loop before you can run several.Build out of order Stub it with: Two sequential model calls with different system prompts.
- SkillsRoles are defined by scoped instructions. Skills are the mechanism for scoping them.Build out of order Stub it with: Hard-coded role prompts.
- EvaluationEvery added agent adds cost and latency. Only an eval can show that a split improved results.Build out of order Stub it with: Manual comparison on five questions. Enough to learn the pattern, not enough to justify it.
Unlocks
Nothing depends on this. It is an end point of the map.
In the reference build
| Path | Role |
|---|---|
| apps/agent-server/graph.py | The executor that runs concurrent nodes. |
| apps/agent-server/nightly/claim_verify.py | Two-vote judging. |
| apps/agent-server/skills/spending-orchestration.md | Instructions for decomposing a multi-part data question. |
| ROLE-DIMENSION-ARCHITECTURE-v2.md | Design for specialist roles by question dimension. |
The same idea on other platforms
| Platform | How this module maps |
|---|---|
| Databricks | Multi-agent supervisors are available as a managed pattern, and LangGraph or the OpenAI Agents SDK run inside a deployed agent. Each sub-agent can be its own serving endpoint or a function. |
| IBM watsonx | Orchestrate agents list collaborators and route work among them. This is the platform's core pattern. |
| Codex | Subagents run tasks in separate contexts. The Agents SDK supports handoffs between agents. |
| Cursor | Subagents and background agents run tasks in parallel with their own context. |
| Claude Code / Agent SDK | Subagents have their own context window and tool set, defined in files. The SDK can spawn them from code. |
| Another machine | The wave executor is plain Python. Sub-agents are functions. |
Explain it back
Answer aloud first. Then open the answer and compare.
Give one good reason and one bad reason to add a second agent.
A strong answerGood: you need an independent check, or a sub-task's context would crowd out the main one. Bad: the architecture diagram looks more capable. Without an eval showing a gain, it is only more cost.
Why two votes for claim verification?
A strong answerA single judge's error would remove true claims. Requiring both to fail trades some missed bad claims for far fewer wrongly removed good ones.
From the live build
Recent changes and files the sync job filed under this module.
- The Role Dimension — Architecture v2
- The Role Dimension — Architecture