旅行推荐助手（Travel Agent）

基于 CrewAI + MCP + FastAPI + Next.js 的多工具协作旅行规划 Agent。

用户用自然语言提出旅行问题（例如"我今天想带 3 个朋友去故宫玩，天气如何？我们 4 个人门票总共要多少钱？"），Agent 会自主依次调用天气查询、网页搜索、费用计算三个 MCP 工具获取真实数据，最后输出一份带数据来源标注的结构化旅行方案。

---

目录

• 系统架构
• 技术栈
• 核心设计
• 快速开始
• 开发过程中遇到的问题与解决
• 已知局限与改进方向

---

系统架构

整个系统分为四层，工具与 Agent 之间通过 MCP 协议解耦：

┌─────────────────────────────────────────────┐
│  前端  Next.js + React          :3000       │
│  聊天界面、健康检查、Markdown 渲染            │
└──────────────────┬──────────────────────────┘
                   │  POST /chat  { "query": "..." }
┌──────────────────▼──────────────────────────┐
│  后端  FastAPI + Uvicorn        :8001       │
│  接收请求 → 调度 Agent → 返回结果             │
└──────────────────┬──────────────────────────┘
                   │  run_travel_agent(query)
┌──────────────────▼──────────────────────────┐
│  Agent  CrewAI「旅行规划专家」                │
│  Plan-and-Solve → ReAct → Reflection        │
└──────────────────┬──────────────────────────┘
                   │  MCP over HTTP
     ┌─────────────┼─────────────┐
┌────▼────┐  ┌─────▼─────┐  ┌───▼──────┐
│ 天气 MCP │  │ 计算器 MCP │  │ 搜索 MCP  │
│  :8766  │  │   :8765   │  │  :8767   │
│get_weather│ │ calculate │  │web_search│
└────┬────┘  └─────┬─────┘  └───┬──────┘
     │             │            │
 wttr.in API   纯本地计算   DuckDuckGo
                            + 正文抓取

分层的好处：三个工具是三个独立进程，各自的依赖、崩溃、重启互不影响。Agent 只需要知道 MCP 服务的 URL，完全不需要了解工具内部是怎么实现的。新增一个工具（比如"酒店查询"）时，只要再起一个 MCP 服务并在 Agent 里注册，不需要动后端和前端任何代码。

---

技术栈

| 层次 | 技术 | | --- | --- | | Agent 框架 | CrewAI（Agent / Task / Crew） | | 工具协议 | MCP（Model Context Protocol）、FastMCP | | 后端服务 | FastAPI、Uvicorn、Pydantic | | 前端 | Next.js 16、React、Tailwind CSS、shadcn/ui、react-markdown | | 大模型 | DeepSeek（deepseek-chat） | | 工具实现 | requests、urllib、BeautifulSoup、ddgs |

---

核心设计

1. Agent 行为控制

Agent 的行为主要通过 backstory 和 Task 两层约束来控制。

backstory —— 编码三种思考范式：

• Plan-and-Solve：先规划「天气 → 景点信息 → 费用计算 → 总结建议」四个步骤，再逐步执行，不跳步。
• ReAct：每次工具返回结果后，先分析数据再决定下一步，而不是一次性把所有工具调完。
• Reflection：输出最终答案前做一次自检，逐项确认"天气数据来自天气 MCP / 门票信息来自搜索 MCP / 总价由计算器 MCP 算出"。

Task —— 硬性约束（必须遵守）：

• 天气数据必须来自天气 MCP 的实际返回结果；
• 门票价格和预约规则必须来自网页搜索 MCP 的实际搜索结果；
• 总价必须由计算器 MCP 计算得出，不能手动计算；
• 任何工具调用失败都必须在答案中说明，绝不编造数据。

设计意图是：backstory 负责"怎么想"，Task 负责"必须做到什么"，两层叠加把模型的输出约束在可控范围内。

2. MCP 工具层

三个工具各自是独立的 MCP 服务，用 @mcp.tool() 装饰器注册：

