Parallel / Swarm / Networked Architectures
Contrast with supervisor: no central decider. Agents read a shared event bus, pick up work asynchronously, write results back. LangGraph explicitly supports "Swarm Architecture" for decentralized, dynamic environments. Matrix (arXiv:2511.21686) represents both control and data flow as serialized messages passed through distributed queues to eliminate the orchestrator bottleneck. The tradeoff is explicit: determinism and traceability for scalability. Swarm fits tasks with many independent sub-problems; it does not fit tasks that need a single coherent plan.
Problem
Supervisor scales to a few workers. What about hundreds? The supervisor itself becomes the bottleneck: every decision about who does what funnels through one agent. One slow plan step stalls the whole system.
Swarm architectures flip the design. Instead of a central planner dispatching work, workers pick work off a shared queue. The "coordination" is baked into the event bus semantics. No orchestrator; the system scales until the queue does.
Concept
The shape
┌──── shared queue ────┐
│ │
┌────────┼────────┐ ◄──────┬───┘
▼ ▼ ▼ │
Worker Worker Worker Worker
A B C D
│ │ │ │
└────────┴────────┴─────────┘
│
▼
results poolNo orchestrator. Each worker repeats: pull a task, process, write result (and optionally enqueue follow-ups).
When swarm fits
- Many independent tasks. Scraping, transforming, classifying. Tasks do not depend on each other.
- Variable-duration work. If some tasks take 100ms and others take 10s, a swarm balances load automatically, fast workers pull next jobs. A supervisor has to anticipate duration.
- Throughput over determinism. You care about total completion time, not strict ordering.
When swarm fails
- Ordered workflows. If step 3 needs step 2's output, a swarm risks step 3 firing before step 2 is done.
- Global-plan tasks. Complex research questions benefit from a planner. A swarm of researchers produces independent facts, not a coherent report.
- Debugging. With no central log and asynchronous work, reproducing a bug is expensive.
Matrix (arXiv:2511.21686)
Matrix is the 2025 paper that takes swarm to its natural conclusion: both control flow and data flow are serialized messages on distributed queues. No central coordinator. Fault tolerance comes from message durability. Scalability is the message broker's problem, not the system's.
Contribution: a programming model where multi-agent coordination is "what message topic does this agent subscribe to?" rather than "which agent does the supervisor pick next?" This makes the system look like a pub/sub event mesh.
Swarm in graph frameworks
LangGraph 2025 docs explicitly describe "Swarm Architecture" as one of the multi-agent patterns: agents are nodes, but edges form a directed graph with cycles and any node can be activated from the pool. A worker picks from available work by condition, not by supervisor assignment.
Failure mode: starvation and hot-spotting
If all workers pull the fastest-available task, long-running tasks never get picked until they are the only ones left. Classic queue starvation.
Mitigations:
- Priority queues with explicit aging (increase priority with wait time).
- Worker specialization: some workers only take "long" tasks.
- Back-pressure: limit how many fast tasks enter the queue.
The content-based routing link
Swarm pairs naturally with content-based routing (Lesson 22). Instead of a generic queue, have one queue per message type. Specialist workers subscribe only to their type. This is the basis for message-bus architectures that scale to thousands of agents.
Build It
code/main.py implements a swarm of 4 worker threads pulling from a shared queue.Queue. Tasks have variable durations (some fast, some slow). The demo contrasts:
- Sequential baseline: one worker processes all tasks serially.
- Fixed assignment: each task pre-assigned to a specific worker (supervisor-style).
- Swarm: workers pull from a shared queue.
Swarm balances load automatically; fixed assignment leaves fast workers idle when their assigned task is slow.
Run:
python3 code/main.pyOutput shows per-worker task counts (swarm distributes unevenly but optimally) and wall-clock times.
Use It
outputs/skill-swarm-fit.md evaluates whether a task should use swarm vs supervisor. Inputs: task independence, duration variance, ordering requirements, debuggability needs.
Ship It
Checklist:
- Priority queue with aging. Prevent long-task starvation.
- Worker idempotency. A task may be pulled more than once if a worker crashes mid-run. Workers must be idempotent.
- Durable queue. Use Kafka, Redis Streams, or a database-backed queue for production.
queue.Queueis in-memory only. - Observability per task. Every task has a trace ID; every worker logs start/end with it.
- Back-pressure. If the queue grows faster than workers drain it, slow the producer.
Exercises
- Run
code/main.py. How much faster is swarm than sequential on the variable-duration workload? How much faster than fixed assignment? - Add a priority queue variant (use
queue.PriorityQueue). Assign priority by task "importance" field. Observe whether low-priority tasks ever starve under continuous load. - Implement a hot-spot detector: log when any worker processes 3× more tasks than the slowest worker. What does that indicate about task-duration distribution?
- Read the Matrix paper (arXiv:2511.21686) abstract and Section 3. Identify one specific tradeoff Matrix accepts (scalability gain) and one it gives up (traceability, determinism).
- Convert the swarm demo to use a
queue.Queueof (task_type, payload) tuples, with workers subscribing only to specific types. What routing rules make sense when tasks are heterogeneous?
Key Terms
| Term | What people say | What it actually means |
|---|---|---|
| Swarm architecture | "Decentralized agents" | Workers pull from shared queue; no central orchestrator. |
| Event bus | "Agents subscribe to topics" | Message broker that routes tasks to workers by type or content. |
| Starvation | "Task never runs" | Low-priority task never gets picked because higher-priority work arrives continuously. |
| Hot-spotting | "One worker drowns" | Load imbalance where one worker gets most tasks. |
| Back-pressure | "Slow down the producer" | Mechanism that signals upstream to stop producing when the queue fills up. |
| Idempotent worker | "Safe to re-run" | A task processed twice produces the same result. Required because workers may crash mid-run. |
| Durable queue | "Survives crashes" | Queue backed by disk or replicated storage; tasks are not lost when a worker crashes. |
| Matrix framework | "Full message-passing swarm" | Both data and control flow are serialized messages on distributed queues. |
Further Reading
- LangGraph workflows and agents, Swarm Architectureexplicit swarm support
- Matrix, A Decentralized Framework for Multi-Agent Systemsfull message-passing swarm
- Anthropic engineering, why supervisor not swarm in Researchwhy a specific production system explicitly chose supervisor over swarm
- AutoGen v0.4 actor-model docsthe event-driven actor rewrite, closer to swarm than v0.2's GroupChat
The full code
Every file for this lesson. Copy it, run it, then change it.
"""Swarm architecture demo: workers pull from a shared queue.
Compares three scheduling strategies on a variable-duration workload:
- sequential (1 worker processes all tasks)
- fixed assignment (each task pre-assigned to a specific worker)
- swarm (4 workers pull from a shared queue)
Swarm balances load automatically; fixed assignment leaves fast workers idle.
"""
from __future__ import annotations
import queue
import threading
import time
from dataclasses import dataclass
@dataclass
class Task:
task_id: int
duration: float
pre_assigned: int # for the fixed-assignment baseline
def fake_work(task: Task) -> str:
time.sleep(task.duration)
return f"task-{task.task_id}-done"
def run_sequential(tasks: list[Task]) -> tuple[float, dict[int, int]]:
t0 = time.time()
counts: dict[int, int] = {0: 0}
for t in tasks:
fake_work(t)
counts[0] += 1
return time.time() - t0, counts
def run_fixed_assignment(tasks: list[Task], n_workers: int) -> tuple[float, dict[int, int]]:
"""Each task is pre-assigned to worker id. Worker processes its tasks serially."""
per_worker: dict[int, list[Task]] = {i: [] for i in range(n_workers)}
for t in tasks:
per_worker[t.pre_assigned].append(t)
counts: dict[int, int] = {i: 0 for i in range(n_workers)}
def worker(wid: int) -> None:
for t in per_worker[wid]:
fake_work(t)
counts[wid] += 1
t0 = time.time()
threads = [threading.Thread(target=worker, args=(i,)) for i in range(n_workers)]
for th in threads:
th.start()
for th in threads:
th.join()
return time.time() - t0, counts
def run_swarm(tasks: list[Task], n_workers: int) -> tuple[float, dict[int, int]]:
"""Workers pull from a shared queue."""
q: queue.Queue = queue.Queue()
for t in tasks:
q.put(t)
counts: dict[int, int] = {i: 0 for i in range(n_workers)}
lock = threading.Lock()
def worker(wid: int) -> None:
while True:
try:
task = q.get_nowait()
except queue.Empty:
return
fake_work(task)
with lock:
counts[wid] += 1
q.task_done()
t0 = time.time()
threads = [threading.Thread(target=worker, args=(i,)) for i in range(n_workers)]
for th in threads:
th.start()
for th in threads:
th.join()
return time.time() - t0, counts
def make_tasks(n_workers: int = 4) -> list[Task]:
"""8 tasks: half fast (0.1s), half slow (0.4s). Pre-assignment is pessimal:
worker 0 gets all slow tasks, others get fast ones."""
tasks: list[Task] = []
for i in range(8):
is_slow = i < 4
tasks.append(
Task(
task_id=i,
duration=0.4 if is_slow else 0.1,
pre_assigned=0 if is_slow else (i - 3) % n_workers,
)
)
return tasks
def main() -> None:
print("Swarm architecture demo — variable-duration workload")
print("-" * 56)
n_workers = 4
tasks = make_tasks(n_workers)
total_work = sum(t.duration for t in tasks)
print(f"{len(tasks)} tasks, 4 slow (0.4s) + 4 fast (0.1s)")
print(f"Total work-seconds: {total_work:.2f}s")
print(f"Ideal parallel time with {n_workers} workers: {total_work / n_workers:.2f}s")
seq_time, seq_counts = run_sequential(tasks)
print(f"\nSequential (1 worker): wall={seq_time:.2f}s, counts={seq_counts}")
fixed_time, fixed_counts = run_fixed_assignment(tasks, n_workers)
print(f"Fixed assignment ({n_workers} workers): wall={fixed_time:.2f}s, counts={fixed_counts}")
print(" worker 0 got all 4 slow tasks; other workers idle after their fast ones.")
swarm_time, swarm_counts = run_swarm(tasks, n_workers)
print(f"Swarm ({n_workers} workers): wall={swarm_time:.2f}s, counts={swarm_counts}")
print(" load balances automatically — slow workers finish first, fast pull next job.")
speedup_vs_seq = seq_time / swarm_time if swarm_time > 0 else float("inf")
speedup_vs_fixed = fixed_time / swarm_time if swarm_time > 0 else float("inf")
print(f"\nSwarm speedup vs sequential: {speedup_vs_seq:.2f}x")
print(f"Swarm speedup vs fixed: {speedup_vs_fixed:.2f}x")
print("\nTakeaway: swarm wins when duration varies and assignment is hard to predict.")
print("Tradeoff: no central trace; debugging requires per-task IDs and durable logs.")
if __name__ == "__main__":
main()