第十六章毕业设计：基于 Hello-Agents 框架构建属于你的多智能体应用-迪斯科星球

第十六章毕业设计：基于 Hello-Agents 框架构建属于你的多智能体应用

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

本文是 Hello-Agents 教程的收官之章实战指南，围绕「毕业设计」这一核心主题，完整讲解从选题、环境准备、Fork 仓库、项目开发到提交 Pull Request 的全流程，并以仓库中真实收录的共创项目Co-creation-projects/jjyaoao-CodeReviewAgent/为样板逐行拆解。读完本文，你将掌握用 HelloAgents 框架独立设计并交付一个可运行的开源智能体应用的全部技能：包括自定义工具（Tool）、智能体组装、Notebook 工程化、README 与依赖清单规范、大文件处理策略，以及通过开源协作被社区评审与收录的完整路径。

一、为什么需要一场「毕业设计」

学习技术最好的方式不是看教程，而是动手实践。在 docs/chapter16/第十六章毕业设计.md 中，Hello-Agents 教程把最后一章定位为一次综合能力训练：前面 15 章你学习了智能体核心概念、多种范式、工具系统、记忆机制、通信协议、强化学习训练与性能评估，第 13–15 章又通过智能旅行助手、自动化深度研究智能体、赛博小镇三个完整实战项目做了融合演练——而真正的挑战在于：如何把这些知识应用到实际问题中？如何设计一个完整系统？如何处理边界情况与异常？

毕业设计的核心价值正是培养这种综合应用能力，将前面学到的所有知识（智能体范式、工具系统、记忆机制、通信协议等）有选择地整合进一个完整项目中。完成它之后，你应当能够：

独立设计并实现一个完整的智能体应用；
熟练使用 HelloAgents 框架的各种功能；
掌握 Git 与 GitHub 的基本操作，参与开源协作；
编写清晰的项目文档；
最终获得一个可以在社区展示的技术作品。

毕业设计的形式与要求

毕业设计将以开源项目的形式提交到 Hello-Agents 的共创项目仓库（Co-creation-projects目录），具体要求如下：

项目命名：使用{你的GitHub用户名}-{项目名称}格式，例如jjyaoao-CodeReviewAgent；
项目内容：一个可运行的 Jupyter Notebook（.ipynb）或 Python 脚本、完整的依赖列表（requirements.txt）、清晰的 README（README.md），可选演示视频、截图、数据集等；
提交方式：通过 GitHub 的 Pull Request（PR）提交；
评审流程：社区成员会 review 你的代码、提出改进建议，通过后合并到主仓库。

这一流程在仓库中已有制度化落地：根目录下的 Co-creation-projects/README.md 就是共创项目的「门面」，它明确了项目命名规范、最小结构要求（README + requirements.txt + main.ipynb 三件套）、README 必备章节、提交流程以及五大项目分类，并直接引用了本章作为详细提交指南。也就是说，你提交的每一个项目都会成为其他学习者可参照的公共资产。

二、项目选题指南：找到值得做的问题

选题三原则

一个好的毕业设计项目应该：具有实用性，解决真实问题而不是为了技术而技术；在有限的时间和资源内可以完成；能够清晰地展示技术能力。而项目目录中的示例作品也印证了这一点——小的创意同样值得被收录，只要是自己动手的作品都值得珍惜。

五大推荐方向

原文档给出了五个方向的选题清单，每个方向下都附有具体的项目形态：

生产力工具类：智能代码审查助手（分析代码质量、发现潜在 bug、提出优化建议）、智能文档生成器、智能会议助手（生成会议纪要、提取行动项）、智能邮件助手；
学习辅助类：智能学习伙伴、智能论文助手、智能编程导师、智能语言学习助手；
创意娱乐类：智能故事生成器、智能游戏 NPC、智能音乐推荐、智能菜谱助手；
数据分析类：智能数据分析师、智能股票分析、智能舆情监控、智能竞品分析；
生活服务类：智能健康助手、智能理财助手、智能购物助手、智能家居控制。

对照 Co-creation-projects/README.md 中的项目分类，可以看到这五个方向正是仓库共创区实际收录作品的分类体系——例如1zrj-DataAnalysisAgent、CC1227871-StockInsightAgent、Henry2513-MeetingActionAgent、bichchibui5-hub-EmailSmartAssistant、lgs-only-NovelGenerator等真实项目分别落在数据分析、生产力工具、创意娱乐等类别中，说明这套选题框架已被社区实际验证。

