# AgentSUMO
**An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models**
[](https://pypi.org/project/agentsumo-mcp/)
[](https://github.com/mw-jeong/AgentSUMO/actions/workflows/tests.yml)
[](https://arxiv.org/abs/2511.06804)
[](https://agentsumo.readthedocs.io/en/latest/?badge=latest)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://registry.modelcontextprotocol.io/v0/servers?search=agentsumo)
**[Documentation](https://agentsumo.readthedocs.io)** ·
[Installation](#installation) ·
[Tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html) ·
[Schema](https://agentsumo.readthedocs.io/en/latest/database/index.html) ·
[Tutorials](https://agentsumo.readthedocs.io/en/latest/tutorials/index.html)
*Web interface: conversational planning panel, scenario list, and live simulation status.*
*Geospatial visualization: per-edge metrics, congestion overlays, and trip replay on the 2.5D basemap.*
## Architecture
```
User (natural language)
|
v
Planner Agent (Claude LLM, Interactive Planning Protocol)
|
+--> AgentSUMO MCP Client --> AgentSUMO MCP Server (PyPI: agentsumo-mcp) --> SUMO
|
+--> SQLite MCP Client --> SQLite MCP Server (Anthropic, open source) --> simulations.db
|
+--> Filesystem MCP Client --> Filesystem MCP Server (Anthropic, open source) --> additional XML files
```
The reasoning layer (Planner Agent) lives in this repository. The execution layer (`agentsumo-mcp`) is published to PyPI and installed automatically as a dependency.
## Tool Layer
The AgentSUMO MCP Server exposes **26 tools** grouped into five capability categories that follow the simulation workflow. Full reference at [agentsumo.readthedocs.io/.../tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html).
| Category | Purpose | Representative tools |
|---|---|---|
| **Scenario Generation** | Build a baseline SUMO simulation: OSM → network → trips → routes → run | `osm_extract`, `net_convert`, `trip_generate`, `route_generate`, `sumo_runner` |
| **Policy Experimentation** | Apply infrastructure, demand, and signal-control interventions | `edge_edit_tool`, `reduce_lanes_tool`, `vehicle_generation_tool`, `flow_generation_tool`, `tls_offset_tool`, `tls_adaptation_tool` |
| **Result Analysis** | Convert SUMO XML output to SQLite and render HTML reports | `xml_to_sqlite_tool`, `simulation_report_tool` |
| **Visualization** | Render networks, highlighted edges, and per-edge metric heatmaps | `visualize_net_tool`, `visualize_edge_tool`, `visualize_policy_target_tool`, `visualize_edgedata_tool` |
| **Utility Functions** | Network statistics, routing, road-name ↔ edge-id resolution, OD-coordinate validation, web-search grounding | `network_summary_tool`, `route_analysis_tool`, `validate_od_coordinates_tool`, `web_search_tool` |
## Installation
### Requirements
- Python 3.10 or later
- [SUMO](https://eclipse.dev/sumo/) 1.24 or later (locally installed, with `SUMO_HOME` set)
- Anthropic Claude API key (bring-your-own-key)
- Mapbox access token (used by the web map renderer)
### 1. Install SUMO
**macOS**
```bash
brew install sumo
```
Or download the installer from the [Eclipse SUMO downloads page](https://sumo.dlr.de/docs/Downloads.php).
**Windows** — Download the installer from the [Eclipse SUMO downloads page](https://sumo.dlr.de/docs/Downloads.php).
**Linux (Ubuntu/Debian)**
```bash
sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc
```
### 2. Set up the Python environment
Install [`uv`](https://docs.astral.sh/uv/):
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Clone the repository, create a virtual environment, and install AgentSUMO:
```bash
git clone https://github.com/mw-jeong/AgentSUMO
cd AgentSUMO
# Create a Python 3.12 venv
uv venv --python 3.12
# Activate the venv
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\activate # Windows
# Install AgentSUMO and all dependencies
# (this also pulls agentsumo-mcp from PyPI as a dependency)
uv pip install -e .
```
### 3. Configure environment variables
AgentSUMO reads API keys and the SUMO path from environment variables. The easiest way is a `.env` file at the project root:
```bash
cp .env.example .env
```
Open `.env` in your editor and fill in:
**`ANTHROPIC_API_KEY`** (required) — Claude API key that drives the Planner Agent. Get one at the [Anthropic Console](https://console.anthropic.com/settings/keys).
```
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
**`MAPBOX_TOKEN`** (required for the web UI) — used to render the basemap. Get one at the [Mapbox access tokens page](https://account.mapbox.com/access-tokens/).
```
MAPBOX_TOKEN=pk.eyJ1Ijoixxxxxxxxxxxxxxxxxx
```
**`SUMO_HOME`** (required) — absolute path to your local SUMO installation. The directory must contain `bin/sumo` (or `bin/sumo.exe` on Windows).
```
# macOS (Homebrew)
SUMO_HOME=/opt/homebrew/share/sumo
# macOS (Eclipse SUMO installer)
SUMO_HOME=/Library/Frameworks/EclipseSUMO.framework/Versions/
