MultiTown is a Python runtime and browser-based visualisation for cost-aware multi-agent control. Planner, Worker, Specialist, Validator, and Router agents are modelled as buildings and residents of a town, each with its own information, permissions, and cost, and the Arena replays a run so model calls, hand-offs, validation, escalation, token use, and outcomes become visible and comparable.
The premise is that adding agents does not automatically improve accuracy, so a multi-agent system is treated as an organisation and governance problem. A single full-access agent can read the requirements, change the work, and certify itself; an always-on team separates those duties but pays coordination cost on every task. MultiTown studies the middle ground: start with the least expensive valid organisation, check observable work, and activate specialists only when evidence and budget justify it.
Experiment designs are labelled A4 through A8: a fixed full team, a statistical pre-task router, a learned pre-task router, and an execution-time adaptive controller. On a 180-scenario held-out split, the A8 deterministic controller reached 142/180 (78.89%) success at 621.5 tokens per decision, 1.104 s mean and 2.275 s p95 end-to-end latency. Under a preregistered paired comparison, A8 improved success over A4 by 11.67 percentage points (95% bootstrap CI +4.44 to +18.89) while using 76.54% fewer tokens, and over A7 by 11.11 points (CI +4.44 to +17.78) with 54.58% fewer tokens. The measurements come from local Qwen and llama.cpp runs on a frozen synthetic population.
A separate branch transfers the approach to 89 public TeamBench tasks with OS-level role isolation and matched model, task, seed, container, and token settings:
| Strategy | Fully passed | Mean partial | Tokens/task | p95 latency | Energy |
|---|---|---|---|---|---|
| PlanExecute-TB | 16/89 | 0.61603 | 49,579 | 151.96 s | 67.89 Wh |
| Solo-TB | 14/89 | 0.63989 | 84,085 | 237.06 s | 90.94 Wh |
| MT-CapacityRoute-v1 | 20/89 | 0.64180 | 48,296 | 91.06 s | 63.32 Wh |
Reinforcement-learning experiments are recorded with their failures. A masked PPO controller raised success from 23.83% to 34.00% (95% CI +7.87 to +12.47) and cut tokens by 25.41%, but unsafe episodes rose from 15.73% to 66.00%; a hard-shield diagnostic cut unsafe episodes to 5.84% and autonomous success to 0%. A constrained-PPO follow-up recovered safety margins without stable success noninferiority and with higher token use. The repository is code-only: raw experiment records, generated results, checkpoints, datasets, and internal notes are excluded by design.
Features
- Arena replay: a browser view of task packets moving through two towns, showing active buildings, queues, alerts, validation, and delivery; the bundled replay runs with no model, API key, or network call
- Role and permission isolation: Planner, Executor, and Verifier receive different context, tools, and authority instead of one agent certifying its own work
- Cost-aware dispatch: an economical worker starts the task and a stronger specialist or review is activated only when evidence and budget allow
- Validation and recovery: runtime evidence triggers review or escalation, with token guards and deterministic fallback and rollback paths
- Comparable experiments: fixed and adaptive organisations replay on frozen tasks while success, tokens, latency, energy, and safety are recorded
- Command-line entry points: multitown-bench, multitown-validate-serving-trace, multitown-run-a8, and multitown-a10-ppo cover benchmarking, trace validation, routing, and controller training
- Bring-your-own endpoint: model-backed commands expect user-supplied OpenAI-compatible endpoints and model identifiers, and no weights are downloaded
- Public contracts: machine-readable schemas and runtime tests ship alongside the runtime implementation