| 工具 | 端口 | 职责 | 关键边界 | | --- | --- | --- | --- | | get_weather | 8766 | 查询指定城市当前天气及未来数日预报 | 超时 10 秒；失败返回错误说明而非抛异常 | | calculate | 8765 | 两数四则运算 | 运算符白名单 + - * /；除零返回错误 | | web_search | 8767 | 网页搜索并抓取正文 | 抓取失败自动退回搜索摘要 |

工具描述即接口：每个工具函数的 docstring 会被 MCP 作为工具说明暴露给模型。所以 web_search 的 docstring 用 Args: 格式写清楚了每个参数的含义——这是给模型看的，不是给人看的注释。

3. 前后端集成

后端（FastAPI）

• POST /chat 接收 {"query": "..."}，返回 {"query", "response", "status"}；
• GET /health 供前端做可用性探测；
• Agent 执行是同步阻塞的，用 asyncio.to_thread() 包一层，避免阻塞事件循环；
• CORS 允许 http://localhost:3000（前端地址）；
• 空 query 返回 400，Agent 执行异常返回 500。

前端（Next.js）

• 聊天式界面，消息用 react-markdown 渲染（因为 Agent 返回的是 Markdown）；
• 顶部实时显示后端健康状态（/health 探测）；
• 提供 4 个快捷提问按钮，方便快速验证不同场景；
• 请求期间锁定输入框，避免重复提交。

4. 健壮性处理

• 三个工具函数全部用 try / except 兜底，失败返回错误字符串而不是让进程崩溃；
• calculate 校验运算符白名单并单独处理除零；
• get_weather 设置 10 秒超时；
• 后端启动时主动探测三个 MCP 服务的端口，未启动则打印明确的警告信息（只警告不阻断，方便"先起后端、再补服务"的调试节奏）；
• 后端区分 400（参数问题）和 500（Agent / MCP 故障），便于定位问题出在哪一层。

---

快速开始

1. 安装依赖

pip install crewai fastapi uvicorn pydantic python-dotenv fastmcp requests beautifulsoup4 ddgs

前端依赖：

cd travel-agent-web/my-app
npm install

2. 配置环境变量

travel-agent-web/backend/.env：

DEEPSEEK_API_KEY=你的_API_Key

travel-agent-web/my-app/.env.local：

NEXT_PUBLIC_API_BASE=http://localhost:8001

3. 按顺序启动

⚠️ 必须先启动三个 MCP 服务再启动后端，否则 Agent 找不到工具会直接报错。

① 三个 MCP 工具服务（各自开一个终端）

python tools/get_weather.py      # :8766
python tools/calculate.py        # :8765
python tools/websearch_mcp.py    # :8767

② 后端 API

cd travel-agent-web/backend
python travel_agent_api.py       # :8001

启动后可访问 http://localhost:8001/docs 查看自动生成的接口文档。

③ 前端

cd travel-agent-web/my-app
npm run dev                      # :3000

打开 http://localhost:3000 即可对话。

4. 命令行快速验证

不想起前端的话，可以直接跑 Agent 的原始 Demo：

cd travel-agent-web/backend
python crewaidemo.py

crewaidemo.py 与后端用的是同一套 Agent 配置，只是把问题和输出写死了，适合在不启动前端的情况下验证「MCP 链路是否通」。

---

开发过程中遇到的问题与解决

问题 ①：模型不按预期的格式输出

现象

Task 的 expected_output 里明确要求输出四段式结构并且"注明数据来源"，但早期版本跑出来的结果里：

• 完全没有"（数据来源：天气 MCP）"这类标注；
• 结构变成了「天气 / 门票费用 / 总花费 / 温馨提示」，和要求的四段式对不上。

排查

把 expected_output 的条目和实际输出逐条对照，确认问题不在工具层——三个工具都正常返回了数据，是模型拿到数据后没有按要求组织输出。也就是说，约束写得不够"可执行"：expected_output 描述的是"成品长什么样"，但没有要求模型在输出前自己检查一遍。

解决

在 backstory 里加入一个明确的 Reflection 步骤，要求模型在给出最终答案前逐项自检：

