【Agent零基础入门课程】从零构建全栈 AI Agent 应用

本文系Datawhale 11月组队学习的学习笔记，笔记内容参考自Datawhale组队学习——Agent零基础入门课程

最近在刷 Datawhale 的 hello-agents 教程，刷到第十三章“智能旅行助手”时，真的有种眼前一亮的感觉。

以往我们写 AI Demo，往往是一个简单的对话框，但这章直接带我们做了一个全栈级别的 AI 应用。不仅有后端复杂的多智能体（Multi-Agent）协作，还有前端的地图交互、行程可视化，甚至还能算预算、导出 PDF。

今天就带大家拆解一下这个项目，看看如何用 Python + LLM 打造一个真正能用的“智能旅行助手”。

---

💡 为什么我们需要 AI 旅行助手？

做过攻略的朋友都知道，规划行程简直是“脑力黑洞”。你要在小红书看景点，去天气网查气温，去携程看酒店，最后还得打开计算器算账。

如果有一个 AI，你告诉它：“我想去北京玩3天，喜欢历史，预算5000元”，它就能：

1. 自动去高德地图搜景点。
2. 查好那几天的天气。
3. 按你的预算找好酒店。
4. 最后把这一切排成一张带有地图和时间表的完美行程单。

这就是我们要做的东西。

技术架构：不只是一个 Chatbot

这个项目采用了经典的前后端分离架构，比起简单的脚本，这更像是一个成熟的互联网产品雏形。

（1）前端层 (Vue3+TypeScript)：负责用户交互和数据展示，包括表单输入、结果展示、地图可视化。

（2）后端层 (FastAPI)：负责 API 路由、数据验证、业务逻辑。

（3）智能体层 (HelloAgents)：负责任务分解、工具调用、结果整合。包含 4 个专门的 Agent。

（4）外部服务层：提供数据和能力，包括高德地图 API、Unsplash API、LLM API。

数据流转过程如下：用户在前端填写表单 → 后端验证数据 → 调用智能体系统 → 智能体依次调用景点搜索、天气查询、酒店推荐、行程规划 Agent → 每个 Agent 通过 MCP 协议调用外部 API → 整合结果返回前端 → 前端渲染展示。

---

拒绝“字典一把梭”，用 Pydantic 定义世界

很多 AI 或者是 Python 初学者（包括以前的我）喜欢用 dict 走天下。但在这种复杂的 Agent 系统里，数据流转非常长：高德API -> Agent -> 后端 -> 前端。而且很多外部 API 返回的数据格式各不相同。

如果不定义数据模型，绝对会为了“这个字段叫 lng 还是 longitude”这种问题调试半天。

项目中使用了 Pydantic 来定义一切数据。比如一个景点（Attraction）：

class Attraction(BaseModel):
    """景点信息"""
    name: str = Field(..., description="景点名称")
    address: str = Field(..., description="地址")
    location: Location = Field(..., description="经纬度坐标") # 嵌套了Location模型
    visit_duration: int = Field(..., description="建议游览时间(分钟)")
    ticket_price: int = Field(default=0, description="门票价格")

这样做的好处不仅是代码清晰，最重要的是：LLM 能够根据这些类定义，更稳定地输出 JSON 格式的数据。前端配合 TypeScript 的类型定义，能做到前后端数据丝滑对接。

单打独斗累死人，试试“多智能体协作”

如果让你写一个 Prompt 让 AI 完成查景点、查天气、找酒店、排行程，那个 Prompt 估计得有一千字，而且 AI 很容易“顾头不顾腚”，漏掉逻辑。

这个项目展示了分治法的魅力。我们设计了 4 个打工“人”（Agent）：

1. 景点搜寻员 (AttractionSearchAgent)：只管根据用户喜好（如“人文”、“自然”）去搜高德 POI。
2. 气象专员 (WeatherQueryAgent)：只管查指定日期的天气。
3. 酒店管家 (HotelAgent)：根据预算和位置推荐酒店。
4. 总策划师 (PlannerAgent)：这是的大脑。它不查数据，只负责拿上面三个人的结果，统筹规划，生成最终的 JSON 行程单。

协作流程如下：
用户请求 -> 景点/天气/酒店 Agent 并行或串行工作 -> 拿到一大堆碎片信息 -> 扔给总策划师 -> 输出完美行程。

代码实现上，这种模块化让调试变得异常简单。天气查不对？只改 WeatherAgent 的 Prompt 就行，不影响其他逻辑。

MCP 协议与工具集成

这一章引入了一个很新的概念：MCP (Model Context Protocol)。

简单说，它是一个连接 LLM 和外部工具的标准协议。以前我们要接高德地图，得自己写 HTTP 请求封装。现在通过 MCP Server 我们只需要简单的配置：

# 创建一个通用的 MCP 工具实例
mcp_tool = MCPTool(
    name="amap_mcp",
    command="npx",
    args=["-y", "@sugarforever/amap-mcp-server"], # 直接调用现成的 MCP 服务
    env={"AMAP_API_KEY": settings.amap_api_key},
    auto_expand=True # 自动展开所有可用工具（搜索、天气、周边等）
)

这样一来，我们的 Agent 瞬间拥有了十几个高德地图的能力，而且多个 Agent 可以共享同一个 MCP 实例，既节省资源又便于管理。

前端交互：让 AI 不再“干等”

以前用AI生成长文，我们只能盯着光标闪烁。但在做 Web 应用时，用户体验（UX）至关重要。

这个项目的后端生成一次计划可能需要 30 秒（毕竟要搜很多次 API）。为了不让用户以为网页卡死，前端做了一个很巧妙的**“伪进度条”**：

// 模拟进度更新，给用户心理按摩
const progressInterval = setInterval(() => {
    if (loadingProgress.value < 90) {
        loadingProgress.value += 10
        // 根据进度显示不同的文案，假装系统在思考不同步骤
        if (loadingProgress.value <= 30) loadingStatus.value = '🔍 正在搜索景点...'
        else if (loadingProgress.value <= 50) loadingStatus.value = '🌤️ 正在查询天气...'
        // ...
    }
}, 500)

虽然是模拟的，但用户体验提升了不止一个档次。此外，前端还利用高德 JS API 实现了地图打点，把 LLM 生成的经纬度直接画在地图上，这种“所见即所得”的感觉非常有成就感。

结语

把这个项目跑通后，我发现它其实是一个通用的资源整合型 Agent模板。
你完全可以把“旅行”换成其他主题，复用这套架构：

• 智能购房助手：地图查房源 + 查学区 + 算贷款。
• 同城活动助手：查展会 + 查交通 + 约饭店。

这一章不仅是在教怎么调用 API，更是在教系统设计。

• 如何用 Pydantic 做数据治理。
• 如何用多 Agent 分解复杂任务。
• 如何用全栈的思维去交付一个 AI 产品。

如果你也想从“写脚本”进阶到“写应用”，Datawhale 的 hello-agents 第十三章绝对值得一试。那种亲手看着 AI 帮你规划好下周五去哪玩的感觉，真的很棒！