第四次作业
智能体项目：能说会做的天气出行规划助手（Weather Agent）
| 这个作业属于哪个课程 | 软件工程 |
|---|---|
| 这个作业要求在哪里 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16760 |
| 这个作业的目标 | 使用现代 AI 工具构建一个具备“语言交互”和“行动执行”能力的智能体（Agent）。 |
| 学号 | 罗晟 3124004103、梁译航3124004101、钱世豪3124004105、黄奕鸣3124004095 |
| GitHub 链接 | https://github.com/3124004103ls/3124004103ls/tree/main/project3-weather-agent |
一、Agent 说明文档
1. 需求描述
本项目旨在构建一个智能出行天气助手。传统的天气 App 只能展示死板的数据，而本 Agent 不仅能通过自然语言与用户进行多轮对话，还能在接收到用户的出行意图时，自主调用外部天气 API（Open-Meteo），获取真实数据，并结合大模型的常识推理，为用户提供穿衣、防晒、带伞等个性化的出行建议。
2. 业务流描述
本 Agent 的核心工作流如下：
- 接收输入：用户在控制台输入自然语言（如：“我想去广州玩，需要带伞吗？”）。
- 意图识别：大模型（Qwen-Max）分析用户语句，识别出查询天气的意图以及目标城市。
- 工具调用（行动）：大模型自动触发 WeatherTool.getWeatherForecast(cityName) 方法。该方法首先调用 Geocoding API 获取城市经纬度，再调用气象 API 获取未来 3 天数据。
- 数据返回：工具将获取到的温度、降水量等 JSON 数据解析后返回给大模型。
- 生成回复（表达）：大模型结合系统提示词（System Prompt）和 API 返回的数据，进行推理，生成自然语言建议（如“广州未来三天高温无雨，建议穿短袖，注意防晒”）。
3. 实现说明
- 技术栈：Java 8 + Maven + LangChain4j 框架 + 阿里云通义千问（Qwen-Max 模型）。
- 核心依赖：使用 langchain4j-open-ai模块通过 OpenAI 兼容模式接入阿里云百炼大模型，确保支持 Function Calling。
- 代码结构：
- Main.java：负责初始化大模型，使用 AiServices 构建带有记忆（ChatMemory）和工具（Tools）的 Agent 接口，并开启控制台交互循环。
- WeatherTool.java：使用 @Tool 注解声明了查天气的方法，内部通过 OkHttp 发起 HTTP 请求获取真实数据。
- 亮点功能：
- 多轮记忆：配置了 MessageWindowChatMemory，Agent 能记住上下文（比如问完广州，问“那边有什么好吃的”，Agent 知道“那边”是广州）。
- 安全配置：API Key 通过系统环境变量（DASHSCOPE_API_KEY）注入，未硬编码在代码中，保障了安全性。
4. 使用示例（功能演示）
启动控制台：
mvn exec:java "-Dexec.mainClass=com.example.Main"
示例 1：基础天气查询与出行建议
你: 我想去广州玩，那边天气怎么样？需要带伞吗？
Agent: 广州未来三天的天气预报如下：
- 10月23日：最高温度31.2℃，最低温度21.9℃，无降水。
- 10月24日：最高温度31.7℃，最低温度21.7℃，无降水。
- 10月25日：最高温度32.4℃，最低温度22.1℃，无降水。
根据预报来看，这三天广州的天气都比较热且干燥，没有降雨。建议穿着轻薄透气的衣物... 此外，由于紫外线可能会很强，记得做好防晒措施。
示例 2：多轮记忆测试
你: 那上海呢？适合去外滩散步吗？
Agent: 上海未来三天的天气情况如下... （Agent 结合温度、风速等给出了适合散步的时段建议）
二、小组分工
- 罗晟：负责整体技术选型与架构设计，编写核心 Agent 逻辑（大模型接入、AiServices 组装），解决 429 限流与 Function Calling 兼容性问题。
- 梁译航：负责外部工具类的编写与调试，实现 Open-Meteo API 的对接、JSON 数据解析与经纬度查询逻辑。
- 钱世豪：负责系统提示词（System Prompt）的设计与优化，确保 Agent 的人设符合“出行助手”的预期，并负责多城市（北上广）场景的测试验证。
- 黄奕鸣：负责环境配置排错（Maven、环境变量）、代码的 Git 版本管理与上传，以及撰写 Agent 说明文档和博客排版。
三、个人心得体会
罗晟（3124004103）
在本次大作业中，我主要负责核心代码的编写。虽然在接入大模型的过程中遇到了很多坎（比如 429 限流、模型不支持工具、Maven 依赖报错），但最终利用 LangChain4j 成功构建了 Agent。看到程序能自己调用天气 API 并且像真人一样给出防晒建议时，我感觉非常有成就感。这让我深刻理解了 AI Agent 中“Function Calling”的底层逻辑，也意识到大模型应用开发不仅是写提示词，更需要扎实的工程能力来打通各个服务。
梁译航
我主要负责天气工具类的 API 对接和代码编写。在实现 getWeatherForecast 的时候，我第一次接触了 Open-Meteo 这种开源气象接口，学会了如何解析复杂的 JSON 嵌套数据。在和罗晟合作的过程中，我明白了“工具”不仅仅是普通的 Java 方法，而是需要按照大模型能理解的规范去定义参数。这次实践让我对如何将外部数据注入给 AI 有了全新的认识。
钱世豪
我负责提示词的优化和场景测试。在这次团队合作中，我发现系统提示词（System Prompt）的设定对 Agent 的表现影响极大。最开始 Agent 只会干巴巴地报数据，后来我在提示词里加入了“你是一个专业的出行助手，需要根据温度建议穿衣和防晒”，它的回答立刻就有了人情味。通过设计各种刁钻的测试场景（比如多轮对话中省略主语），我也验证了 Agent 的记忆能力，这让我对 AI 交互设计产生了浓厚的兴趣。
黄奕鸣
我主要负责环境配置、代码仓库管理和文档整理。在项目前期，大家都被各种环境问题（如 Maven 下载依赖失败、环境变量读取不到、API Key 泄露隐患）折磨得不轻。我通过查阅资料，规范了项目的 .gitignore 和配置方式。在整理文档时，我完整梳理了 Agent 的业务流，深刻认识到一个“能说会做”的智能体，其背后是一整套严密的工程架构。这次团队合作让我体会到了分工与沟通的重要性。
四、项目总结
通过本次项目，我们小组不仅成功用 Java 搭建了一个具备“自然语言对话（能说）”和“外部工具调用（会做）”能力的 Agent，还实现了多轮对话记忆和安全的环境变量配置（加分项）。
在研发过程中，我们遇到了诸如 API 响应限流（429）、模型不支持工具调用等挑战。通过查阅官方文档、切换 OpenAI 兼容接口、并在团队中互相排错，最终不仅克服了困难，还加深了对 MCP（Model Context Protocol）和 LangChain 等现代 AI 开发范式的理解。这为我们接下来的大项目打下了坚实的技术基础。
浙公网安备 33010602011771号