从零开始构建智能体 [Hello,Agents]

从零开始构建智能体 [Hello,Agents] 从零开始构建智能体 [Hello,Agents] Modified January 3 Created on December 21, 2025 8294 13982 9 29 Code block Plain Text Copy fastapi =0.109.0 uvicorn =0.27.0 16.4.3 开发 Jupyter Notebook （1）Notebook 结构建议 一个好的 Jupyter Notebook 应该包含以下部分： Code block Plain Text Copy ======================================== 第1部分:项目介绍 ========================================""" 项目名称 项目简介 简要介绍项目的目标和功能 作者信息 姓名:XXX GitHub:@XXX 日期:2025 XX XX """ ======================================== 第2部分:环境配置 ======================================== 安装依赖 !pip install q hello agents[all] 导入必要的库from hello agents import SimpleAgent, HelloAgentsLLM from hello agents.tools import BaseTool import os from dotenv import load dotenv 加载环境变量 load dotenv() ======================================== 第3部分:工具定义 ========================================class CustomTool(BaseTool):"""自定义工具类""" name = "tool name" description = "工具描述"def run(self, query: str) str:"""工具执行逻辑""" 实现你的工具逻辑return "结果" ======================================== 第4部分:智能体构建 ======================================== 创建LLM llm = HelloAgentsLLM() 创建智能体 agent = SimpleAgent( name="智能体名称", llm=llm, system prompt="系统提示词") 添加工具 agent.add tool(CustomTool()) ======================================== 第5部分:功能演示 ======================================== 示例1:基础功能print("=== 示例1:基础功能 ===") result = agent.run("用户输入")print(result) 示例2:复杂场景print("\n=== 示例2:复杂场景 ===") result = agent.run("复杂的用户输入")print(result) ======================================== 第6部分:性能评估（可选） ======================================== 评估代码 ... ======================================== 第7部分:总结与展望 ========================================""" 项目总结 实现的功能 功能1 功能2 遇到的挑战 挑战1及解决方案 挑战2及解决方案 未来改进方向 改进1 改进2 """ 16.4.4 测试你的项目 在提交之前，可以使用测试清单来判断自己的项目是否满足提交要求： Code block Plain Text Copy [ ] 代码能够正常运行，没有报错 [ ] README文档完整，说明清晰 [ ] requirements.txt包含所有依赖 [ ] 有清晰的使用示例 [ ] 代码有适当的注释 [ ] 输出结果符合预期 [ ] 处理了常见的异常情况 [ ] 项目结构清晰，文件命名规范 [ ] 大文件已妥善处理（见下节） 16.4.5 大文件处理指南 ⚠️ 重要：避免主仓库过大 为了保持 Hello Agents 主仓库的轻量化，请遵循以下大文件处理规范： （1）文件大小限制 • 项目总大小： 不超过 5MB • 禁止直接提交： 视频文件、大型数据集、模型文件 （2）大文件处理方案 如果你的项目包含大文件（数据集、视频、模型等），请使用以下方案： 方案 1：使用外部链接（推荐） 将大文件上传到外部平台，在 README 中提供下载链接： Code block Plain Text Copy 数据集 本项目使用的数据集较大，请从以下链接下载: 数据集1: 百度网盘 提取码: xxxx 数据集2: Google Drive 演示视频: B站 / YouTube 推荐的外部平台： • 数据集： 百度网盘、Google Drive、Kaggle、HuggingFace Datasets • 视频： B 站、YouTube、腾讯视频 • 模型： HuggingFace Models、ModelScope • 图片： GitHub Issues、图床服务 方案 2：创建独立仓库 如果项目资源较多，建议创建独立的数据仓库： Code block Plain Text Copy 项目资源 由于项目包含大量数据和演示资源，已单独创建资源仓库: 资源仓库: https://github.com/你的用户名/项目名称 resources 包含内容: 数据集、演示视频、模型文件、测试数据等 使用方法 \ \ \ 方案 3：使用示例数据 在主仓库中只提供小规模的示例数据： Code block Plain Text Copy 在README中说明 数据说明 : 示例数据（100条记录） 完整数据集（10万条记录）请从这里下载 （3）最佳实践示例 Code block Plain Text Copy 你的用户名 项目名称/ ├── README.md 包含外部资源链接 ├── requirements.txt ├── main.ipynb ├── .gitignore 忽略大文件 ├── data/ │ └── sample.csv 仅示例数据（<1MB） └── outputs/ └── demo result.png 仅演示结果（<1MB） README 中的说明： Code block Plain Text Copy 数据和资源 示例数据 项目包含小规模示例数据用于快速测试（位于 ） 完整数据集 完整数据集（500MB）请从以下链接下载: 百度网盘: [链接] 提取码: xxxx 下载后解压到 目录 演示视频 B站: 项目演示视频 YouTube: Demo Video 16.5 提交 Pull Request 16.5.1 提交代码到 GitHub 步骤 1：检查修改 Code block Plain Text Copy 查看修改的文件git status 步骤 2：添加文件 Code block Plain Text Copy 添加所有修改的文件git add . 或者添加特定文件git add Co creation projects/你的用户名 项目名称/ 步骤 3：提交修改 提交信息应遵循以下格式： Code block Plain Text Copy 格式:类型: 简短描述git commit m "feat: 添加XXX毕业设计项目" 提交类型规范： • feat： 新增功能或项目（毕业设计项目使用此类型） • fix： 修复 bug • docs： 文档更新 • style： 代码格式调整（不影响功能） • refactor： 代码重构 • test： 测试相关 • chore： 其他修改（如依赖更新） 步骤 4：推送到 GitHub Code block Plain Text Copy 推送到你的Fork仓库git push origin feature/你的项目名称 16.5.2 创建 Pull Request 步骤 1：访问 GitHub 1. 访问你 Fork 的仓库：https://github.com/你的用户名/Hello Agents 2. 点击"Pull requests"标签，如图 16.3 所示 3. 点击"New pull request"按钮 图 16.3 创建 Pull Request 步骤 2：选择分支 • Base repository： datawhalechina/Hello Agents • Base branch： main • Head repository： 你的用户名/Hello Agents • Compare branch： feature/你的项目名称 步骤 3：填写 PR 信息 16.4.3 开发 Jupyter Notebook （1）Notebook 结构建议 一个好的 Jupyter Notebook 应该包含以下部分： 16.4.4 测试你的项目 在提交之前，可以使用测试清单来判断自己的项目是否满足提交要求： 16.4.5 大文件处理指南 ⚠️ 重要：避免主仓库过大 为了保持 Hello Agents 主仓库的轻量化，请遵循以下大文件处理规范： （1）文件大小限制 • 项目总大小： 不超过 5MB • 禁止直接提交： 视频文件、大型数据集、模型文件 （2）大文件处理方案 如果你的项目包含大文件（数据集、视频、模型等），请使用以下方案： 方案 1：使用外部链接（推荐） 将大文件上传到外部平台，在 README 中提供下载链接： 推荐的外部平台： • 数据集： 百度网盘、Google Drive、Kaggle、HuggingFace Datasets • 视频： B 站、YouTube、腾讯视频 • 模型： HuggingFace Models、ModelScope • 图片： GitHub Issues、图床服务 方案 2：创建独立仓库 如果项目资源较多，建议创建独立的数据仓库： 方案 3：使用示例数据 在主仓库中只提供小规模的示例数据： （3）最佳实践示例 README 中的说明： 16.5 提交 Pull Request 16.5.1 提交代码到 GitHub 步骤 1：检查修改 步骤 2：添加文件 步骤 3：提交修改 提交信息应遵循以下格式： 提交类型规范： • feat： 新增功能或项目（毕业设计项目使用此类型） • fix： 修复 bug • docs： 文档更新 • style： 代码格式调整（不影响功能） • refactor： 代码重构 • test： 测试相关 • chore： 其他修改（如依赖更新） 步骤 4：推送到 GitHub 16.5.2 创建 Pull Request 步骤 1：访问 GitHub 1. 访问你 Fork 的仓库：https://github.com/你的用户名/Hello Agents 2. 点击"Pull requests"标签，如图 16.3 所示 3. 点击"New pull request"按钮 图 16.3 创建 Pull Request 步骤 2：选择分支 • Base repository： datawhalechina/Hello Agents • Base branch： main • Head repository： 你的用户名/Hello Agents • Compare branch： feature/你的项目名称 步骤 3：填写 PR 信息 python\n{sample code}\n README.md 示例 16.7 总结与展望 通过完成毕业设计，你应该已经掌握了智能体系统设计的完整流程。从需求出发设计系统架构，熟练使用 HelloAgents 框架的各种功能和组件，开发自定义工具扩展智能体能力，完成从需求分析到代码实现的完整项目开发，学会使用 Git 和 GitHub 进行开源协作，以及编写清晰的技术文档。 在本项目中，我们从零开始构建了 HelloAgents 框架，并用它实现了多个实用的应用。完成毕业设计只是开始，你可以继续深入学习更多智能体范式和算法、提示工程和上下文工程、多智能体协作机制等理论知识；也可以扩展技术栈，学习 Web 开发构建完整的应用、学习数据库实现数据持久化、学习部署将应用上线；还可以持续优化你的项目，添加更多功能、优化性能和用户体验、完善测试和文档；更重要的是，积极参与社区贡献，帮助其他学习者、参与 Hello Agents 框架开发、分享你的经验和心得。 从第一章的简单智能体，到现在能够独立构建完整的多智能体应用，你已经走过了一段精彩的学习旅程。但这不是终点，而是新的起点。 AI 技术日新月异，智能体领域更是充满无限可能。希望你能够保持好奇心持续学习新技术，勇于用 AI 技术解决实际问题创造价值，乐于将你的经验和成果分享给社区，不断打磨你的作品追求卓越。 最后，感谢你完整阅读了本项目。希望你在学习的过程中有所收获，也希望你能够将所学应用到实际项目中，创造出令人惊叹的智能体应用。AI 的未来充满无限可能，让我们一起探索和创造! 记住：最好的学习方式就是动手实践！ 现在，开始构建属于你的智能体应用吧！我们期待在 Co creation projects 目录中看到你的精彩作品！ 如果你觉得 Hello Agents 项目对你有帮助，请给我们一个⭐Star！ 🎓 恭喜你完成了 Hello Agents 教程的学习！🎉 🤖 《从零开始构建智能体》 [Hello, Agents] 从基础理论到实际应用，全面掌握智能体系统的设计与实现 🔖 本文经授权转载，特此致谢 👤 原作者：陈思州 (GitHub: jjyaoao) LLM Agent 领域资深开发者等，顶级开源教程 hello agents 核心作者。该项目在 GitHub 已突破 10,000 Stars ，是目前最系统、最硬核的智能体开发入门实战教程之一。 🐳 来源社区：Datawhale AI 开源学习社区之一，汇聚了众多开源与探索精神的理想主义者。致力于构建和分享高质量的 AI 学习资源，始终秉持 "for the learner" 的初心，与学习者共同成长。 🔖 本文经授权转载，特此致谢 👤 原作者：陈思州 (GitHub: jjyaoao) LLM Agent 领域资深开发者等，顶级开源教程 hello agents 核心作者。该项目在 GitHub 已突破 10,000 Stars ，是目前最系统、最硬核的智能体开发入门实战教程之一。 🐳 来源社区：Datawhale AI 开源学习社区之一，汇聚了众多开源与探索精神的理想主义者。致力于构建和分享高质量的 AI 学习资源，始终秉持 "for the learner" 的初心，与学习者共同成长。 🎯 项目介绍 如果说 2024 年是"百模大战"的元年，那么 2025 年无疑开启了"Agent 元年"。技术的焦点正从训练更大的基础模型，转向构建更聪明的智能体应用。然而，当前系统性、重实践的教程却极度匮乏。为此，我们发起了 Hello Agents 项目，希望能为社区提供一本从零开始、理论与实战并重的智能体系统构建指南。 Hello Agents 是 Datawhale 社区的系统性智能体学习教程。如今 Agent 构建主要分为两派，一派是 Dify，Coze，n8n 这类软件工程类 Agent，其本质是流程驱动的软件开发，LLM 作为数据处理的后端；另一派则是 AI 原生的 Agent，即真正以 AI 驱动的 Agent。本教程旨在带领大家深入理解并构建后者——真正的 AI Native Agent。教程将带领你穿透框架表象，从智能体的核心原理出发，深入其核心架构，理解其经典范式，并最终亲手构建起属于自己的多智能体应用。我们相信，最好的学习方式就是动手实践。希望这本教程能成为你探索智能体世界的起点，能够从一名大语言模型的"使用者"，蜕变为一名智能体系统的"构建者"。 ✨ 你将收获什么？ • 📖 Datawhale 开源免费 完全免费学习本项目所有内容，与社区共同成长 • 🔍 理解核心原理 深入理解智能体的概念、历史与经典范式 • 🏗️ 亲手实现 掌握热门低代码平台和智能体代码框架的使用 • 🛠️ 自研框架HelloAgents 基于 Openai 原生 API 从零构建一个自己的智能体框架 • ⚙️ 掌握高级技能 一步步实现上下文工程、Memory、协议、评估等系统性技术 • 🤝 模型训练 掌握 Agentic RL，从 SFT 到 GRPO 的全流程实战训练 LLM • 🚀 驱动真实案例 实战开发智能旅行助手、赛博小镇等综合项目 • 📖 求职面试 学习智能体求职相关面试问题 💡 如何学习 欢迎你，未来的智能系统构建者！在开启这段激动人心的旅程之前，请允许我们给你一些清晰的指引。 本项目内容兼顾理论与实战，旨在帮助你系统性地掌握从单个智能体到多智能体系统的设计与开发全流程。因此，尤其适合有一定编程基础的 AI 开发者、软件工程师、在校学生 以及对前沿 AI 技术抱有浓厚兴趣的 自学者。在学习本项目之前，我们希望你具备基础的 Python 编程能力，并对大语言模型有基本的概念性了解（例如，知道如何通过 API 调用一个 LLM）。项目的重点是应用与构建，因此你无需具备深厚的算法或模型训练背景。 项目分为五大部分，每一部分都是通往下一阶段的坚实阶梯： • 第一部分：智能体与语言模型基础（第一章～第三章），我们将从智能体的定义、类型与发展历史讲起，为你梳理"智能体"这一概念的来龙去脉。随后，我们会快速巩固大语言模型的核心知识，为你的实践之旅打下坚实的理论地基。 • 第二部分：构建你的大语言模型智能体（第四章～第七章），这是你动手实践的起点。你将亲手实现 ReAct 等经典范式，体验 Coze 等低代码平台的便捷，并掌握 Langgraph 等主流框架的应用。最终，我们还会带你从零开始构建一个属于自己的智能体框架，让你兼具“用轮子”与“造轮子”的能力。 • 第三部分：高级知识扩展（第八章～第十二章），在这一部分，你的智能体将“学会”思考与协作。我们将使用第二部分的自研框架，深入探索记忆与检索、上下文工程、Agent 训练等核心技术，并学习多智能体间的通信协议。最终，你将掌握评估智能体系统性能的专业方法。 • 第四部分：综合案例进阶（第十三章～第十五章），这里是理论与实践的交汇点。你将把所学融会贯通，亲手打造智能旅行助手、自动化深度研究智能体，乃至一个模拟社会动态的赛博小镇，在真实有趣的项目中淬炼你的构建能力。 • 第五部分：毕业设计及未来展望（第十六章），在旅程的终点，你将迎来一个毕业设计，构建一个完整的、属于你自己的多智能体应用，全面检验你的学习成果。我们还将与你一同展望智能体的未来，探索激动人心的前沿方向。 智能体是一个飞速发展且极度依赖实践的领域。为了获得最佳的学习效果，我们在项目的code文件夹内提供了配套的全部代码，强烈建议你将理论与实践相结合。请务必亲手运行、调试甚至修改项目里提供的每一份代码。欢迎你随时关注 Datawhale 以及其他 Agent 相关社区，当遇到问题时，你可以随时在本项目的 issue 区提问。 现在，准备好进入智能体的奇妙世界了吗？让我们即刻启程！ 前言 自 2022 年底以来，以 ChatGPT 为代表的大语言模型（Large Language Model, LLM）如同一场技术海啸，彻底改变了我们与人工智能交互的方式。LLM 强大的自然语言理解和生成能力，让我们看到了通往通用人工智能（AGI）的曙光。然而，当最初的惊艳沉淀下来，开发者们开始探索下一个前沿：如何让 AI 不仅仅是一个“有问必答”的工具，而是成为一个能自主规划、调用工具、解决复杂问题的“行动者”？ 答案，就是 智能体（Agent）。 如果说 2024 年是“百模大战”的元年，那么 2025 年无疑开启了“Agent 元年”。我们看到，技术的焦点正从训练更大、更强的基础模型，转向如何构建更聪明、更高效的智能体应用。单个智能体已经能胜任特定领域的任务，而由多个智能体分工、协作、甚至辩论，共同完成一个宏大目标的多智能体系统（Multi Agent System, MAS），则被视为释放 LLM 全部潜能、解决真实世界复杂问题的关键钥匙。 然而，当前的生态中存在一个明显的断层：一方面是层出不穷的 Agent 框架和应用，令人眼花缭乱；另一方面，却是系统性知识的极度匮乏。大多数教程聚焦于某个特定框架的 API 调用，学习者往往“知其然，而不知其所以然”，在面对复杂需求时，依然感到力不从心。我们缺少一本能够穿透框架表象，从第一性原理出发，系统讲解智能体设计、构建与协作的实战指南。 鉴于此，我们发起了 Hello Agents 项目，希望能为社区提供一本从零开始、理论与实战并重的智能体系统构建指南。我们不仅会带你领略智能体领域最前沿的技术，更会引导你深入其核心架构，理解其经典范式，并最终亲手构建起属于自己的多智能体应用。 我们相信，最好的学习方式就是动手实践。希望这本教程能成为你探索智能体世界的起点，能够从一名大语言模型的"使用者"，蜕变为一名智能体系统的"构建者"。 写给读者的建议 欢迎你，未来的智能系统构建者！在开启这段激动人心的旅程之前，请允许我们给你一些小小的建议。 在阅读项目之前，我们希望你： • 具备基础的 Python 编程能力。 • 对大语言模型有基本的概念性了解（例如，知道如何获取 LLM 的 API）。 • 请放心，你无需具备深厚的算法或模型训练背景，项目的重点是应用与构建。 本项目分为五部分，覆盖基础到实战，循序渐进，层层相扣： 第一部分（基础篇）： 我们将为你铺垫人工智能与 LLM 的核心知识，让你对智能体的诞生背景有宏观的认识。 第二部分（单体篇）： 这是你动手实践的开始。我们将带你从零开始，构建一个功能完备的单体智能，深入理解其内部的“心智”结构。 第三部分（高级篇）： 在这里，你的智能体将“学会”思考、拥有记忆和工具，并掌握智能体之间的通信协议，最终完成评估的闭环。 第四部分（实战篇）： 这是项目的核心价值所在。你将通过一系列精心设计的综合案例，将所学知识融会贯通，在实战中淬炼真金。 第五部分（展望篇）： 旅程的终点是新的起点。你将亲手打造属于你的“毕业作品”，为你的学习之旅画上一个圆满的句号。 纸上得来终觉浅，绝知此事要躬行。为了获得最佳的学习效果，我们在项目的code文件夹内提供了配套的全部代码，强烈建议你将理论与实践相结合。请务必亲手运行、调试甚至修改项目里提供的每一份代码。我们鼓励你举一反三，将所学技术应用到自己感兴趣的真实场景中，这才是学习的最终目的。 最后，作为一个开源项目，我们热忱欢迎你的参与和贡献。当你遇到问题时，可以在我们的社区中提问；当你有了新的想法或发现时，也欢迎你随时加入到项目的共建中来。 感谢你选择阅读 Hello agents，祝你学习愉快，探索无限！ 第一部分：智能体与语言模型基础 第一章 初识智能体 欢迎来到智能体的世界！在人工智能浪潮席卷全球的今天，智能体（Agent）已成为驱动技术变革与应用创新的核心概念之一。无论你的志向是成为 AI 领域的研究者、工程师，还是希望深刻理解技术前沿的观察者，掌握智能体的本质，都将是你知识体系中不可或缺的一环。 因此，在本章，让我们回到原点，一起探讨几个问题：智能体是什么？它有哪些主要的类型？它又是如何与我们所处的世界进行交互的？通过这些讨论，希望能为你未来的学习和探索打下坚实的基础。 图 1.1 智能体与环境的基本交互循环 1.1 什么是智能体？ 在探索任何一个复杂概念时，我们最好从一个简洁的定义开始。在人工智能领域，智能体被定义为任何能够通过传感器（Sensors）感知其所处环境（Environment），并自主地通过执行器（Actuators）采取行动（Action）以达成特定目标的实体。 这个定义包含了智能体存在的四个基本要素。环境是智能体所处的外部世界。对于自动驾驶汽车，环境是动态变化的道路交通；对于一个交易算法，环境则是瞬息万变的金融市场。智能体并非与环境隔离，它通过其传感器持续地感知环境状态。摄像头、麦克风、雷达或各类应用程序编程接口（Application Programming Interface, API）返回的数据流，都是其感知能力的延伸。 获取信息后，智能体需要采取行动来对环境施加影响，它通过执行器来改变环境的状态。执行器可以是物理设备（如机械臂、方向盘）或虚拟工具（如执行一段代码、调用一个服务）。 然而，真正赋予智能体"智能"的，是其自主性（Autonomy）。智能体并非只是被动响应外部刺激或严格执行预设指令的程序，它能够基于其感知和内部状态进行独立决策，以达成其设计目标。这种从感知到行动的闭环，构成了所有智能体行为的基础，如图 1.1 所示。 1.1.1 传统视角下的智能体 在当前大语言模型（Large Language Model, LLM）的热潮出现之前，人工智能的先驱们已经对“智能体”这一概念进行了数十年的探索与构建。这些如今我们称之为“传统智能体”的范式，并非单一的静态概念，而是经历了一条从简单到复杂、从被动反应到主动学习的清晰演进路线。 这个演进的起点，是那些结构最简单的反射智能体（Simple Reflex Agent）。它们的决策核心由工程师明确设计的“条件 动作”规则构成，如图 1.2 所示。经典的自动恒温器便是如此：若传感器感知的室温高于设定值，则启动制冷系统。 这种智能体完全依赖于当前的感知输入，不具备记忆或预测能力。它像一种数字化的本能，可靠且高效，但也因此无法应对需要理解上下文的复杂任务。它的局限性引出了一个关键问题：如果环境的当前状态不足以作为决策的全部依据，智能体该怎么办？ 图 1.2 简单反射智能体的决策逻辑示意图 为了回答这个问题，研究者们引入了“状态”的概念，发展出基于模型的反射智能体（Model Based Reflex Agent）。这类智能体拥有一个内部的世界模型（World Model），用于追踪和理解环境中那些无法被直接感知的方面。它试图回答：“世界现在是什么样子的？”。例如，一辆在隧道中行驶的自动驾驶汽车，即便摄像头暂时无法感知到前方的车辆，它的内部模型依然会维持对那辆车存在、速度和预估位置的判断。这个内部模型让智能体拥有了初级的“记忆”，使其决策不再仅仅依赖于瞬时感知，而是基于一个更连贯、更完整的世界状态理解。 然而，仅仅理解世界还不够，智能体需要有明确的目标。这促进了基于目标的智能体（Goal Based Agent）的发展。与前两者不同，它的行为不再是被动地对环境做出反应，而是主动地、有预见性地选择能够导向某个特定未来状态的行动。这类智能体需要回答的问题是：“我应该做什么才能达成目标？”。经典的例子是 GPS 导航系统：你的目标是到达公司，智能体会基于地图数据（世界模型），通过搜索算法（如 A 算法）来规划（Planning）出一条最优路径。这类智能体的核心能力体现在了对未来的考量与规划上。 更进一步，现实世界的目标往往不是单一的。我们不仅希望到达公司，还希望时间最短、路程最省油并且避开拥堵。当多个目标需要权衡时，基于效用的智能体（Utility Based Agent）便随之出现。它为每一个可能的世界状态都赋予一个效用值，这个值代表了满意度的高低。智能体的核心目标不再是简单地达成某个特定状态，而是最大化期望效用。它需要回答一个更复杂的问题：“哪种行为能为我带来最满意的结果？”。这种架构让智能体学会在相互冲突的目标之间进行权衡，使其决策更接近人类的理性选择。 至此，我们讨论的智能体虽然功能日益复杂，但其核心决策逻辑，无论是规则、模型还是效用函数，依然依赖于人类设计师的先验知识。如果智能体能不依赖预设，而是通过与环境的互动自主学习呢？ 这便是学习型智能体（Learning Agent）的核心思想，而强化学习（Reinforcement Learning, RL）是实现这一思想最具代表性的路径。一个学习型智能体包含一个性能元件（