AgentSUMO

---

概述

AgentSUMO 让非专业领域的利益相关者能够通过自然语言交互设计、运行和分析 SUMO 交通仿真。规划器 Agent 会将抽象的政策问题转换为可执行的仿真计划，通过模型上下文协议（MCP）驱动仿真，并通过 Web 仪表板呈现结果。

• 对话式场景设计 — 描述政策问题，即可获得可运行的仿真
• 政策实验 — 道路封闭、车道缩减、信号优化、需求变化
• 跨场景分析 — 使用 SQL 比较多次运行，并自动生成 HTML 报告
• Web 仪表板 — 地理空间可视化、时间序列图表和行程回放

演示

架构

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

推理层（规划器 Agent）位于此代码库中。执行层（agentsumo-mcp）已发布到 PyPI，并会作为依赖项自动安装。

工具层

AgentSUMO MCP Server 提供 26 个工具，分为五类能力，涵盖仿真工作流。完整参考文档见 agentsumo.readthedocs.io/.../tools。

类别	用途	代表性工具
场景生成	构建基线 SUMO 仿真：OSM → 网络 → 行程 → 路线 → 运行	osm_extract、net_convert、trip_generate、route_generate、sumo_runner
策略实验	应用基础设施、需求和信号控制干预	edge_edit_tool、reduce_lanes_tool、vehicle_generation_tool、flow_generation_tool、tls_offset_tool、tls_adaptation_tool
结果分析	将 SUMO XML 输出转换为 SQLite，并生成 HTML 报告	xml_to_sqlite_tool、simulation_report_tool
可视化	渲染路网、高亮路段和逐路段指标热力图	visualize_net_tool、visualize_edge_tool、visualize_policy_target_tool、visualize_edgedata_tool
实用功能	路网统计、路径规划、道路名称 ↔ 路段 ID 解析、OD 坐标验证、网页搜索依据	network_summary_tool、route_analysis_tool、validate_od_coordinates_tool、web_search_tool

安装

要求

• Python 3.10 或更高版本
• SUMO 1.24 或更高版本（本地安装并设置 SUMO_HOME）
• Anthropic Claude API 密钥（自备密钥）
• Mapbox 访问令牌（用于网页地图渲染器）

1. 安装 SUMO

macOS

brew install sumo

或者从 Eclipse SUMO 下载页面下载安装程序。

Windows — 从 Eclipse SUMO 下载页面下载安装程序。

Linux（Ubuntu/Debian）

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc

2. 设置 Python 环境

安装 uv：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

克隆代码仓库、创建虚拟环境并安装 AgentSUMO：

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. 配置环境变量

AgentSUMO 从环境变量读取 API 密钥和 SUMO 路径。最简单的方式是在项目根目录创建 .env 文件：

cp .env.example .env

在编辑器中打开 .env 并填写：

ANTHROPIC_API_KEY（必需）— 用于驱动 Planner Agent 的 Claude API 密钥。请在 Anthropic Console 获取。

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

MAPBOX_TOKEN（网页界面必需）— 用于渲染底图。请在 Mapbox 访问令牌页面 获取。

MAPBOX_TOKEN=pk.eyJ1Ijoixxxxxxxxxxxxxxxxxx

SUMO_HOME（必需）— 本地 SUMO 安装的绝对路径。该目录必须包含 bin/sumo（Windows 上为 bin/sumo.exe）。

# macOS (Homebrew)
SUMO_HOME=/opt/homebrew/share/sumo

# macOS (Eclipse SUMO installer)
SUMO_HOME=/Library/Frameworks/EclipseSUMO.framework/Versions/<version>/EclipseSUMO  # e.g. 1.24.0; use the directory name installed under Versions/

# Windows
SUMO_HOME=C:\Program Files (x86)\Eclipse\Sumo

# Linux
SUMO_HOME=/usr/share/sumo

AGENTSUMO_MCP_OUTPUT_BASE（可选）— 覆盖 MCP 服务写入仿真输出（路网、行程、结果）的基目录。默认为当前工作目录。

AGENTSUMO_MCP_OUTPUT_BASE=/path/to/your/output/dir

4. 运行

# Web interface (opens at http://localhost:8000)
python web.py

# CLI mode
python chat.py

# Clean up simulation outputs
python clean.py

项目结构

AgentSUMO/
├── agentsumo/
│   ├── agent/        # Planner Agent (Claude orchestrator + prompts)
│   ├── client/       # MCP clients (AgentSUMO, SQLite, Filesystem)
│   └── core/         # Configuration
├── agentsumo_mcp/    # AgentSUMO MCP Server source (also published to PyPI)
│   └── defaults/     # Packaged fixtures (e.g., vehicle_types.add.xml)
├── packaging/mcp/    # PyPI build configuration for agentsumo-mcp
├── web/              # Web interface (FastAPI + Jinja2 templates)
├── docs/             # Sphinx documentation source
├── tests/            # Unit tests
├── assets/           # README images
├── output/           # Runtime artifacts (auto-populated; 8 categories tracked
│                     #   via .gitkeep — simulations/, networks/, trips/,
│                     #   analysis/, reports/, uploads/, visualizations/, additional/)
├── chat.py           # CLI entry point
├── web.py            # Web server entry point
└── .env.example      # Environment variable template

单独使用 MCP 服务

AgentSUMO MCP Server 可脱离此框架独立使用，适用于任何兼容 MCP 的大模型客户端（Claude Desktop、OpenAI 工具客户端、Gemini、本地大模型）：

pip install agentsumo-mcp

也可以通过 uvx 使用，无需安装：

uvx agentsumo-mcp

该服务已在官方 MCP Registry 中注册，名称为 io.github.mw-jeong/agentsumo-mcp。

故障排查

SUMO 路径错误 — 请检查 .env 中的 SUMO_HOME。该目录必须包含 bin/sumo（Windows 上为 bin/sumo.exe）。

API 密钥错误 — 请检查 .env 中的 ANTHROPIC_API_KEY 是否设置为有效的 Claude API 密钥。Planner Agent 未配置该密钥时将拒绝启动。

依赖项错误 — 重新解析依赖项：

uv pip install -e . --upgrade

旧版令牌文件（已弃用，计划在 0.2.0 中移除） — 如果缺少对应的环境变量，AgentSUMO 仍会回退到项目根目录下的 claude_api.txt 和 mapbox_token.txt，但这些代码路径现在会在导入时发出 DeprecationWarning。新安装请使用 .env 工作流。

文档

完整文档请见 agentsumo.readthedocs.io。

• 安装 — SUMO、Python 3.10+、环境设置
• 工具 — 所有 MCP 工具的参考文档
• 架构 — simulations.db ER 图和列参考
• 教程 — 论文案例研究的操作指南

引用

如果您在学术工作中使用 AgentSUMO，请引用：

@article{jeong2025agentsumo,
  title         = {AgentSUMO: An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models},
  author        = {Jeong, Minwoo and Chang, Jeeyun and Yoon, Yoonjin},
  journal       = {arXiv preprint arXiv:2511.06804},
  year          = {2025},
  url           = {https://arxiv.org/abs/2511.06804}
}

许可证

MIT。请参阅 LICENSE。

---