选题示例：智能代码审查助手

原文档以CodeReviewAgent为例演示选题方法：

问题分析：代码审查是软件开发的重要环节，但人工审查耗时且易遗漏；现有静态分析工具只能发现语法错误，无法理解代码逻辑，因此需要一个能理解代码语义、提供深度分析的智能助手；
核心功能：代码质量分析（风格、命名规范、注释完整性）、潜在 bug 检测（逻辑错误、边界条件、资源泄漏）、性能优化建议、安全漏洞扫描（SQL 注入、XSS 等）、最佳实践推荐；
预期成果：可运行的 Jupyter Notebook 展示完整审查流程，支持 Python、JavaScript 等主流语言，输出结构化 Markdown 审查报告，并附带具体代码示例和改进建议。

三、开发环境准备与仓库协作流程

安装必要工具

(1) Python 环境：安装 HelloAgents 框架：

pip install "hello-agents[all]"

(2) Git 与 GitHub：配置版本控制环境：

# 检查 Git 版本 git --version # 配置 Git 用户信息 git config --global user.name "你的名字" git config --global user.email "你的邮箱" # 配置 GitHub SSH 密钥（推荐） # 1. 生成 SSH 密钥 ssh-keygen -t ed25519 -C "你的邮箱" # 2. 将公钥添加到 GitHub # 复制 ~/.ssh/id_ed25519.pub 的内容 # 在 GitHub Settings > SSH and GPG keys 中添加 # 3. 测试连接 ssh -T git@github.com

(3) Jupyter Notebook：

pip install jupyter notebook # 或使用 JupyterLab（推荐） pip install jupyterlab # 启动 jupyter lab

Fork 仓库并克隆到本地

毕业设计采用典型的 GitHub Fork 工作流，分三步完成：

步骤 1：Fork 仓库——访问 Hello-Agents 仓库，点击右上角 Fork 按钮，选择自己的 GitHub 账号完成 Fork：

步骤 2：克隆到本地——克隆你 Fork 的仓库，并添加上游仓库以便同步更新：

# 克隆你 Fork 的仓库 git clone git@github.com:你的用户名/hello-agents.git # 进入项目目录 cd hello-agents # 添加上游仓库（用于同步更新） git remote add upstream https://github.com/datawhalechina/hello-agents.git # 查看远程仓库 git remote -v

步骤 3：创建开发分支——不要直接在 main 分支上开发：

# 创建并切换到新分支 git checkout -b feature/你的项目名称 # 例如： git checkout -b feature/code-review-agent

项目目录结构

在Co-creation-projects目录下创建你的项目文件夹，并采用推荐的工程化结构：

cd Co-creation-projects mkdir 你的用户名-项目名称 # 例如: mkdir jjyaoao-CodeReviewAgent cd jjyaoao-CodeReviewAgent

你的用户名-项目名称/ ├── README.md # 项目说明文档 ├── requirements.txt # Python 依赖列表 ├── main.ipynb # 主要的 Jupyter Notebook ├── data/ # 数据文件（可选） │ ├── sample_code.py │ └── test_cases.json ├── outputs/ # 输出结果（可选） │ ├── review_report.md │ └── screenshots/ └── src/ # 源代码（可选，如果代码较多） ├── agents/ ├── tools/ └── utils/

这一结构与仓库中已收录的真实项目完全吻合：例如 Co-creation-projects/jjyaoao-CodeReviewAgent/ 实际包含README.md、requirements.txt、main.ipynb、data/sample_code.py与outputs/review_report.md；而Henry2513-MeetingActionAgent、nihaoshoum-LoveAnalysisAgent等项目也都遵循了data/+outputs/的目录约定，形成了社区一致的项目范式。

四、项目开发指南：从文档到代码

编写 README 文档

README 是项目的门面，原文档给出了一份完整模板，覆盖以下章节：项目名称与一句话描述、项目简介（解决什么问题、特色功能、适用场景）、核心功能清单、技术栈（HelloAgents 框架、使用的智能体范式如 ReAct / Plan-and-Solve、工具与 API、其他依赖）、快速开始（环境要求、安装依赖、配置 API 密钥、运行项目）、使用示例、项目亮点、性能评估、未来计划、贡献指南、许可证、作者、致谢。

