kra35-prismx-agentsumo

<div align="center"> # AgentSUMO **基于大型语言模型的交互式仿真场景生成智能体框架，用于 SUMO 交通仿真** [](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) <img src="assets/hero_overview.png" alt="AgentSUMO overview" width="850"/> **[文档](https://agentsumo.readthedocs.io)** · [安装](#installation) · [工具](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html) · [模式](https://agentsumo.readthedocs.io/en/latest/database/index.html) · [教程](https://agentsumo.readthedocs.io/en/latest/tutorials/index.html) </div> --- ## 概述 **AgentSUMO** 让非专业利益相关者通过自然语言交互设计、执行和分析 [SUMO](https://eclipse.dev/sumo/) 交通仿真。规划智能体将抽象的政策问题转化为可执行的仿真计划，通过模型上下文协议（MCP）驱动，并通过网页仪表板显示结果。 - **对话式场景设计** — 描述政策问题，获取可运行的仿真 - **政策实验** — 道路封闭、车道减少、信号优化、需求变化 - **跨场景分析** — 基于 SQL 的跨运行比较，自动生成 HTML 报告 - **网页仪表板** — 地理空间可视化、时间序列图表和行程重放 ## 演示 <div align="center"> <img src="assets/demo_web_interface.png" alt="Web interface" width="800"/> *网页界面：对话式规划面板、场景列表和实时仿真状态.* <br/><br/> <img src="assets/demo_geospatial.png" alt="Geospatial visualization" width="800"/> *地理空间可视化：每边指标、拥堵叠加层和 2.5D 基图上的行程重放.* </div> ## 架构 ``` 用户（自然语言） | v 规划智能体（Claude LLM，交互式规划协议） | +--> AgentSUMO MCP 客户端 --> AgentSUMO MCP 服务器（PyPI：agentsumo-mcp）--> SUMO | +--> SQLite MCP 客户端 --> SQLite MCP 服务器（Anthropic，开源）--> simulations.db | +--> 文件系统 MCP 客户端 --> 文件系统 MCP 服务器（Anthropic，开源）--> 额外 XML 文件 ``` 推理层（规划智能体）位于此仓库中。执行层（`agentsumo-mcp`）发布到 PyPI 并自动作为依赖项安装。 ## 工具层 AgentSUMO MCP 服务器公开了 **26 种工具**，分为五个能力类别，遵循仿真工作流程。完整的参考资料见 [agentsumo.readthedocs.io/.../tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html)。 | 类别 | 目的 | 代表性工具 | |---|---|---| | **场景生成** | 构建基线 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](https://eclipse.dev/sumo/) 1.24 或更高版本（本地安装，并设置 `SUMO_HOME`） - Anthropic Claude API 密钥（自带密钥） - Mapbox 访问令牌（用于网页地图渲染器） ### 1. 安装 SUMO **macOS** ```bash brew install sumo ``` 或从 [Eclipse SUMO 下载页面](https://sumo.dlr.de/docs/Downloads.php) 下载安装程序。 **Windows** — 从 [Eclipse SUMO 下载页面](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. 设置 Python 环境 安装 [`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" ``` 克隆仓库，创建虚拟环境并安装 AgentSUMO： ```bash git clone https://github.com/mw-jeong/AgentSUMO cd AgentSUMO # 创建 Python 3.12 虚拟环境 uv venv --python 3.12 # 激活虚拟环境 source .venv/bin/activate # macOS / Linux # .venv\Scripts\activate # Windows # 安装 AgentSUMO 和所有依赖项 # （这也会从 PyPI 拉取 agentsumo-mcp 作为依赖项） uv pip install -e . ``` ### 3. 配置环境变量 AgentSUMO 从环境变量中读取 API 密钥和 SUMO 路径。最简单的方法是项目根目录下的 `.env` 文件： ```bash cp .env.example .env ``` 在编辑器中打开 `.env` 并填写： **`ANTHROPIC_API_KEY`** （必填）— 驱动规划智能体的 Claude API 密钥。在 [Anthropic 控制台](https://console.anthropic.com/settings/keys) 获取。 ``` ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` **`MAPBOX_TOKEN`** （必填，用于网页 UI）— 用于渲染基图。在 [Mapbox 访问令牌页面](https://account.mapbox.com/access-tokens/) 获取。 ``` MAPBOX_TOKEN=pk.eyJ1Ijoixxxxxxxxxxxxxxxxxx ``` **`SUMO_HOME`** （必填）— 本地 SUMO 安装的绝对路径。该目录必须包含 `bin/sumo`（或 Windows 上的 `bin/sumo.exe`）。 ``` # macOS（Homebrew） SUMO_HOME=/opt/homebrew/share/sumo # macOS（Eclipse SUMO 安装程序） SUMO_HOME=/Library/Frameworks/EclipseSUMO.framework/Versions/<version>/EclipseSUMO # 例如 1.24.0；使用安装在版本下的目录名称。 # 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. 运行 ```bash # 网页界面（在 http://localhost:8000 打开） python web.py # 命令行界面模式 python chat.py # 清理仿真输出 python clean.py ``` ## 项目结构 ``` AgentSUMO/ ├── agentsumo/ │ ├── agent/ # 规划智能体（Claude 协调器 + 提示） │ ├── client/ # MCP 客户端（AgentSUMO、SQLite、文件系统） │ └── core/ # 配置 ├── agentsumo_mcp/ # AgentSUMO MCP 服务器源代码（也发布到 PyPI） │ └── defaults/ # 打包的固定装置（例如 vehicle_types.add.xml） ├── packaging/mcp/ # agentsumo-mcp 的 PyPI 构建配置 ├── web/ # 网页界面（FastAPI + Jinja2 模板） ├── docs/ # Sphinx 文档源代码 ├── tests/ # 单元测试 ├── assets/ # README 图片 ├── output/ # 运行时工件（自动填充；8 个类别由 .gitkeep 跟踪 │ # simulations/、networks/、trips/、analysis/、reports/、uploads/、visualizations/、additional/） ├── chat.py # 命令行界面入口 ├── web.py # 网页服务器入口 └── .env.example # 环境变量模板 ``` ## 独立使用 MCP 服务器 AgentSUMO MCP 服务器可与任何 MCP 兼容的 LLM 客户端（Claude Desktop、OpenAI 工具客户端、Gemini、本地 LLM）独立使用： ```bash pip install agentsumo-mcp ``` 或使用 [`uvx`](https://docs.astral.sh/uv/guides/tools/) 而无需安装： ```bash uvx agentsumo-mcp ``` 服务器在官方 [MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=agentsumo) 中注册为 `io.github.mw-jeong/agentsumo-mcp`。 ## 故障排除 **SUMO 路径错误** — 验证 `.env` 中的 `SUMO_HOME`。该目录必须包含 `bin/sumo`（或 Windows 上的 `bin/sumo.exe`）。 **API 密钥错误** — 验证 `.env` 中的 `ANTHROPIC_API_KEY` 是否设置为有效的 Claude API 密钥。如果没有，规划智能体将拒绝启动。 **依赖项错误** — 重新解决依赖项： ```bash uv pip install -e . --upgrade ``` **旧令牌文件（已弃用，计划在 0.2.0 中删除）** — AgentSUMO 仍然会回退到项目根目录下的 `claude_api.txt` 和 `mapbox_token.txt`，但这些代码路径现在会在导入时发出 `DeprecationWarning`。对于新安装，请使用 `.env` 工作流。 ## 文档 完整文档位于 **[agentsumo.readthedocs.io](https://agentsumo.readthedocs.io)**。 - [安装](https://agentsumo.readthedocs.io/en/latest/installation.html) — SUMO、Python 3.10+、环境设置 - [工具](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html) — 所有 MCP 工具的参考 - [模式](https://agentsumo.readthedocs.io/en/latest/database/index.html) — `simulations.db` ER 图和列参考 - [教程](https://agentsumo.readthedocs.io/en/latest/tutorials/index.html) — 论文案例研究的演练 ## 引用 如果您在学术工作中使用了 AgentSUMO，请引用： ```bibtex @article{jeong2025agentsumo, title = {AgentSUMO：基于大型语言模型的交互式仿真场景生成智能体框架，用于 SUMO 交通仿真}, 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](LICENSE)。 --- <div align="center"> _在 <img src="assets/logo_kaist.png" alt="KAIST" height="55"/> &nbsp;&nbsp;&nbsp;&nbsp; <img src="assets/logo_caus.png" alt="CAUS" height="55"/> &nbsp;&nbsp;&nbsp;&nbsp; <img src="assets/logo_stil.png" alt="Spatial Tech Innovation Lab" height="55"/> </div>