在输出最终答案前，你进行 Reflection 检查：确认天气数据来自天气 MCP、门票信息来自网页搜索 MCP、总价由计算器 MCP 计算，并核对人数、单价和总价是否匹配。

效果

加入之后，最终版输出的开头会先出现一段自检清单：

好的，所有数据已获取完毕。下面进行 Reflection 检查： ✅ 天气数据：来自天气 MCP，查询了北京市今日天气…… ✅ 门票信息：来自网页搜索 MCP，搜索到故宫成人票价格为旺季 60 元/人…… ✅ 费用计算：由计算器 MCP 完成，60 × 4 = 240 元，人数（1+3=4 人）与单价匹配。 ✅ 所有工具调用成功，无编造数据。

正文里的每一部分也都带上了「（数据来源：天气 MCP）」这样的标注。

收获：光靠 expected_output 描述"要什么"是不够的，得在 backstory 里给模型一个可执行的检查动作，它才会真的去核对。

---

问题 ②：工具名对不上，Agent 找不到工具

现象

在 Task 的描述里需要写出要调用的工具名，但一开始并不知道该填什么。CrewAI 会根据 MCP 服务的 URL 自动拼接出工具名——http://localhost:8766/mcp 上的 get_weather 被注册成了 localhost_8766_mcp_get_weather。这个名字是拼出来的，没有任何文档写它，凭空猜不出来。

排查

把 Agent 的 verbose=True 打开，观察 Agent 执行日志，从日志里看到实际注册的工具名是 localhost_8766_mcp_get_weather、localhost_8765_mcp_calculate、localhost_8767_mcp_web_search 这种形式。

解决

先把 travel_agent_api.py 里的 Agent 配置抽成一份独立的 Demo（crewaidemo.py），把问题写死、直接跑命令行，用 verbose 日志把三个工具的真实名字探出来，再抄进 Task 的描述里。

这也是 crewaidemo.py 至今保留在项目里的原因——它不只是个旧文件，而是**"工具名探测 + MCP 链路验证"的脚手架**。改动 Agent 配置后先跑它确认链路通，再起后端和前端，比每次都把三层全拉起来调试快得多。

收获：涉及框架自动生成标识符的地方（工具名、事件名等），先把中间过程的日志打开看一眼。

---

问题 ③：网页搜索抓回来的正文质量差

现象

web_search 最初是直接把抓到的网页正文塞给模型的，但实际结果很不稳定：

• 搜索"故宫门票价格"，第一条结果是团购类网站，正文里混着大量导航栏、脚本、页脚文字；
• 真正有用的价格信息被淹没，或者抓到一半就断在无关内容上；
• 有时抓取失败，返回的内容过短，模型拿不到任何有效信息。

排查

把搜索结果的原始返回打出来对比，确认问题出在 fetch_page_content 没有做任何清洗，把整个页面的可见文本原样返回了。

解决

给 fetch_page_content 加了一套净化与降级逻辑：

1. 用 BeautifulSoup 解析后，先删除 script、style、nav、header、footer 这些噪声标签；
2. 按行切分文本，只保留长度 ≥ 30 字的段落，滤掉导航链接之类的碎片；
3. 累计长度达到上限（2000 字）就停止，避免把整个页面塞进去；
4. 降级策略：如果清洗后的正文不足 100 字，说明没抓到有效内容，返回 None，由调用方退回使用搜索引擎给出的摘要，而不是把一堆无意义的碎片丢给模型；
5. 整段包在 try / except 里，抓取超时或异常时同样退回摘要。

效果

正文的噪声大幅减少，价格、开放时间这类关键信息能被稳定提取出来。

收获：给模型喂数据之前先做一遍清洗，"喂什么"往往比"怎么问"更影响最终效果。

---

问题 ④：模型绕过计算器自己做心算

现象

同一个案例里，主要的门票总价（60 × 4 = 240 元）确实走了计算器 MCP，日志里也能看到调用记录。但模型在补充说明里写了这么一句：

如需参观珍宝馆或钟表馆，每人各加 10 元，4 人共需额外 80 元，总费用则为 320 元。

