An open-source testbed for agent protocols
Test the path, not just the protocol.
A protocol spec says what an agent should do, but NANDA Town records what the agent actually does when things go wrong. You drop any agent into a small simulated town where sellers crash mid-deal, deliveries arrive twice, agent cards drift out of sync with reality, and context gets truncated, all planted deliberately by the town itself. Every run writes evidence you can replay on your own machine, and every failure comes with the exact command that reruns just the broken part.
Three test tiers
The same test runs at three levels of realism.
Testing starts in a fully deterministic simulation and ends against live agents on the open web, and every tier along the way writes the same evidence format and uses the same five verdicts, so a pass means the same thing wherever it was earned.
The Lab
A seeded discrete-event simulation of the whole town runs auctions, voting rounds, consensus protocols, supply chains, and capability spoofing attacks entirely in memory. Because the same seed always produces the same run down to the last event, you can find a regression by diffing two runs instead of arguing about what probably happened.
nandatown run marketplace
The Track
Real agent processes talk to each other over HTTP through a durable mailbox built on leases, fencing tokens, and at-least-once delivery, the same machinery that keeps production distributed systems honest. The town kills a seller process in the middle of a negotiation and then checks that the deal still closes exactly once after the restart.
nandatown run quote-crash-restart
The Path
You point the town at any live A2A agent by URL, and it reads the agent card, invokes the advertised capability, and then repeats the same request to check that the agent does not fulfill the order twice. Everything gets graded against a versioned path profile, so a pass means the same thing no matter who ran the test or when.
nandatown test-agent --url ...
The town is modular
Twelve replaceable protocol layers.
Every interaction in the town passes through these twelve layers, and each one ships with a working default plugin that any scenario can swap for a registered alternative. If you find a failure that fits no existing layer, you can propose a new one and the town will exercise it against every scenario like the rest.
Plugins register with a one-line decorator and resolve by name at runtime, so you can test a new registry design or a different trust model by writing a plugin instead of forking the town.
Replayable evidence
Every verdict comes with evidence you can replay.
Every run writes an evidence bundle whose manifest stores a sha256 hash of every file, so any tampering with the record is detectable by anyone who holds a copy. Validators reach their verdicts from the recorded events alone and never from an agent's self-report, and when the events are not enough to decide, the verdict is Inconclusive rather than a pass, because missing evidence is not proof of anything.
When something breaks, the result names the first broken stage, marks everything after it as unreached rather than failed so that one bug does not read as ten, and prints the exact command that reruns the broken stage on its own.
Anyone can check a bundle without trusting the person who sent it, because
nandatown verify <bundle> recomputes every hash and re-judges every
stage from the raw events on the verifier's own machine.
A badge that expires
The TOWN-TESTED badge is narrow, and it expires.
A passing run produces a receipt signed with an Ed25519 key and stripped of business data like prices and order contents, and the badge renders only while the evidence is fresh, the signature verifies, and the coverage list is complete. The claim itself stays deliberately small, saying only that one capability passed one profile at one point in time.
Install and run
Get started.
Clone and install
You need Python 3.11 or newer, and everything runs locally on your machine with no accounts and no cloud dependencies.
Open the town
The command opens an interactive GUI right in your terminal, and adding --web serves the same interface in a browser instead.
Run the scenarios
The first command runs a full marketplace where deals open, get bid on, and close, and the second deliberately crashes the seller mid-deal to check that the deal still completes exactly once after recovery.
Test a live agent
The command tests any A2A agent that serves an agent card, and you can try it first against the town's own demo agent, which ships with a planted defect so you can watch a failure get caught.
Connect your own work
Connect an agent, a protocol, or a service.
Bring your agent
You point the LLM harness at any OpenAI-compatible endpoint or a local Ollama model, or you use the deterministic MockBrain when you want reproducible runs. The town then injects context truncation and tool errors mid-run to see what your agent actually does when a tool call fails or its context gets cut.
Bring your protocol
The command nandatown import-pr pulls a pull request straight from the
nandatown repo, scans it for secrets, and registers it as a layer plugin, so every
scenario in the town can exercise your protocol before it ever merges.
Bring your service
You wrap a real service and get a run grant that issues a fresh session key for each run, so your controller keys never leave your machine. A passing run earns a signed receipt, and you can mirror the evidence bundle to any host and recover it byte for byte from its content address.