AgentSUMO

---

概要

AgentSUMO を使うと、専門知識のない関係者でも自然言語でやり取りしながら、SUMO の交通シミュレーションを設計、実行、分析できます。プランナーエージェントは、抽象的な政策上の問いを実行可能なシミュレーション計画に変換し、Model Context Protocol（MCP）を介して実行し、ウェブダッシュボードを通じて結果を提示します。

• 対話型シナリオ設計 — 政策上の問いを説明すると、実行可能なシミュレーションを作成します
• 政策実験 — 道路閉鎖、車線削減、信号最適化、需要変更
• シナリオ横断分析 — SQL ベースで実行結果を比較し、HTML レポートを自動生成します
• ウェブダッシュボード — 地理空間可視化、時系列グラフ、トリップ再生

デモ

アーキテクチャ

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

推論レイヤー（プランナーエージェント）はこのリポジトリにあります。実行レイヤー（agentsumo-mcp）は PyPI で公開され、依存関係として自動的にインストールされます。

ツールレイヤー

AgentSUMO MCP サーバーは、シミュレーションのワークフローに沿った5つの機能カテゴリに分類される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（ウェブUIに必須）— ベースマップの描画に使用します。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サーバーは、このフレームワークとは独立して、MCP対応の任意のLLMクライアント（Claude Desktop、OpenAIのツールクライアント、Gemini、ローカルLLM）で使用できます：

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 キーが設定されていることを確認してください。キーがない場合、プランナーエージェントは起動しません。

依存関係エラー — 依存関係を再解決してください：

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 をご覧ください。

---