代理旅行工作流程
使用Python和.NET构建的用于旅行规划的生产就绪、无框架的代理工作流 模型上下文协议（MCP）.
🚀 特性
核心能力
- 无框架：使用标准Python库从头开始构建，展示了对代理架构的深刻理解。
- MCP集成：实现用于标准化工具通信的自定义、轻量级MCP客户端/服务器架构。
- 多LLM支持：在OpenAI、Anthropic和Google Gemini模型之间无缝切换。
- 鲁棒稳定性：包括自动重试、安全过滤器处理和连接错误恢复。 - 谷歌双子座2.0：原生支持多模式输入（文本+文件）和优化的指令遵循。 - 灵活的配置不区分大小写 LLM_PROVIDER （例如。， GOOGLE 或 google 两者都工作）。
- 集成工具:
- ✈️ 航班搜索和预订：实时航班搜索（Amadeus API），提供往返支持。 - 智能往返工作流程：选择出境后自动搜索回程航班。 - 🔍 主动日期灵活性：当没有找到航班时，会自动搜索±1-2天并显示所有选项。 - 🧠 智能日期推断：根据“今天”智能推断“1月30日”等日期的年份，处理拼写错误和相对日期，而不会唠叨。 - ✅ 航班选择验证：防止产生幻觉的航班代码-仅使用实际搜索结果中的航班。 - 👥 多乘客定价：自动计算总价×乘客人数。 - 📋 乘客详细信息确认：预订前确认姓名护照配对，以避免混淆。 - 模拟模式：当缺少API键时，回退到模拟数据。 - 智能预订：处理“预订第一个”或航班代码。 - 🚗 汽车租赁：为您的旅行预订车辆。 - ☀️ 天气预报：通过航班搜索自动获取。 - 💳 支付：生产就绪的Stripe集成，自动回退到模拟。 - 自动支付：预订后自动处理付款。 - 📧 邮件确认：通过Stripe将预订确认回执发送到客户的电子邮件。 - 📅 相对日期处理：自然语言日期支持（“明天”、“两天后”、“下周”）。
- 交互式CLI和Web UI：通过简单的终端界面或现代、精致的Web UI与代理交互。
- 🌍 多语言支持：代理人用你写的语言（意大利语、西班牙语、法语、德语等）回复。
- 📜 搜索历史记录：具有localStorage持久性的完整对话历史记录，删除单个对话，并快速访问以前的查询。
生产就绪功能
- 📊 结构化日志记录：JSON格式的日志
request_id,timestamp，以及用于可观察性的上下文元数据。 - 🔭 廊坊可观察性：可选的LLM跟踪和分析-监控延迟、令牌使用和成本。
- ✅ Pydantic 验证：对使用Pydantic模型的所有工具进行严格的类型验证。
- ⚡ 异步架构：使用高性能异步执行
asyncio和FastAPI. - 🔄 错误处理和检索：用于弹性工具执行的指数回退重试逻辑。
- 💾 状态管理：抽象内存接口，具有用于会话持久化的内存中实现。
- 🧪 综合测试：涵盖协议验证、编排器逻辑和完整工作流程的集成测试。
- 🐳 Docker支持：具有安全最佳实践的多阶段Dockerfile（非root用户）。
🛠️ 安装
- 克隆仓库:
git clone https://github.com/yourusername/agentic-travel-workflow.git
cd agentic-travel-workflow- 创建并激活虚拟环境:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项:
pip install -r requirements.txt\[！提示\] 如果使用VS Code，则包括.vscode/settings.json将自动隐藏__pycache__文件夹，以获得更干净的工作空间。
⚙️ 配置
- 复制示例环境文件：
cp .env.example .env- 打开
.env并添加您的API密钥：
# LLM API Keys (At least one is required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
# Optional Service Keys (Mocks used if missing)
FLIGHT_API_KEY=...
FLIGHT_API_SECRET=...
# Payment Processing (Stripe - Optional, uses mock if missing)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...> \[！提示\] > 条纹设置（可选）： > > 1. 在以下网址创建免费帐户 stripe.com > 1. 从获取测试API密钥 仪表盘→ 开发者→ API密钥 > 1. 将它们添加到您的 .env 文件 > 1. 使用测试卡 4242 4242 4242 4242 任何未来到期和CVC > 1. 如果未配置Stripe密钥，应用程序将退回模拟支付 > > 测试您的Stripe配置： > > ``bash > python tests/test_stripe_config.py > `` > > 这将验证您的API密钥是否正常工作。
> \[！提示\] > Langfuse可观察性（可选）： > > 1. 在以下网址创建免费帐户 langfuse.com > 1. 从项目设置中获取API密钥 > 1. 将它们添加到您的 .env 文件： > ``ini > LANGFUSE_SECRET_KEY=sk-lf-... > LANGFUSE_PUBLIC_KEY=pk-lf-... > LANGFUSE_HOST=https://cloud.langfuse.com > ` > 1. 所有LLM呼叫和代理轮换都将被自动跟踪 > 1. 如果未配置Langfuse密钥，则应用程序正常工作（优雅降级） > > **故障排除：** > 如果您遇到痕迹未出现的问题，请确保您正在使用 start_span 和 start_generation` （v3neneneba API），如果自定义跟踪逻辑，因为decorator与异步代理循环不兼容。
> \[！重要\] > 应用程序将自动从以下位置加载这些密钥 .env 文件。在运行应用程序之前，请确保此文件存在于根目录中。
🏃 用法
Web界面（推荐）
使用Uvicorn启动FastAPI web服务器：
uvicorn web_server:app --port 5000 --reload打开浏览器并导航到 http://localhost:5000.
命令行接口
启动异步CLI代理：
python travel_agent/cli.py键入您的旅行请求，然后按Enter键。类型 quit 退出。 你：我想计划下个月去东京旅行。 代理人：我很乐意帮你计划你的东京之旅！你到底打算什么时候去？ 你：从12月10日到12月20日。 代理人：太好了！让我帮你查一下航班和天气。..
Web UI功能
web界面包括：
- 💬 聊天界面：具有消息历史记录的现代响应式聊天用户界面
- 🎨 双子座灵感设计:
- 带有谷歌蓝色调的干净灯光主题 - 材料设计3（MD3）造型指南 - 平滑的立方贝塞尔动画 - 药丸形状的按钮和输入 - 多色渐变英雄文本 - 微妙的阴影和悬停效果
- 🔗 可点击链接：航班预订链接呈现为可点击元素
- 🫧 实时思维指标：带有弹跳点的动画“思考…”文本
- 📱 自适应聊天布局：从欢迎屏幕平滑过渡到干净、基于药丸的对话视图
- 📎 多格式文件上传：直接上传文档（PDF、DOCX、TXT、图像）进行分析。文本文档在服务器端解析以实现最大兼容性。
- 📜 可折叠搜索历史侧栏:
- 开始折叠以获得更清晰的初始视图 - 动画V形图标在切换时旋转 - 上下文菜单（3点）：共享、固定、重命名和删除对话 - 固定对话 将它们放在列表的首位 - 智能时间戳（例如，“500万年前”、“2小时前”和“3天前”） - 确认后清除所有历史记录 - 使用localStorage的持久存储（最多50个对话）
- ✨ 自定义样式模式:
- 破坏性行为的优雅确认对话框 - 输入重命名模式（替换浏览器提示） - Toast通知以获取反馈（取代浏览器警报）
- ✈️ 灵活的航班预订:
- 接受多种选择格式（航班代码、数字或自然语言） - 清晰的确认信息，包括预订参考和详细信息
- 📊 实时状态：代理通过服务器发送的事件处理工具时实时更新
🧪 测试
运行综合测试套件：
# Activate virtual environment first
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run all tests
python -m unittest discover tests -v测试覆盖率:
- 方案验证（Pydantic模型）
- 编排器逻辑（错误处理、重试、内存）
- 完整集成工作流程
📂 项目结构
├── web_server.py # FastAPI Web Server (Entry Point)
├── static/ # Frontend Assets
│ ├── index.html
│ ├── css/
│ └── js/
├── travel_agent/
│ ├── cli.py # CLI Entry point
│ ├── config.py # Configuration management
│ ├── agent/
│ │ ├── llm.py # Async LLM Provider wrappers
│ │ ├── orchestrator.py # Core Async Agent logic
│ │ ├── memory.py # Conversation memory
│ │ └── cache.py # Performance caching
│ ├── mcp/
│ │ ├── protocol.py # MCP JSON-RPC definitions
│ │ └── mcp_server.py # Async MCP Server implementation
│ └── tools/ # Async Tool implementations
│ ├── flights.py
│ ├── cars.py
│ ├── weather.py
│ └── payment.py🐳 部署
使用Docker构建和运行：
# Build the image
docker build -t travel-agent .
# Run the container
docker run -p 5000:5000 --env-file .env travel-agentDocker镜像使用多阶段构建，并作为非root用户运行以确保安全。
📚 教育资源
对于那些学习代理工作流程的人，我已经包括了一个完整的 代码库的注释版本 在 annotated/ 目录。每个文件都有注释，以解释其目的和功能。
关键注释文件：
- 带注释的Web服务器 -具有流式响应的FastAPI应用程序
- 带注释的代理编排器 -核心代理循环
- 带注释的LLM提供者 -多提供者抽象
- 带注释的MCP服务器 -工具注册和执行
📜 API归因
此应用程序使用以下第三方API：
- 开放天气 -天气预报数据（许可证 CC 4.0)
- Amadeus开发者版 -航班搜索和预订数据（测试环境）
有关详细的许可证信息和归属要求，请参阅 许可.md.
🤝 贡献
欢迎投稿！请随时提交拉取请求。