仓库中的 Co-creation-projects/jjyaoao-CodeReviewAgent/README.md 就是这套模板的完整落地实例：它以「基于 HelloAgents 框架的智能代码审查工具」一句话开篇，随后依次给出项目简介、核心功能（代码结构分析 / PEP 8 风格检查 / LLM 智能建议 / Markdown 报告生成）、技术栈、两种 API 密钥配置方式、快速体验与完整功能两条使用路径、项目结构树、技术实现说明（两个自定义工具）、示例输出预览与未来改进清单——这份真实 README 可作为你撰写自己项目文档的对照范本。

编写 requirements.txt

列出项目所有 Python 依赖，并注明用途：

# 核心依赖 hello-agents[all]>=0.2.7 # 可视化（如果需要） matplotlib>=3.7.0 plotly>=5.14.0 # Web框架（如果需要） fastapi>=0.109.0 uvicorn>=0.27.0

仓库中真实项目的依赖清单可以印证这一规范。例如 Co-creation-projects/jjyaoao-CodeReviewAgent/requirements.txt 按依赖用途分块组织：hello-agents[all]>=0.1.0（框架核心）、jupyter>=1.0.0与notebook>=7.0.0（运行环境）、python-dotenv>=1.0.0（环境变量管理）、ast-comments>=1.0.0（代码分析工具）；而bichchibui5-hub-EmailSmartAssistant、alexrunner-DataAnalysisAgent等项目也都保持了「核心依赖 + 专项依赖」的分层写法。

开发 Jupyter Notebook

原文档给出了一个七段式 Notebook 工程化骨架，值得逐段落实：

项目介绍：以 Markdown 单元格说明项目名称、简介与作者信息；
环境配置：!pip install -q hello-agents[all]安装依赖，导入SimpleAgent、HelloAgentsLLM、BaseTool，用python-dotenv加载环境变量；
工具定义：继承BaseTool编写自定义工具类，声明name、description并实现run(query)方法；
智能体构建：创建HelloAgentsLLM，实例化SimpleAgent并传入system_prompt，用agent.add_tool()挂载工具；
功能演示：设计「基础功能」与「复杂场景」两个示例，打印运行结果；
性能评估（可选）：附加评估代码；
总结与展望：以 Markdown 总结实现的功能、遇到的挑战与解决方案、未来改进方向。

# ======================================== # 第3部分: 工具定义 # ======================================== class CustomTool(BaseTool): """自定义工具类""" name = "tool_name" description = "工具描述" def run(self, query: str) -> str: """工具执行逻辑""" # 实现你的工具逻辑 return "结果" # ======================================== # 第4部分: 智能体构建 # ======================================== llm = HelloAgentsLLM() agent = SimpleAgent( name="智能体名称", llm=llm, system_prompt="系统提示词" ) agent.add_tool(CustomTool())

提交前的自测清单

在提交之前，逐项检查自己的项目：

代码能够正常运行，没有报错
README 文档完整，说明清晰
requirements.txt 包含所有依赖
有清晰的使用示例
代码有适当的注释
输出结果符合预期
处理了常见的异常情况
项目结构清晰，文件命名规范
大文件已妥善处理（见下节）

大文件处理指南

为了保持主仓库轻量化，请遵循以下规范：

项目总大小不超过 5MB；禁止直接提交视频文件、大型数据集、模型文件；
方案 1：外部链接（推荐）——把大文件上传到外部平台，在 README 中提供下载链接。推荐平台：数据集用百度网盘 / Google Drive / Kaggle / HuggingFace Datasets，视频用 B 站 / YouTube / 腾讯视频，模型用 HuggingFace Models / ModelScope，图片用 GitHub Issues 或图床；
方案 2：创建独立仓库——资源较多时单独建项目名称-resources仓库，README 中说明克隆与拷贝方法；
方案 3：使用示例数据——主仓库只放小规模示例（如data/sample.csv，100 条记录），完整数据在 README 中注明下载方式。

推荐的目录实践（同时配合.gitignore忽略大文件）：

你的用户名-项目名称/ ├── README.md # 包含外部资源链接 ├── requirements.txt ├── main.ipynb ├── .gitignore # 忽略大文件 ├── data/ │ └── sample.csv # 仅示例数据（<1MB） └── outputs/ └── demo_result.png # 仅演示结果（<1MB）

五、提交 Pull Request：让作品进入社区

提交代码到 GitHub

按四步完成本地到远端的分支提交：

