TravelPlanner-Agent

LangGraph + MCP に基づくスマート旅行プランニングエージェント。自然言語での対話を通じて、高德地图 API を自動的に呼び出し、実際の天気と観光スポットのデータを取得し、地理的な距離でクラスタリングしてグループ化し、構造化された複数日の旅程（地図のマーカー、近隣のレストラン推薦を含む）を生成します。

機能特性

• マルチエージェントオーケストレーション：LangGraph グラフ駆動（嗜好抽出 → 記憶検索 → 意図判断 → ツール呼び出し → 旅程プランニング）

• 実データ：MCP 経由で高德地图に接続し、リアルタイムの天気、観光スポット（座標付き）、周辺のレストランを取得

• 経路プランニング：K-means クラスタリング + 最近傍チェーンで、地理的に近い観光スポットを同じ日に配置し、移動が順路で往復しないようにする

• ベクトルメモリ：ローカル embedding モデル + ChromaDB で、ユーザーの嗜好を自動抽出し、セマンティック検索で注入

• 構造化出力：with_structured_output で TripPlan JSON を生成し、フロントエンドのカード + 高德地图で表示

• Eval 回帰テスト：固定テストケースで意図の振り分け、構造化出力、ツール呼び出し、嗜好抽出を自動評価

Related MCP server: Ingrids Reisetjenester

技術スタック

アーキテクチャ

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

クイックスタート

環境要件

• Python 3.10+

• ローカル embedding モデル（BGE、ダウンロードが必要、下記参照）

1. 依存関係のインストール

pip install -r requirements.txt

2. ローカル embedding モデルのダウンロード

プロジェクトは BAAI/bge-small-zh-v1.5 をベクトル検索に使用します。魔搭（ModelScope）から 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. 環境変数の設定

.env.example を .env にコピーし、あなたの key を入力します：

# 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. フロントエンドの高德 JS Key

app.py を開き、HTML 内の YOUR_AMAP_JS_KEY をあなたの高德 JS API Key に置き換えます（Web サービス Key とは別の key です）。

5. 起動

python app.py

ブラウザで http://localhost:8000 にアクセスし、「西安の3日間の旅程を計画して」のように入力します。

ディレクトリ構造

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

Eval の実行

python eval_app.py

6 つのテストケースが実行され、意図の振り分け、構造化出力の完全性、ツール呼び出し、嗜好抽出を自動評価します。

セキュリティについて

• .env は .gitignore に追加済みです。実際の API Key をコミットしないでください

• 高德 JS Key はフロントエンド用の key で、平文で公開されるためドメインのホワイトリストで制限します。自分のホワイトリストを設定してください

• ローカルモデルとベクトルデータベースのデータはリポジトリにコミットしません

License

MIT