TravelPlanner-Agent

An intelligent travel planning Agent based on LangGraph + MCP. Through natural language conversation, it automatically calls the AMap API to obtain real weather and attraction data, clusters by geographic distance, and generates structured multi-day itineraries (with map markers and nearby restaurant recommendations).

Features

• Multi-Agent orchestration: LangGraph graph-driven (preference extraction → memory retrieval → intent judgment → tool calls → itinerary planning)

• Real data: Connects to AMap via MCP for real-time weather, attractions (with coordinates), and nearby restaurants

• Route planning: K-means clustering + nearest-neighbor chain, geographically close attractions arranged on the same day, no backtracking

• Vector memory: Local embedding model + ChromaDB, automatically extracts user preferences and injects them via semantic retrieval

• Structured output: with_structured_output generates TripPlan JSON, frontend cards + AMap display

• Eval regression: Fixed test cases automatically evaluate intent routing, structured output, tool calls, and preference extraction

Related MCP server: Ingrids Reisetjenester

Tech Stack

Architecture

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

Quick Start

Requirements

• Python 3.10+

• Local embedding model (BGE, needs to be downloaded, see below)

1. Install dependencies

pip install -r requirements.txt

2. Download the local embedding model

The project uses BAAI/bge-small-zh-v1.5 for vector retrieval. Download it from ModelScope to the models/ directory:

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. Configure environment variables

Copy .env.example to .env and fill in your keys:

# 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. Frontend AMap JS Key

Open app.py and replace YOUR_AMAP_JS_KEY in the HTML with your AMap JS API Key (it is a different key from the Web Service Key).

5. Start

python app.py

Open your browser at http://localhost:8000 and enter something like "Help me plan a three-day trip to Xi'an".

Directory Structure

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   # 结构化输出验证

Run Eval

python eval_app.py

Runs 6 test cases, automatically evaluating: intent routing, structured output completeness, tool calls, and preference extraction.

Security Notes

• .env is already in .gitignore; do not commit real API keys

• The AMap JS Key is a frontend key, exposed in plaintext and restricted by domain whitelist; configure your own whitelist

• Local model and vector database data are not committed to the repository

License

MIT