# 步骤1: 检查修改 git status # 步骤2: 添加文件（推荐只添加自己的项目目录） git add Co-creation-projects/你的用户名-项目名称/ # 步骤3: 提交，遵循 Conventional Commits 类型规范 git commit -m "feat: 添加XXX毕业设计项目" # 步骤4: 推送到你的 Fork 仓库 git push origin feature/你的项目名称

提交类型规范：feat新增功能或项目（毕业设计项目使用此类型）、fix修复 bug、docs文档更新、style代码格式调整、refactor代码重构、test测试相关、chore其他修改（如依赖更新）。

创建 Pull Request

进入你 Fork 的仓库，点击Pull requests标签页，再点击New pull request：

选择分支：Base repository 为datawhalechina/hello-agents、Base branch 为main；Head repository 为你的用户名/hello-agents、Compare branch 为feature/你的项目名称；
填写 PR 信息——PR 标题必须统一格式：

[毕业设计] 项目名称 - 简短描述

示例：[毕业设计] CodeReviewAgent - 智能代码审查助手、[毕业设计] StudyBuddy - AI学习伙伴、[毕业设计] DataAnalyst - 智能数据分析师。

PR 描述建议使用官方模板，包含：项目信息（项目名称、作者、项目类型）、项目简介（2–3 句）、核心功能清单、技术亮点（使用了 XXX 范式、实现了 XXX 功能）、演示效果（可选截图或 GIF）、自检清单（代码可运行 / README 完整 / requirements.txt 完整 / 使用示例清晰 / 注释适当）、其他说明。

点击Create pull request提交：

响应 Review 意见

提交 PR 后，社区成员会 review 代码并提出建议，请及时响应：

查看评论：在 PR 页面查看 reviewer 的评论；
修改代码：根据建议修改；
提交更新：

git add . git commit -m "fix: 根据review意见修改XXX" git push origin feature/你的项目名称

回复评论：在 GitHub 上回复 reviewer，说明你的修改内容。

六、示例项目深度拆解：CodeReviewAgent

为了让要求更具体，原文档给出了完整的示例项目，且该示例已在仓库中真实收录为 Co-creation-projects/jjyaoao-CodeReviewAgent/，我们可以对照源码逐层理解。

项目结构与真实产物

jjyaoao-CodeReviewAgent/ ├── README.md # 项目文档 ├── requirements.txt # 依赖列表 ├── main.ipynb # 主程序（含快速演示和完整功能） ├── .env.example # 环境变量示例 ├── .gitignore # Git忽略规则 ├── data/ │ └── sample_code.py # 示例代码 └── outputs/ └── review_report.md # 示例报告

其中outputs/review_report.md是项目的真实运行产物，展示了一次完整代码审查的五个维度：代码结构分析（UserManager类及其三个方法、calculate_average_age/send_email辅助函数）、风格问题（第 1 行超过 79 字符）、潜在 Bug（delete_user删除用户后列表索引变化的隐患）、性能优化建议（get_user最坏情况需遍历整个列表，建议改用字典存储）、最佳实践建议（补充异常处理、用logging替代print、编写单元测试、细化文档字符串），并给出改进后的完整代码示例——这正是「工具产出结构化事实 + LLM 生成深度建议」的典型协作模式。

核心代码解读（main.ipynb）

第一步：配置 LLM 参数。通过环境变量指定模型、密钥、接口地址与超时：

os.environ["LLM_MODEL_ID"] = "Qwen/Qwen2.5-72B-Instruct" os.environ["LLM_API_KEY"] = "your_api_key_here" os.environ["LLM_BASE_URL"] = "https://api-inference.modelscope.cn/v1/" os.environ["LLM_TIMEOUT"] = "60"

第二步：定义代码分析工具。CodeAnalysisTool使用 Python 标准库ast解析代码结构——用ast.parse建立语法树，再通过ast.walk收集FunctionDef与ClassDef节点，统计函数数量、类数量、代码行数并输出函数/类列表；遇到SyntaxError时返回可读的错误信息。StyleCheckTool则逐行检查 PEP 8 规范：超过 79 个字符的行、以及不在[0, 4, 8, 12]缩进阶梯上的行都会被记录为问题。两个工具都通过get_parameters()声明入参（code参数，string 类型，必填）：

