TravelPlanner-Agent

Agente inteligente de planificación de viajes basado en LangGraph + MCP. A través de conversación en lenguaje natural, llama automáticamente a la API de 高德地图 para obtener datos reales de clima y atracciones, agrupa por distancia geográfica mediante clustering y genera itinerarios estructurados de varios días (con marcadores en el mapa y recomendaciones de restaurantes cercanos).

Características

• Orquestación multi-agente: dirigida por grafo LangGraph (extracción de preferencias → recuperación de memoria → juicio de intención → llamada a herramientas → planificación de itinerario)

• Datos reales: conexión a 高德地图 a través de MCP para obtener clima en tiempo real, atracciones (con coordenadas) y restaurantes cercanos

• Planificación de rutas: clustering K-means + cadena de vecino más cercano, las atracciones geográficamente cercanas se organizan el mismo día, visitas sin retrocesos

• Memoria vectorial: modelo de embedding local + ChromaDB, extrae automáticamente preferencias del usuario y las inyecta mediante búsqueda semántica

• Salida estructurada: with_structured_output genera JSON de TripPlan, tarjetas frontend + visualización en mapa de 高德地图

• Regresión Eval: casos fijos de evaluación automática de enrutamiento de intención, salida estructurada, llamada a herramientas y extracción de preferencias

Related MCP server: Ingrids Reisetjenester

Stack tecnológico

Arquitectura

用户输入
  → extract（偏好提取，两级过滤：关键词粗筛 + LLM 精判）
  → retrieve（记忆检索，从向量库查相关偏好注入）
  → route（意图判断：规划 or 闲聊）
  → model（LLM 决定调用工具）
  → tools（MCP 高德：天气 / 景点 / 周边餐厅）
  → plan（K-means 聚类分组 + LLM 结构化输出 TripPlan）
  → 前端卡片 + 地图展示

Inicio rápido

Requisitos del entorno

• Python 3.10+

• Modelo de embedding local (BGE, requiere descarga, ver más abajo)

1. Instalar dependencias

pip install -r requirements.txt

2. Descargar el modelo de embedding local

El proyecto usa BAAI/bge-small-zh-v1.5 para la búsqueda vectorial. Descárgalo desde 魔搭（ModelScope）al directorio models/:

mkdir -p models
python -c "from modelscope import snapshot_download; snapshot_download('AI-ModelScope/bge-small-zh-v1.5', local_dir='./models/bge-small-zh-v1.5')"

3. Configurar variables de entorno

Copia .env.example como .env y completa tus claves:

# DeepSeek（主对话 + 结构化输出 + 偏好提取）
DEEPSEEK_API_KEY=your_deepseek_key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 高德地图（Web 服务 API Key，后端调天气/景点/餐厅）
AMAP_API_KEY=your_amap_web_key

4. Clave JS de 高德地图 para el frontend

Abre app.py y reemplaza YOUR_AMAP_JS_KEY en el HTML por tu clave JS API de 高德地图 (es una clave distinta de la clave de servicio web).

5. Iniciar

python app.py

Abre el navegador en http://localhost:8000 e introduce algo como "ayúdame a planificar un itinerario de tres días en Xi'an".

Estructura de directorios

TravelPlanner-Agent/
├── app.py                # 主后端（FastAPI + LangGraph 图）
├── amap_mcp_server.py    # 高德 MCP Server（天气/景点/周边餐厅）
├── config.py             # 配置（从 .env 读取）
├── eval_app.py           # Eval 回归测试
├── requirements.txt      # 依赖
└── examples/             # 学习版示例（V0-V5 逐步搭建过程）
    ├── main.py           # V0 最小 LLM 调用
    ├── trip_agent.py     # V2 手写 Agent Loop
    ├── graph_agent.py    # V3 LangGraph 版
    ├── v4_memory.py      # V4 手工记忆
    ├── v4_vector_memory.py  # V4 向量检索记忆
    ├── v5_eval.py        # V5 Eval
    └── test_structured.py   # 结构化输出验证

Ejecutar Eval

python eval_app.py

Se ejecutarán 6 casos de prueba que evalúan automáticamente: enrutamiento de intención, integridad de la salida estructurada, llamada a herramientas y extracción de preferencias.

Notas de seguridad

• .env está incluido en .gitignore; no subas claves API reales

• La clave JS de 高德地图 es una clave de frontend, expuesta en texto plano y limitada por la lista blanca de dominios; configura tu propia lista blanca

• Los datos del modelo local y de la base vectorial no se suben al repositorio

Licencia

MIT