内容
# 瓦伦西亚智慧城市代理
瓦伦西亚智慧城市代理是一个多代理助手，用于回答有关西班牙瓦伦西亚的运营问题。它结合了Google ADK代理、MCP工具服务器、城市开放数据集成、用户记忆、RAG和Web/API前端。
该助手旨在回答以下查询：
- "城市中心附近的交通状况如何？"
- "考虑到天气和空气质量，我今天可以骑自行车吗？"
- "在我的目的地附近找到公共停车场和电动汽车充电点。"
- "我如何从UPV到城市中心？"
- "附近的警察局、报亭、消防栓或公共城市服务在哪里？"
用户界面代理以西班牙语回答，而本仓库的文档以英文编写。
## 亮点
- Google ADK多代理编排，配备用于交通、环境和城市服务的专家代理。
- FastMCP服务器通过SSE公开实时工具。
- 动态编排层，带有基于规则和可选的LLM规划。
- 瓦伦西亚交通、EMT/GTFS、Valenbisi、FGV/地铁-电车数据、天气、空气质量、路由、地理编码和城市服务的实时和近实时集成。
- 持久的用户配置文件内存，用于处理重复需求，如无障碍或旅行偏好。
- React界面的REST API后端。
- 用于本地演示的Chainlit和终端聊天界面。
- 用于工具、编排、响应合成和数据质量的评估框架和回归测试。
## 架构
```text
用户
|
| CLI / Chainlit / React
v
Google ADK根编排器
|
| 路由任务
v
专家代理
|-- 交通专家
|-- 环境专家
|-- 服务专家
|
| 过滤的MCP工具集
v
FastMCP SSE服务器
|
| 域模块
v
瓦伦西亚开放数据、NAP GTFS、Open-Meteo、OpenRouteService、
DuckDuckGo、Neo4j/RAG、本地SQLite内存
```
MCP服务器拥有工具注册表，并公开按类别过滤的工具集。ADK代理通过SSE与其连接，通常在`http://127.0.0.1:8081/sse`。
## 数据和工具域
MCP服务器从`src/domains/`注册工具，并将其分配给代理类别：
- 交通：来自瓦伦西亚开放数据的拥堵总结、监控道路段和交通状态分布。
- EMT和公共交通：巴士线路、站点、到达导向数据和NAP GTFS支持的交通助手。
- 自行车：Valenbisi站点可用性和附近自行车搜索。
- 交通：FGV地铁/电车站点、公共停车场、电动汽车充电点、ZBE状态、装卸区、自行车停车场和相关的城市交通数据集。
- 路由和地理编码：通过OpenRouteService配置时，执行地点搜索和行人/汽车路线计算。
- 天气：通过Open-Meteo获取当前天气、每日总结和预报。
- 空气质量：污染物总结和健康导向的解释。
- 城市服务：警察局、报亭、消防栓、公共设施、旅游、城市服务和其他文档数据集。
- 网络搜索：最近的事件、新闻和公共信息查找。
- 知识/RAG：由RAG管道支持的市政和旅游知识。
## 仓库布局
```text
.
|-- agent_runner.py # 终端聊天/演示运行器
|-- agent_smartcity/ # ADK根和专家代理
|-- evals/ # ADK评估案例和自定义指标
|-- scripts/ # 调试和论文评估助手
|-- smartcity-react/ # React + Vite网页客户端
|-- src/
| |-- api.py # React客户端的FastAPI后端
| |-- frontend.py # Chainlit前端
| |-- mcp_server.py # FastMCP工具服务器和注册表
| |-- domains/ # 城市数据/工具实现
| |-- memory/ # 用户配置文件持久性
| |-- orchestration/ # 规划、执行、证据、合成
| |-- rag/ # 知识/RAG摄取和查询代码
| `-- utils/ # 共享API、GTFS、日志记录、模型助手
|-- tests/ # 单元和集成式回归测试
|-- requirements.txt # Python依赖项
|-- start_server.sh # 启动MCP SSE服务器
`-- start_frontend.sh # 启动Chainlit前端
```
## 需求
- Python 3.11或更新版本。
- Node.js 20或更新版本，用于React/Vite客户端。
- 有效的`.env`文件，用于模型和外部API配置。
- 可选：带有APOC的Neo4j，用于运行图RAG摄取管道。
当前代理代码通过LiteLLM使用PoliGPT作为根和专家代理。MCP服务器配置还验证`GOOGLE_API_KEY`，因此本地运行应提供两个密钥，除非您在代码中调整此验证。
## 安装
```bash
git clone <仓库网址>
cd SmartCity
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```
然后编辑`.env`。实际的本地配置如下所示：
```ini
# ADK代理通过LiteLLM使用的LLM后端。
POLIGPT_API_KEY=您的poligpt_api_key
POLIGPT_API_BASE=https://api.poligpt.upv.es/
# 仍在src/config.py中验证MCP服务器启动时。
GOOGLE_API_KEY=您的google_api_key
AGENT_MODEL=gemini-2.0-flash-exp
AGENT_TEMPERATURE=0.7
# MCP服务器。
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8081
# 可选但推荐用于更丰富的交通答案。
ORS_API_KEY=您的openrouteservice_key
NAP_API_KEY=您的transportes_nap_key
# 默认值通常很好。
VALENCIA_API_BASE_URL=https://valencia.opendatasoft.com
VALENCIA_LATITUDE=39.47
VALENCIA_LONGITUDE=-0.38
ENABLE_CACHE=true
CACHE_TTL=600
NAP_GTFS_TTL=43200
# 可选图/RAG后端。
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j
```
## 运行项目
首先启动MCP服务器。ADK专家代理通过此SSE服务访问工具。
```bash
./start_server.sh
```
该脚本是幂等的。如果已在配置的端口上运行MCP服务器，它将重用它。要故意替换该端口上的进程：
```bash
./start_server.sh --restart
```
### 终端聊天
```bash
python agent_runner.py
```
这将启动一个小型终端UI，带有交互模式和演示模式。
### Chainlit UI
```bash
./start_frontend.sh
```
等效的手动命令：
```bash
chainlit run src/frontend.py -w
```
### React + FastAPI UI
运行API后端：
```bash
uvicorn src.api:app --host 0.0.0.0 --port 8000
```
在另一个终端中，启动React应用程序：
```bash
cd smartcity-react
npm install
npm run dev
```
Vite开发服务器代理`/api`到`http://localhost:8000`。如果您将后端部署到其他地方，请为React客户端设置`VITE_API_BASE_URL`。
### Google ADK接口
```bash
adk web .
```
或：
```bash
adk run agent_smartcity
```
## 可选RAG服务
服务专家可以使用本地服务代理作为默认代理，或在端口`8001`上可用时使用远程A2A RAG服务。
启动RAG A2A服务：
```bash
python src/rag/rag_a2a_server.py
```
强制使用本地服务代理而不是远程A2A服务：
```bash
SMARTCITY_FORCE_LOCAL_SERVICES_AGENT=1 python agent_runner.py
```
运行网页/图摄取管道：
```bash
python src/rag/ingestion/pipeline.py
```
摄取管道爬取配置的瓦伦西亚相关种子URL，清理和分割文档，创建向量数据，并将图信息写入Neo4j。它期望`.env`中的Neo4j设置和APOC支持实体解析后处理。
## API端点
FastAPI后端公开：
- `POST /api/chat`用于聊天请求。
- `POST /api/sessions`创建聊天会话。
- `GET /api/sessions/{user_id}`列出会话。
- `GET /api/sessions/{session_id}/messages`获取会话历史记录。
- `PUT /api/sessions/{session_id}`更新标题或固定状态。
- `DELETE /api/sessions/{session_id}`删除会话。
- `GET /api/profile/{user_id}`检查持久用户内存。
- `DELETE /api/profile/{user_id}/{category}`删除保存的偏好类别。
- `GET /api/data-sources/summary`检查已验证和推断的数据源覆盖范围。
后端在`smartcity_chat.db`中存储聊天会话。用户配置文件内存使用`DATABASE_URL`配置的数据库，默认为本地SQLite。
## 测试
运行完整的配置测试套件：
```bash
python -m pytest
```
有用的聚焦检查：
```bash
python -m pytest tests/test_open_data.py tests/test_adk_patches.py tests/test_response_synthesis.py -q
python -m pytest tests/test_dynamic_orchestrator.py tests/test_orchestration_modules.py -q
python -m pytest evals/evaluate.py::test_mixed_scenarios -vv -s
```
论文/评估助手：
```bash
scripts/run_paper_eval_battery.sh
```
常见的评估环境变量：
```ini
ADK_EVAL_CONFIG=test_config_paper.json
ADK_EVAL_NUM_RUNS=1
EVAL_TIMEOUT_SECONDS=240
SMARTCITY_EVAL_DIAGNOSTICS_DIR=/tmp/smartcity_eval_diagnostics
```
## 配置说明
- `POLIGPT_API_KEY`由`agent_smartcity/agent.py`通过`validate_poligpt_environment()`要求。
- `POLIGPT_API_BASE`默认为`https://api.poligpt.upv.es/`。
- `GOOGLE_API_KEY`当前由`src/config.py`验证启动MCP服务器时需要。
- `ORS_API_KEY`启用通过OpenRouteService的路由计算。没有它，路由答案将受到限制。
- `NAP_API_KEY`启用从西班牙国家访问点下载GTFS以获取更丰富的EMT、FGV和城际数据。
- `MCP_SERVER_PORT`默认为`8081`。API后端通常在`8000`运行；可选的RAG A2A服务在`8001`运行。
- `SMARTCITY_PLANNER_MODE`控制根编排模式。支持的值包括`llm`、`rule_based`和`env`。
- `SMARTCITY_LLM_PLANNER_ENABLED=1`在`SMARTCITY_PLANNER_MODE=env`时启用可选的规划器。
- `SMARTCITY_FORCE_LOCAL_SERVICES_AGENT=1`绕过远程A2A服务代理。
## 开发提示
- 在使用CLI、Chainlit、ADK或API流程时保持MCP服务器运行。
- 如果代码更改后工具模式看起来过时，请使用`./start_server.sh --restart`重启MCP服务器。
- 在演示之前使用`GET /api/data-sources/summary`了解哪些数据集已验证、推断或待处理。
- 在更改一个域模块时，更喜欢聚焦测试，然后在演示之前运行编排和合成测试。
## 许可证
请参阅[LICENSE](LICENSE)。