class CodeAnalysisTool(Tool): """代码静态分析工具""" def __init__(self): super().__init__( name="code_analysis", description="分析Python代码的结构、复杂度和潜在问题" ) def run(self, parameters: Dict[str, Any]) -> str: code = parameters.get("code", "") if not code: return "错误:代码不能为空" try: tree = ast.parse(code) functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)] classes = [node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)] result = { "函数数量": len(functions), "类数量": len(classes), "代码行数": len(code.split('\n')), "函数列表": [f.name for f in functions], "类列表": [c.name for c in classes] } return str(result) except SyntaxError as e: return f"语法错误:{str(e)}"

第三步：组装工具注册表与智能体。把两个工具注册进ToolRegistry，创建HelloAgentsLLM实例，再定义系统提示词——提示词明确规定了审查流程（先code_analysis分析结构、再style_check检查风格、最后基于结果输出报告）与报告结构（代码结构分析、风格问题、潜在 bug、性能优化建议、最佳实践建议，以 Markdown 输出），最后用SimpleAgent把 LLM、提示词与工具注册表绑定起来：

tool_registry = ToolRegistry() tool_registry.register_tool(CodeAnalysisTool()) tool_registry.register_tool(StyleCheckTool()) llm = HelloAgentsLLM() system_prompt = """你是一位经验丰富的代码审查专家。你的任务是: 1. 使用code_analysis工具分析代码结构 2. 使用style_check工具检查代码风格 3. 基于分析结果，提供详细的审查报告 审查报告应包括: 代码结构分析、风格问题、潜在bug、性能优化建议、最佳实践建议 请以Markdown格式输出报告。""" agent = SimpleAgent( name="代码审查助手", llm=llm, system_prompt=system_prompt, tool_registry=tool_registry )

第四步：运行示例并保存报告。读取data/sample_code.py，调用agent.run()发起审查，将返回的 Markdown 报告写入outputs/review_report.md：

with open("data/sample_code.py", "r", encoding="utf-8") as f: sample_code = f.read() review_result = agent.run(f"请审查以下Python代码:\n\n```python\n{sample_code}\n```") with open("outputs/review_report.md", "w", encoding="utf-8") as f: f.write(review_result)

从源码结构看，这个项目的设计精髓在于把确定性分析与生成式推理解耦：ast解析与 PEP 8 检查是确定、可复现的，保证审查结果不漂移；而 LLM 基于工具返回的结构化事实，负责写出「潜在 Bug」「性能优化」这类需要语义理解的深度建议。这也正是第 4 章 ReAct 范式「思考–调用工具–观察–再思考」在毕业设计中的直接应用——工具负责事实，LLM 负责推理。

与该示例可对照的框架实现

示例中使用的SimpleAgent、HelloAgentsLLM、ToolRegistry等组件，正是本教程第 7 章「构建你的 Agent 框架」的成果。以 code/chapter7/my_llm.py 为例，MyLLM通过继承HelloAgentsLLM扩展能力；code/chapter7/my_simple_agent.py 中的MySimpleAgent继承SimpleAgent；code/chapter7/my_react_agent.py 则展示了基于ReActAgent的推理循环实现。如果你在毕业设计中需要更复杂的推理能力，可以直接参考这些框架源码来理解add_tool、tool_registry等 API 的底层调用关系。

七、总结与展望

完成毕业设计意味着你掌握了智能体系统设计的完整闭环：从需求出发设计系统架构，熟练使用 HelloAgents 框架的功能与组件，开发自定义工具扩展智能体能力，完成从需求分析到代码实现的完整项目开发，使用 Git 与 GitHub 进行开源协作，并编写清晰的技术文档。

从第 1 章的简单智能体，到能够独立构建完整的多智能体应用，这是一段完整的进阶之旅，而毕业设计不是终点而是新的起点。原文档给出了三条清晰的后续路线：

深化理论：继续学习更多智能体范式与算法、提示工程与上下文工程、多智能体协作机制；
扩展技术栈：学习 Web 开发构建完整应用、学习数据库实现数据持久化、学习部署将应用上线；
持续打磨与回馈社区：添加功能、优化性能与体验、完善测试与文档，参与 Hello-Agents 框架开发，帮助其他学习者。

记住：最好的学习方式就是动手实践！现在就开始构建属于你的智能体应用，我们期待在Co-creation-projects目录中看到你的精彩作品。如果你想提前了解项目的整体脉络与全部章节，可以翻阅 docs/README.md；共创项目的提交规范与最新收录作品，可随时查阅 Co-creation-projects/README.md。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析