DEV Community

Cover image for Exploring Emergence: Building a 100-Agent City Simulation with Local LLMs
Harish Kotra (he/him)
Harish Kotra (he/him)

Posted on

Exploring Emergence: Building a 100-Agent City Simulation with Local LLMs

#ai #tutorial #python #dailybuild2026

What happens when you give 100 autonomous AI agents a few dollars, place them on a real-world city map, and give them complete free will?

This is the question that drove the creation of Emergent City, an open-source, AI-driven city simulation project. Rather than scripting predefined behaviors, this project aims to explore emergence—how macro-economic and geographical patterns naturally arise from simple, localized AI decisions.

In this technical breakdown, I'll explain how I built a buttery smooth, 100-agent simulation running entirely on local LLMs, and how you can fork the project to build your own world.

Here is what it looks like

The Challenge

Running a true multi-agent simulation is notoriously resource-intensive. If you want 100 agents to "think" simultaneously, relying on external APIs (like OpenAI or Anthropic) becomes prohibitively expensive and inevitably hits rate limits.

The goal for Emergent City was strict:

  1. 100% Local: Powered by local, small-parameter models (like qwen2.5:3b via Ollama).
  2. Real-World Geography: Agents must navigate actual city street networks.
  3. Continuous Performance: Even if the AI inference slows down, the frontend visualization must remain locked at a smooth 60 FPS.

The Architecture: Decoupling Consciousness from Physics

To achieve this, the application is strictly partitioned into a Python Backend (FastAPI) and a JavaScript Frontend (Leaflet.js).

The frontend does zero heavy lifting. It simply polls the backend for the current "truth" of the world and interpolates the agent movements visually between those states.

Architecture Diagram

The Round-Robin Execution Model

Even with a highly optimized local model, querying an LLM 100 times per second on consumer hardware is impossible. To solve this, the engine uses a Round-Robin Execution Model for agent "consciousness."

  1. The Physics Step: Every tick, the engine updates the physical simulation—moving agents along their predefined paths, calculating traffic congestion, and deducting driver fuel taxes.
  2. The LLM Step: The engine selects a small, random subset of agents (the "decision-makers"). Only these agents are passed their local context (wallet balance, nearby agents, local traffic) and query the LLM to make a conscious decision (trade, move, or idle).

Execution Model

This ensures the simulation always ticks forward, but decisions permeate through the population gradually, creating a fascinating ripple effect as agents react to traffic jams or economic shifts.

Interactive Features

To make the simulation a true sandbox, I built in interactive "God Mode" APIs:

  • Make it Rain: A simple POST request that air-drops $1,000 into every agent's wallet, instantly causing massive localized inflation at the shops.
  • Traffic Jam: A button that identifies where all active drivers are heading and artificially spikes the congestion score there, forcing the LLM to organically recalculate alternate routes.
  • Smite: By clicking any agent on the Leaflet map, you instantly drain their wallet to zero.

Additionally, using OSMnx, the simulation can hot-swap between major cities dynamically. By hitting the /api/change-city endpoint, the backend pauses, downloads the street network for a new city (e.g., Bengaluru or Tokyo), and respawns the population.

How to Fork & Build Your Own

The entire codebase is open-source and shockingly simple to get running.

Prerequisites:
You need Python 3 and Ollama installed. Pull the base model:

ollama run qwen2.5:3b
Enter fullscreen mode Exit fullscreen mode

Setup:
Clone the repo and install the backend dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Run:
Launch the FastAPI server:

uvicorn main:app --reload
Enter fullscreen mode Exit fullscreen mode

Navigate to http://localhost:8000 and watch your city come alive.

How the output looks

Ideas for Expansion

The magic of this project is its modularity. You can easily extend this by modifying the Agent Prompts and the Python simulation loop.

Here is how you can improve it:

  1. New Agent Personas: Add police to patrol specific nodes, or delivery_drivers that must balance picking up packages with fuel costs.
  2. Dynamic Weather APIs: Inject real-world weather metrics into the LLM prompt. Watch how the agents autonomously decide to seek shelter when you tell the prompt "It is raining heavily."
  3. Public Transit & Economics: Implement rigid bus routes. A massive opportunity exists to see if resident LLMs organically deduce that waiting for the bus is statistically cheaper than walking.

Emergent behavior in multi-agent systems is arguably one of the most exciting frontiers in AI. By scaling down the models and focusing on the systemic rules, we can build highly complex, conscious environments entirely on our own laptops.

Fork the repo and show me what you build!

Top comments (0)