这两个数字（80 和 320）并不是计算器算出来的——工具日志里 calculate 只被调用了一次。模型在"可选附加项"这种次要计算上，自己心算就给出了结果。

排查

对照工具调用日志和最终输出，发现输出里的数字比工具调用次数多，确认存在"模型自行计算"的情况。

解决

在 Task 的约束条件里显式加了一条硬约束：

总价必须由计算器 MCP 计算得出，不能手动计算。

同时把"每步完成后分析结果再进入下一步"的步骤描述写得更明确，引导模型在每一步都走工具。

效果

把约束范围从"最终总价"扩大到所有金额（含单价×人数、可选项、附加费用），并明确写出"禁止自行心算任何数字"。

收获：提示词约束的覆盖范围必须写具体。原来只写了"总价"，模型就只对"总价"守规矩，对"可选项"照样自由发挥——约束写多细，模型就守多细。

---

问题 ⑤：模型构造的搜索关键词年份漂移

现象

同一份代码、同一个目的地，模型自己构造的搜索词在两次运行中并不一致：

• 一次是「北京故宫门票价格 2024 成人票 预约规则」
• 另一次是「故宫门票价格 2025年」

搜索词由模型自主构造，年份会漂移。而门票价格是随年份变化的，年份过期就可能检索到历史价格表，进而影响费用计算结果的准确性。

排查

检查后发现，年份不是代码传进去的，是模型自己"想"出来的——它只能依据训练数据中的时间认知去猜当前是哪一年。所以问题的根源是：本该由系统提供的上下文，被交给了模型去猜。

解决

把"当前是哪一年"从模型的猜测变成系统的确定输入：

1. run_travel_agent() 中用 date.today() 取系统当前日期；
2. 在 Task 描述开头注入「当前日期：2026年09月15日」；
3. 在步骤 2 中加一条明确指令：「搜索关键词中必须包含当前年份（2026 年），避免检索到过期价格」。

效果

搜索词中的年份由系统时间决定，不再依赖模型的知识截止时间推断。crewaidemo.py 同步做了相同修改，保持两处 Agent 配置一致。

收获：凡是"模型不该猜、而系统本来就知道"的信息（当前日期、用户身份、权限范围、价格表），都应该由代码直接注入 prompt，而不是指望模型推断。

---

已知局限与改进方向

| # | 局限 | 改进方向 | | --- | --- | --- | | 1 | 提示词已要求所有金额必须走计算器，但模型是否严格遵守无法在代码层保证 | 在输出后做数字校验，拦截未经计算器得出的数字 | | 2 | Agent 执行是同步阻塞的，长任务会占满一个线程 | 若并发量上来，改为异步执行 + 任务队列，前端轮询或走 SSE 推送 | | 3 | 单 Agent 串行调用三个工具，无法并行 | 三个工具之间无依赖关系时可并行调用，缩短响应时间 | | 4 | 当前无对话记忆，每轮请求都是独立的 | 引入会话 ID，把历史消息一并传给 Agent，支持多轮追问 | | 5 | MCP 服务需手动逐个启动，尚无统一启动脚本 | 写一个脚本一次性拉起三个 MCP 服务与后端 |

---

目录结构

.
├── tools/                          # 三个独立 MCP 工具服务
│   ├── calculate.py                #   计算器      :8765
│   ├── get_weather.py              #   天气查询    :8766
│   └── websearch_mcp.py            #   网页搜索    :8767
│
└── travel-agent-web/
    ├── backend/
    │   ├── travel_agent_api.py     # CrewAI Agent + FastAPI 服务  :8001
    │   ├── crewaidemo.py           # 命令行 Demo（工具名探测 / 链路验证）
    │   └── travel_api.md           # 接口文档
    │
    └── my-app/                     # Next.js 前端  :3000
        └── src/app/
            ├── page.tsx            # 聊天界面
            └── layout.tsx

---

说明

本项目为个人学习实践项目，用于验证 Agent 行为控制与 MCP 工具集成的完整链路。

工具层的数据来源为公开接口（wttr.in 天气、DuckDuckGo 搜索），门票价格等信息以搜索结果为准，不作为实际出行决策依据。