使用说明
🗺️ 项目图集-人工智能旅行计划
使用LangChain、LangGraph和Google Gemini的人工智能旅行计划器。为航班（行李）、天气（OpenMeteo）、活动（Tavily）、住宿（OpenBnB）和愿望清单协调MCP服务器。
🎯 概述
阿特拉斯 是一款基于人工智能的旅行伴侣，它改变了用户规划旅行的方式。用户只需用自然语言描述他们的旅行需求，而不是在多个网站之间来回切换。阿特拉斯：
- 🌤️ 检查天气 在目的地（OpenMeteo API）
- ✈️ 搜索航班 实时（Duffel API v2）
- 🏨 寻找住宿 具有风格匹配功能（OpenBnB MCP-AirBnB的MCP服务器）
- 🎭 发现活动 和隐藏的宝石（Tavily AI搜索）
- 📋 管理愿望清单 用于行程规划
- 📊 提供成本估算 以及行程建议
🏗️ 建筑
高级图表
┌─────────────────────────────────────────────────────────┐
│ User Interfaces │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI Client │ │ Streamlit UI │ │
│ │ (async) │ │ (web) │ │
│ └──────────────┘ └──────────────┘ │
└───────────────┬──────────────────────────┬──────────────┘
│ │
└──────────────┬───────────┘
│
┌──────────────────────▼─────────────────────────┐
│ LangGraph Agent Executor │
│ (Orchestrates tools, manages chat state) │
│ │
└──────────────────────┬─────────────────────────┘
│
┌──────────────────────▼─────────────────────────┐
│ MultiServerMCPClient (langchain) │
│ (Routes requests to specialized servers) │
└──────┬───┬───┬───┬─────────────────────────────┘
│ │ │ │
┌─────────┘ │ │ └─────────────────┐
│ │ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Flight │ │ Weather │ │ Scout │ │Wishlist │ │ Airbnb │
│ Server │ │ Server │ │ Server │ │ Server │ │ Server │
│Port 8002│ │Port 8000│ │Port 8003│ │Port 8001│ │ (npx) │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │ │
┌────▼────────────▼────────────▼────────────▼────────────▼────┐
│ External APIs & Services │
│ Duffel (Flights) │ OpenMeteo │ Tavily │ OpenBnB │ |
└─────────────────────────────────────────────────────────────┘
技术栈
| 层 | 技术 | 目的 |
|---|---|---|
| LLM | 谷歌双子座2.5 Flash/Groq Llama 3.1 | 核心推理引擎 |
| 编排 | LangChain+LangGraph | 代理循环和工具路由 |
| MCP服务器 | FastMCP | 工具协议标准化 |
| 异步运行时 | asyncio | 事件循环管理 |
| 日志记录 | Loguru | 控制台+文件的结构化日志记录 |
| 追踪 | Langfuse（可选） | 可观察性和调试 |
| Web用户界面 | Streamlit | 交互式聊天界面 |
| 命令行界面 | 内置异步 | 基于终端的聊天 |
| 配置 | python dotenv | 环境管理 |
🚀 快速开始
1.安装和设置
python -m venv venv
source venv/Scripts/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
2.配置环境
创建 .env 在项目根目录中：
# LLM (pick one)
GOOGLE_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
# APIs
DUFFEL_API_KEY=your_duffel_key
TAVILY_API_KEY=your_tavily_key
# Optional
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_PUBLIC_KEY=your_public_key
3.启动MCP服务器
打开 4个独立的终端:
python -m src.atlas.servers.flight_server # Port 8002 - Flight search
python -m src.atlas.servers.wish_list_server # Port 8001 - Wishlist management
python -m src.atlas.servers.wheather_server # Port 8000 - Weather forecasts
python -m src.atlas.servers.scout_server # Port 8003 - Activities discovery
或者，如果你有根包装脚本：
python flight_server.py
python wish_list_server.py
python wheather_server.py
python scout_server.py
4.运行应用程序
命令行接口命令模式 （推荐）：
python -m src.atlas.client.client
Web用户界面 （流光灯）：
streamlit run src/atlas/client/app.py
# Opens at http://localhost:8501
📁 项目结构
project atlas/
├── README.md # Documentation (this file)
├── requirements.txt # Python dependencies
├── .env # API keys & config (not tracked)
├── test.py # Test script
│
├── src/atlas/ # Main application package
│ ├── __init__.py
│ │
│ ├── client/ # User Interface Layer
│ │ ├── client.py # CLI agent (async, async main loop)
│ │ └── app.py # Streamlit web UI interface
│ │
│ ├── servers/ # MCP Tool Servers (FastMCP)
│ │ ├── flight_server.py # ✈️ Flight search (Duffel API, Port 8002)
│ │ ├── wheather_server.py # 🌤️ Weather forecasts (OpenMeteo, Port 8000)
│ │ ├── scout_server.py # 🎭 Activities discovery (Tavily, Port 8003)
│ │ └── wish_list_server.py # 📋 Wishlist management (In-memory, Port 8001)
│ │
│ ├── prompt/ # Prompt Templates
│ │ └── agent_prompt.py # System instructions & planning rules
│ │
│ │
│ └── config/ # Configuration (empty - for future use)
│ └── env loader
│
├── tests/ # Test suite directory (if created)
│
├── logs/ # Application logs (auto-created)
│ └── atlas.log # Rotating log file (5MB, 10-day retention)
│
└── __pycache__/ # Python cache (ignored in git)
关键文件
| 文件 | 目的 | 状态 |
|---|---|---|
src/atlas/client/client.py |
具有异步MCP编排的CLI代理 | ✅ 活动 |
src/atlas/client/app.py |
带有会话管理的流线型web界面 | ✅ 活动 |
src/atlas/servers/flight_server.py |
用于航班搜索的MCP服务器（行李） | ✅ 活动 |
src/atlas/servers/wheather_server.py |
MCP天气/预报服务器（OpenMeteo） | ✅ 活动 |
src/atlas/servers/scout_server.py |
用于活动发现的MCP服务器（Tavily） | ✅ 活动 |
src/atlas/servers/wish_list_server.py |
用于愿望清单管理的MCP服务器 | ✅ 活动 |
src/atlas/prompt/agent_prompt.py |
带有计划说明的系统提示 | ✅ 活动 |
⚙️ MCP服务器
| 服务器 | 端口 | 用途 | API |
|---|---|---|---|
| 航班 | 8002 | 搜索航班 | 行李架v2 |
| 天气 | 8000 | 查看预测 | OpenMeteo |
| 侦察兵 | 8003 | 查找活动/地点 | Tavily |
| 愿望清单 | 8001 | 管理目的地 | 内存中 |
| Airbnb | （npx） | 寻找住宿 | OpenBnB |
� API设置
谷歌双子座
- 访问 谷歌AI工作室
- 创建API密钥→ 添加到
.env作为GOOGLE_API_KEY
备选方案： Groq Calma 3.1 （更快）→ GROQ_API_KEY
行李架（航班）
- 注册地址： 达夫尔
- 获取测试/生产API密钥→
DUFFEL_API_KEY
Tavily（活动）
- 注册地址： 塔维利
- 获取API密钥→
TAVILY_API_KEY
OpenMeteo（天气）
✅ 免费，不需要API密钥！
廊坊（可选）
- 注册地址： 浪伏
- 创建项目，添加密钥
.env用于追踪
�️ 发展
添加新服务器
- 创建
src/atlas/servers/my_server.py:
from fastmcp import FastMCP
mcp = FastMCP("My Server")
@mcp.tool()
def my_tool(param: str) -> str:
return f"Result: {param}"
if __name__ == "__main__":
mcp.run(transport="streamable-http", port=8004)
- 创建根包装器
my_server.py:
import sys
sys.path.insert(0, "src")
from atlas.servers.my_server import mcp
if __name__ == "__main__":
mcp.run(transport="streamable-http", port=8004)
- 注册
MCP_SERVERSdict（客户端.py/app.py）：
MCP_SERVERS = {
"my_server": {
"transport": "streamable_http",
"url": "http://127.0.0.1:8004/mcp",
}
}
🐛 故障排除
| 问题 | 解决方案 |
|---|---|
| “连接被拒绝：127.0.0.1:8000” | 在单独的终端中启动所有4台MCP服务器 |
| “找不到DUFFEL_API_KEY” | 创建 .env 使用API密钥文件 |
| “任务将Future附加到不同的循环中” | ✅ 已修复——内部创建了处理程序 setup() |
| 反应缓慢 | 使用Groq Llama代替Gemini（更快） |
| 事件循环已在运行（Streamlit） | ✅ 通过以下方式处理 nest_asyncio.apply() |
| 没有日志显示 | 检查 logs/atlas.log 文件 |
📚 主要特点
✅ 多回合对话 具有状态持久性（LangGraph MemorySaver）
✅ 异步I/O 用于快速API调用
✅ 集中化的日志 （洛古鲁→ 控制台+旋转文件）
✅ 优雅的API漏洞 （例如，如果Tavily失败，则进行模拟搜索）
✅ 键入提示 贯穿始终（Pydantic模型）
✅ 可选可观察性 （Langfuse追踪）
� 资源
旅途愉快！ ✈️🗺️
最后更新日期：2025年12月|版本：1.0.0
