Tutorials#
Video tutorial#
A guided walkthrough of AgentSUMO covering setup, the web interface, issuing natural-language requests, applying policy interventions, and using the SQLite-backed dashboard for cross-scenario comparison.
Launching the web interface#
AgentSUMO ships with a browser-based interface that combines the agent chat, an interactive map, and a database-driven dashboard in a single three-panel view.
source .venv/bin/activate
python web.py
The FastAPI server starts on http://localhost:8000. The backend exposes
RESTful endpoints for files, networks, simulations, and database queries,
plus a WebSocket channel for real-time chat and tool-execution updates.
Three-panel layout#
┌──────────────┬──────────────────────────┬─────────────┐
│ File Explorer│ Map / Dashboard │ Chat │
│ (left) │ (center) │ (right) │
│ │ │ │
│ networks/ │ Mapbox GL JS: │ Agent │
│ trips/ │ - road network │ responses │
│ simulations/│ - density heatmap │ Tool calls │
│ reports/ │ - vehicle replay │ Progress │
│ visualiza- │ - difference compare │ │
│ tions/ │ │ │
└──────────────┴──────────────────────────┴─────────────┘
Left — File explorer#
A hierarchical tree of every artifact AgentSUMO has produced, grouped by
output category: networks, trips, simulations, reports, visualizations.
Clicking a file previews it (XML inline, PNG inline, HTML opens in a new
tab). Clicking simulations.db opens the dashboard.
Center — Map and dashboard#
The center panel hosts the primary view. By default it shows an interactive Mapbox map with the SUMO road network drawn as a GeoJSON layer. The same panel can switch to several other modes:
Heatmap — color-coded edge-level metric (density, speed, emissions) overlaid on the network.
Replay — frame-by-frame vehicle replay using the JSON capture from
sumo_runner. Playback controls support play/pause, seek bar, and speeds of 1×, 5×, 10×, 15×.Difference heatmap — visual diff between two scenarios with symmetric color scaling centered on zero.
Comparative dashboard — KPI table (avg trip duration, waiting time, speed, CO₂), trip-duration distribution histograms, top congested roads, with cross-scenario percentage changes color-coded green/red.
The map’s toolbar exposes basemap switching via and an Edge Selection tool for manual policy targeting.
Agent-driven map control#
The Planner Agent does not render the map itself — it embeds structured markers in its natural-language responses, and the client parses them to trigger map operations. The three markers in the current implementation are:
Marker |
Effect |
|---|---|
|
Geocode the location and drop a pin on the map. |
|
Highlight a route across the listed edges in the given color. |
|
Activate edge-selection mode on the map, prompting the user to click road segments. |
Markers are stripped from the user-visible reply, so the agent’s natural language stays clean while the map updates automatically.
Visual policy targeting#
Rather than typing SUMO edge IDs, you can specify a policy target by clicking on the map:
Click the Select tool in the map toolbar.
Click road segments — each selected edge is added to a selection panel showing its name, lane count, speed limit, and length.
Choose a policy type from the Policy dropdown (lane reduction, road closure, speed change, rerouter installation).
Click Submit. The client sends a structured message to the agent containing the edge IDs and the requested intervention.
The agent applies the corresponding policy tool (
reduce_lanes_tool,edge_edit_tool,speed_limit_edit_tool, etc.) and re-runs the pipeline.
This spatial selection mechanism is the bridge between the visual map and the agent’s tool layer.
Simulation replay#
When sumo_runner executes, it captures vehicle states (position, speed,
heading) at configurable time intervals via SUMO’s TraCI and produces a
frame-indexed JSON file. The replay layer reads that file and renders
vehicles as points with a four-stop speed-based color gradient:
Red — stationary ($v \approx 0$)
Orange — slow ($v \approx 5$ m/s)
Green — normal flow ($v \approx 10$ m/s)
Cyan — free flow ($v \geq 15$ m/s)
Linear interpolation between consecutive frames keeps motion smooth at any playback speed.
Database-driven dashboard#
The comparative dashboard queries simulations.db directly via REST
endpoints:
/api/db/simulations— list everysimulation_id./api/compare?ids=A,B— return KPIs for selected scenarios with percentage deltas vs. the first./api/dashboard?id=baseline— return the full set of metrics for one simulation.
When two or more scenarios are selected, the dashboard displays percentage changes color-coded green (improvement) and red (degradation). Trip-duration distributions are shown as horizontal bar charts with configurable time buckets. The top-N most congested roads are ranked by length-weighted average density, with clickable entries that highlight the corresponding segments on the map.
Automated HTML report#
The dashboard’s Export Report button calls
simulation_report_tool, which renders a self-contained HTML
report from the database. The report includes the full KPI tables, the
trip-duration histograms, the top congested roads, an inline SVG of the
study area with the busiest edges highlighted, and cross-scenario
comparison if multiple simulation_ids are present. Reports are served at
/api/report/<path> and can be opened in a new tab or downloaded for
offline review.
REST API#
The web backend is built on FastAPI and exposes ~25 endpoints covering file
inspection, simulation listing, dashboard data, heatmaps, replay,
traffic-light parsing, and SUMO config loading. They are intended for the
built-in client but are stable enough to support custom front-ends or
analytical integrations. Inspect the OpenAPI schema at
http://localhost:8000/docs when the server is running.
Use cases#
End-to-end walkthroughs that reproduce the paper case studies. Each starts from a plain-English prompt and ends with a quantitative comparison stored in the database.
Complex task. Schedule a one-lane Teheran-ro closure during one of two candidate 30-min windows and compare disruption at vehicle, edge, and network levels.
Agentic task. From an open-ended congestion goal, build the MSG post-event surge from public NYC TLC records and compare Green Wave vs Webster signal policies.
Compare emissions across 0%, 25%, and 75% electric-vehicle adoption rates.
Webster vs. Green-Wave signal timing in a side-by-side comparative report.
See also