Hello-Agents从零构建 AI Native 智能体的完整学习路线、配套代码与实战解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsHello-Agents 是 Datawhale 社区推出的系统性智能体开源教程《从零开始构建智能体》的主仓库覆盖从智能体概念、经典范式ReAct、Plan-and-Solve、Reflection到记忆与检索、上下文工程、通信协议、Agentic-RL 训练及综合案例的全链路内容。本文基于仓库根目录的 README 展开并结合code/目录下各章配套源码带你理清这条从使用者到构建者的学习路径、每章配套代码的真实实现方式以及本地运行所需的环境配置细节。读完本文你可以明确 16 个章节各自解决什么问题、如何配合code/目录中的可运行代码动手实践以及社区扩展章节Extra-Chapter与共创项目库的用法。一、项目定位为什么强调AI Native AgentREADME 开篇给出了当前 Agent 构建领域的两分法这也是整个教程的立论基础软件工程类 Agent如 Dify、Coze、n8n 等低代码平台本质是流程驱动的软件开发LLM 作为数据处理的后端AI 原生 AgentAI Native Agent真正以 AI 驱动的智能体由模型自主完成推理、规划与工具调用。教程的目标是带领大家深入理解并构建后者。这一定位决定了课程结构低代码平台第五章与主流框架第六章只是用轮子的入门环节第七章节要求造轮子——基于 OpenAI 兼容 API 从零构建一个自己的智能体框架后续的第八章至第十二章记忆、检索、上下文工程、协议、训练、评估都建立在这个自研框架之上。教程同时承诺的收获清单见 README你将收获什么包括理解核心原理、掌握低代码平台与代码框架的使用、自研框架 HelloAgents、上下文工程与 Memory 等高级技能、从 SFT 到 GRPO 的 Agentic-RL 全流程实战、以及智能旅行助手与赛博小镇等综合案例。二、课程总体结构16 章五部分的章节导航仓库文档位于docs/目录侧边栏 与 README 的导航表一致全书按五大部分组织。下表完整继承 README 的章节导航链接已转换为仓库根目录相对路径并补充各部分的学习目标章节关键内容学习文档前言项目的缘起、背景及读者建议docs/前言.md第一部分智能体与语言模型基础第一章 初识智能体智能体定义、类型、范式与应用docs/chapter1/第一章%20初识智能体.md第二章 智能体发展史从符号主义到 LLM 驱动的智能体演进docs/chapter2/第二章%20智能体发展史.md第三章 大语言模型基础Transformer、提示、主流 LLM 及其局限docs/chapter3/第三章%20大语言模型基础.md第二部分构建你的大语言模型智能体第四章 智能体经典范式构建手把手实现 ReAct、Plan-and-Solve、Reflectiondocs/chapter4/第四章%20智能体经典范式构建.md第五章 基于低代码平台的智能体搭建Coze、Dify、n8n 等低代码平台使用docs/chapter5/第五章%20基于低代码平台的智能体搭建.md第六章 框架开发实践AutoGen、AgentScope、LangGraph 等主流框架docs/chapter6/第六章%20框架开发实践.md第七章 构建你的Agent框架从 0 开始构建智能体框架docs/chapter7/第七章%20构建你的Agent框架.md第三部分高级知识扩展第八章 记忆与检索记忆系统、RAG、存储docs/chapter8/第八章%20记忆与检索.md第九章 上下文工程持续交互的情境理解docs/chapter9/第九章%20上下文工程.md第十章 智能体通信协议MCP、A2A、ANP 等协议解析docs/chapter10/第十章%20智能体通信协议.md第十一章 Agentic-RL从 SFT 到 GRPO 的 LLM 训练实战docs/chapter11/第十一章%20Agentic-RL.md第十二章 智能体性能评估核心指标、基准测试与评估框架docs/chapter12/第十二章%20智能体性能评估.md第四部分综合案例进阶第十三章 智能旅行助手MCP 与多智能体协作的真实世界应用docs/chapter13/第十三章%20智能旅行助手.md第十四章 自动化深度研究智能体DeepResearch Agent 复现与解析docs/chapter14/第十四章%20自动化深度研究智能体.md第十五章 构建赛博小镇Agent 与游戏的结合模拟社会动态docs/chapter15/第十五章%20构建赛博小镇.md第五部分毕业设计及未来展望第十六章 毕业设计构建属于你的完整多智能体应用docs/chapter16/第十六章%20毕业设计.mdREADME 对五部分的学习路径还有一段精炼的说明值得直接引用第一部分第一三章从智能体的定义、类型与发展历史讲起梳理概念来龙去脉并快速巩固大语言模型核心知识打下理论地基第二部分第四七章动手实践起点。亲手实现 ReAct 等经典范式体验 Coze 等低代码平台掌握 LangGraph 等主流框架最终从零构建自己的智能体框架兼具用轮子与造轮子的能力第三部分第八十二章使用第二部分自研框架深入记忆与检索、上下文工程、Agent 训练、通信协议并掌握评估智能体系统性能的专业方法第四部分第十三十五章理论与实践的交汇点打造智能旅行助手、自动化深度研究智能体、模拟社会动态的赛博小镇第五部分第十六章毕业设计构建完整的属于自己的多智能体应用并展望智能体前沿方向。学习前置条件README 明确了读者画像与前置要求学习前请对照自查适合人群有一定编程基础的 AI 开发者、软件工程师、在校学生以及对前沿 AI 技术有兴趣的自学者前置能力基础 Python 编程能力对大语言模型有基本概念性了解例如知道如何通过 API 调用一个 LLM明确不要求深厚的算法或模型训练背景——项目重点在应用与构建。三、配套代码总览code 目录与章节一一对应README 强调智能体是一个飞速发展且极度依赖实践的领域并强烈建议将理论与实践结合亲手运行、调试甚至修改code/目录中的每一份代码。code/目录与docs/中的 16 个章节一一对应下面按学习顺序梳理各章配套代码的实际内容与结构。3.1 第一章第一次与智能体对话FirstAgentTest.py及同名 Notebook是全书的第一个程序用于完成最朴素的用户输入—模型响应闭环作为后续所有范式的对照基线。3.2 第四章三大经典范式的可运行实现第四章配套代码位于 code/chapter4 目录包含四个文件构成一个最小但完整的智能体运行时llm_client.pyHelloAgentsLLM客户端是全章及后续示例的模型调用底座tools.pyToolExecutor与内置工具如网页搜索演示注册—描述—执行的工具管理方式ReAct.py、Plan_and_solve.py、Reflection.py三种经典范式的独立实现。LLM 客户端与 .env 环境变量约定llm_client.py 中的HelloAgentsLLM初始化逻辑定义了全教程统一的环境变量约定这也是本地运行任何配套代码前的首要配置步骤self.model model or os.getenv(LLM_MODEL_ID) apiKey apiKey or os.getenv(LLM_API_KEY) baseUrl baseUrl or os.getenv(LLM_BASE_URL) timeout timeout or int(os.getenv(LLM_TIMEOUT, 60)) if not all([self.model, apiKey, baseUrl]): raise ValueError(模型ID、API密钥和服务地址必须被提供或在.env文件中定义。)对应的.env配置项含义如下环境变量说明默认值LLM_MODEL_ID模型标识兼容 OpenAI 接口的任意模型名必填无默认LLM_API_KEY服务商 API 密钥必填无默认LLM_BASE_URL兼容 OpenAI 接口的服务地址必填无默认LLM_TIMEOUT请求超时秒60客户端的think方法llm_client.py统一采用流式调用发起streamTrue的chat.completions.create请求后逐块打印delta.content并拼接返回完整文本temperature默认为 0保证推理任务的确定性。由于它只依赖openai官方客户端且仅要求接口兼容切换到任何 OpenAI 风格的服务端自部署、ModelScope、OpenAI 等只需改.env三个变量即可。ReAct 循环的最小实现ReAct.py 中的ReActAgent是理解推理—行动—观察循环的最佳样本核心机制有四点提示词约定REACT_PROMPT_TEMPLATE要求模型严格输出Thought:与Action:两段其中 Action 只有两种合法形式——{tool_name}[{tool_input}]调用工具或Finish[最终答案]结束ReAct.py最大步数控制构造参数max_steps默认为 5run循环超过步数即终止并返回None防止死循环正则解析_parse_output用Thought:\s*(.*?)(?\nAction:|$)与Action:\s*(.*?)$两条正则从模型输出中提取思考与行动_parse_action再按(\w)\[(.*)\]拆分工具名与参数历史回灌每轮执行后将Action与Observation追加进self.history下一轮提示词中作为上下文回灌形成记忆闭环。其主程序示例展示了工具注册与运行的完整链路llm HelloAgentsLLM() tool_executor ToolExecutor() search_desc 一个网页搜索引擎。当你需要回答关于时事、事实以及在你的知识库中找不到的信息时应使用此工具。 tool_executor.registerTool(Search, search_desc, search) agent ReActAgent(llm_clientllm, tool_executortool_executor) agent.run(华为最新的手机是哪一款它的主要卖点是什么)值得注意的细节工具注册时传入的自然语言描述会直接渲染进提示词的可用工具区——这正体现了 README 中LLM 作为数据处理后端的反面AI Native 范式中工具语义必须由模型自己理解并决策调用。3.3 第五、六章低代码平台与主流框架第五章配套材料位于 code/chapter5 目录包含 Coze、Dify、FastGPT、n8n 四个平台的可导入工程文件如 HelloAgent_difyCase.yml、HelloAgent_n8nCase.json可直接导入对应平台复现教程中的工作流。第六章配套代码按框架分子目录组织每个框架一个 Demo 目录含说明与依赖清单code/chapter6/AgentScopeDemocode/chapter6/AutoGenDemocode/chapter6/CAMELcode/chapter6/Langgraph这些 Demo 的作用是横向对比各框架对多智能体对话的抽象差异为第七章自研框架提供设计参照。3.4 第七章自研框架 HelloAgents 的分层扩展第七章配套代码 code/chapter7 演示了基于框架基类做扩展的三层结构LLM 层、Agent 层、编排层。LLM 层——以 provider 分发扩展模型接入。my_llm.py 中的MyLLM继承HelloAgentsLLM在构造函数中拦截providermodelscope的分支自行解析MODELSCOPE_API_KEY环境变量、指定 ModelScope 推理网关的base_url与默认模型并用OpenAI官方客户端创建连接其余 provider 则原样回落到super().__init__(...)if provider modelscope: self.api_key api_key or os.getenv(MODELSCOPE_API_KEY) self.base_url base_url or https://api-inference.modelscope.cn/v1/ ... self._client OpenAI(api_keyself.api_key, base_urlself.base_url, timeoutself.timeout) else: super().__init__(modelmodel, api_keyapi_key, base_urlbase_url, providerprovider, **kwargs)这个拦截 回落模式说明由于 OpenAI SDK 的接口兼容性为框架新增一个模型供应商只需要在构造期替换clientthink等运行时方法全部继承复用。my_main.py 则展示了最小验证方式MyLLM(providermodelscope)实例化后直接调用llm.think(messages)获得流式响应。Agent 层——继承基类重写 run 方法。my_simple_agent.py 中的MySimpleAgent(SimpleAgent)演示了带工具调用开关的对话 Agentrun方法先拼装 system含增强后的工具信息与历史消息若未启用工具调用则直接self.llm.invoke(messages)并记录Message历史启用时转入_run_with_tools处理多轮工具迭代默认max_tool_iterations3。my_react_agent.py 中的MyReActAgent(ReActAgent)则展示了提示词模板可替换性——custom_prompt参数允许传入自定义的MY_REACT_PROMPT结构上比第四章版本增加了工作流程重要提醒等结构化分节max_steps同样默认 5。从源码结构看第七章配套的my_*.py文件正是教材所讲的框架基类 用户扩展分层的实物基类负责消息管理、配置Config、工具注册表ToolRegistry等横切关注点用户只需关注提示词与执行策略。3.5 第八章记忆与检索的完整应用样例第八章配套 code/chapter8 共 11 个由浅入深的脚本从 01_MemoryTool_Basic_Operations.py 的 MemoryTool 基本操作到 04_RAGTool_MarkItDown_Pipeline.py 的 RAG 流水线再到 10_RAG_Pipeline_Complete.py 的完整 RAG 链路。最有实战价值的是 11_QA_Assistant.py——一个基于 HelloAgents 的 PDF 学习助手Gradio 界面。其PDFLearningAssistant类在初始化时同时挂载两个工具MemoryTool(user_id...)负责按用户隔离的学习历程记忆RAGTool(rag_namespacefpdf_{user_id})负责按用户隔离的文档知识库并内置会话统计加载文档数、提问数、学习概念数——这正是第八章记忆 检索两大主题在一个应用中的合体形态。3.6 第九章至第十二章上下文工程、协议、训练与评估code/chapter9上下文工程配套代码含 codebase_maintainer.py、上下文构建器、笔记工具、终端工具等 6 个示例脚本与 READMEcode/chapter10通信协议章节文件命名即实验序列——01_TestConnect.py到02_Connect2MCP.py建立 MCP 连接03_GitHubMCP.py使用现成 MCP04_MCPTransport.py与 my_mcp_server.py 自建 MCP 服务05_UseMCPToolInAgent.py把 MCP 工具接入智能体06_MultiAgentDocumentAssist.py做多智能体协作随后 A2A 系列07_SimpleA2AAgent.py至10_A2ATool_Simple.py与 ANP 系列11_ANPInit.py至13_ANPLoadBalancing.py分别覆盖点对点协议与网络协议并附带独立天气 MCP 服务器示例14_weather_mcp_server.pycode/chapter11Agentic-RL 训练实战按流水线组织01_dataset_loading.py → 02_reward_functions.py → 04_sft_training.py → 05_grpo_training.py → 07_model_evaluation.py并提供 06_complete_pipeline.py 一键全流水线、08_distributed_training.py 分布式训练以及accelerate_configs/下的多卡 YAML 配置code/chapter12性能评估实战含 BFCL 快速上手02_bfcl_quick_start.py、自定义评估03_bfcl_custom_evaluation.py、GAIA 基准实践05_gaia_quick_start.py、数据生成与 LLM-as-Judge 胜率评估08_data_generation_llm_judge.py、09_data_generation_win_rate.py并附 README。3.7 第十三章至第十六章综合案例工程第四部分与毕业设计对应的是四个完整工程目录工程对应章节路径智能旅行助手MCP 多智能体协作第十三章code/chapter13/helloagents-trip-planner自动化深度研究智能体DeepResearch 复现第十四章code/chapter14/helloagents-deepresearch赛博小镇Godot 游戏 Agent 社会模拟第十五章code/chapter15/Helloagents-AI-Town毕业设计共创路径说明第十六章code/chapter16/共创路径.md其中 code/chapter16/共创路径.md 指出生成毕业设计的具体实现统一收录在 Co-creation-projects 目录见 Co-creation-projects/README.md该目录汇集了社区贡献者提交的完整毕业设计项目如数据分析、数据库查询、股票洞察、邮件摘要、代码审查等数十个可运行的 Agent 应用可作为毕业设计选题的直接参照样本。四、本地运行指南从 clone 到跑通第一个 ReAct4.1 获取仓库本地学习需要克隆仓库文档与代码均在主干分支git clone https://gitcode.com/datawhalechina/hello-agents.git4.2 准备依赖与环境变量配套代码依赖openai官方 Python 客户端与python-dotenv.env 加载以第四章为例pip install openai python-dotenv然后在code/chapter4/下创建.env文件HelloAgentsLLM在 import 时会load_dotenv()LLM_MODEL_ID你的模型ID LLM_API_KEY你的API密钥 LLM_BASE_URL你的OpenAI兼容服务地址 LLM_TIMEOUT60配置缺失时客户端会抛出ValueError(模型ID、API密钥和服务地址必须被提供或在.env文件中定义。)见 llm_client.py这一显式报错机制便于快速定位配置问题。4.3 运行经典范式示例cd code/chapter4 python ReAct.py程序会按第 N 步分轮打印模型的思考Thought、行动Action与观察Observation最多执行 5 步后以Finish[最终答案]收尾或步数耗尽终止——对照 ReAct.py 的run方法即可逐步核对控制台输出与源码逻辑。第七章的 my_main.py 则是验证自研框架 LLM 层的最小入口运行前需额外设置MODELSCOPE_API_KEY或使用其他已支持的 provider。五、社区贡献精选与 Extra-Chapter 扩展阅读README 还维护了一张社区贡献精选表独立于正文的拓展内容统一放在 Extra-Chapter 目录。以下完整继承该表的 13 个扩展章节路径已转为仓库相对路径扩展章节内容主题Extra01-面试问题总结.mdAgent 岗位相关面试问题Extra01-参考答案.md相关面试问题答案Extra02-上下文工程补充知识.md上下文工程内容扩展Extra03-Dify智能体创建保姆级操作流程.mdDify 智能体创建保姆级教程Extra04-DatawhaleFAQ.mdDatawhale 课程常见问题Extra05-AgentSkills解读.mdAgent Skills 与 MCP 技术对比Extra06-GUIAgent科普与实战.mdGUI Agent 科普与多场景实战Extra07-环境配置.md环境配置Extra08-如何写出好的Skill.mdSkill 写作最佳实践Extra09-Agent应用开发实践踩坑与经验分享.mdCode Agent 应用开发踩坑与经验总结Extra10-Agent自进化.mdAgent 自进化四类闭环与代表项目Extra11-WebAgent科普与实战.mdWeb Agent 原理、反爬实战与 HelloAgents 集成Extra12-旅行助手后训练实战.md把旅行助手 Demo 打磨成能用的 PlannerExtra13-Hello-Agents视频课录制共创.md视频课程共创录制资源此外Co-creation-projects 目录收录了社区共创的毕业设计项目README 鼓励以 PR 形式向社区精选投稿。六、后续规划与许可说明README下一步规划部分给出了项目的演进方向视频课程陆续放出实践课将从设计思路讲到具体实施自研框架 HelloAgents 已更新至 V1.0.0 版本计划继续完善并增加更多轻量化工具与特性同时保持兼容学习版本计划推出后续作品《从零开始训练智能体》帮助学习者掌握从零到一训练自定义场景智能体模型的能力。关于引用与许可README 提供了 BibTeX 引用条目标题为Hello-Agents: Building an AI Agent from Scratch年份 2025供研究或工作引用本作品采用**知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议CC BY-NC-SA 4.0**许可二次传播请遵守该协议约定。七、小结Hello-Agents 以AI Native Agent为北极星用 16 章五部分搭建了一条从概念认知第一三章、范式实现第四七章、系统能力第八十二章到综合工程第十三十六章的完整学习路径code/目录中从 HelloAgentsLLM 客户端 到 ReAct 循环、框架扩展、MemoryTool RAGTool 应用、MCP/A2A/ANP 协议实验 直至 Agentic-RL 训练流水线 的可运行代码与正文形成一一对应的读一章、跑一章结构。建议的落地方式先按第二节的章节导航通读文档再在第三章对应小节运行配套代码遇到扩展主题面试、Skills、Web Agent、自进化等时查阅 Extra-Chapter最终以 Co-creation-projects 中的社区毕设作为选题参照完成属于自己的多智能体应用。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hello-Agents：从零构建 AI Native 智能体的完整学习路线、配套代码与实战解析
Hello-Agents从零构建 AI Native 智能体的完整学习路线、配套代码与实战解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsHello-Agents 是 Datawhale 社区推出的系统性智能体开源教程《从零开始构建智能体》的主仓库覆盖从智能体概念、经典范式ReAct、Plan-and-Solve、Reflection到记忆与检索、上下文工程、通信协议、Agentic-RL 训练及综合案例的全链路内容。本文基于仓库根目录的 README 展开并结合code/目录下各章配套源码带你理清这条从使用者到构建者的学习路径、每章配套代码的真实实现方式以及本地运行所需的环境配置细节。读完本文你可以明确 16 个章节各自解决什么问题、如何配合code/目录中的可运行代码动手实践以及社区扩展章节Extra-Chapter与共创项目库的用法。一、项目定位为什么强调AI Native AgentREADME 开篇给出了当前 Agent 构建领域的两分法这也是整个教程的立论基础软件工程类 Agent如 Dify、Coze、n8n 等低代码平台本质是流程驱动的软件开发LLM 作为数据处理的后端AI 原生 AgentAI Native Agent真正以 AI 驱动的智能体由模型自主完成推理、规划与工具调用。教程的目标是带领大家深入理解并构建后者。这一定位决定了课程结构低代码平台第五章与主流框架第六章只是用轮子的入门环节第七章节要求造轮子——基于 OpenAI 兼容 API 从零构建一个自己的智能体框架后续的第八章至第十二章记忆、检索、上下文工程、协议、训练、评估都建立在这个自研框架之上。教程同时承诺的收获清单见 README你将收获什么包括理解核心原理、掌握低代码平台与代码框架的使用、自研框架 HelloAgents、上下文工程与 Memory 等高级技能、从 SFT 到 GRPO 的 Agentic-RL 全流程实战、以及智能旅行助手与赛博小镇等综合案例。二、课程总体结构16 章五部分的章节导航仓库文档位于docs/目录侧边栏 与 README 的导航表一致全书按五大部分组织。下表完整继承 README 的章节导航链接已转换为仓库根目录相对路径并补充各部分的学习目标章节关键内容学习文档前言项目的缘起、背景及读者建议docs/前言.md第一部分智能体与语言模型基础第一章 初识智能体智能体定义、类型、范式与应用docs/chapter1/第一章%20初识智能体.md第二章 智能体发展史从符号主义到 LLM 驱动的智能体演进docs/chapter2/第二章%20智能体发展史.md第三章 大语言模型基础Transformer、提示、主流 LLM 及其局限docs/chapter3/第三章%20大语言模型基础.md第二部分构建你的大语言模型智能体第四章 智能体经典范式构建手把手实现 ReAct、Plan-and-Solve、Reflectiondocs/chapter4/第四章%20智能体经典范式构建.md第五章 基于低代码平台的智能体搭建Coze、Dify、n8n 等低代码平台使用docs/chapter5/第五章%20基于低代码平台的智能体搭建.md第六章 框架开发实践AutoGen、AgentScope、LangGraph 等主流框架docs/chapter6/第六章%20框架开发实践.md第七章 构建你的Agent框架从 0 开始构建智能体框架docs/chapter7/第七章%20构建你的Agent框架.md第三部分高级知识扩展第八章 记忆与检索记忆系统、RAG、存储docs/chapter8/第八章%20记忆与检索.md第九章 上下文工程持续交互的情境理解docs/chapter9/第九章%20上下文工程.md第十章 智能体通信协议MCP、A2A、ANP 等协议解析docs/chapter10/第十章%20智能体通信协议.md第十一章 Agentic-RL从 SFT 到 GRPO 的 LLM 训练实战docs/chapter11/第十一章%20Agentic-RL.md第十二章 智能体性能评估核心指标、基准测试与评估框架docs/chapter12/第十二章%20智能体性能评估.md第四部分综合案例进阶第十三章 智能旅行助手MCP 与多智能体协作的真实世界应用docs/chapter13/第十三章%20智能旅行助手.md第十四章 自动化深度研究智能体DeepResearch Agent 复现与解析docs/chapter14/第十四章%20自动化深度研究智能体.md第十五章 构建赛博小镇Agent 与游戏的结合模拟社会动态docs/chapter15/第十五章%20构建赛博小镇.md第五部分毕业设计及未来展望第十六章 毕业设计构建属于你的完整多智能体应用docs/chapter16/第十六章%20毕业设计.mdREADME 对五部分的学习路径还有一段精炼的说明值得直接引用第一部分第一三章从智能体的定义、类型与发展历史讲起梳理概念来龙去脉并快速巩固大语言模型核心知识打下理论地基第二部分第四七章动手实践起点。亲手实现 ReAct 等经典范式体验 Coze 等低代码平台掌握 LangGraph 等主流框架最终从零构建自己的智能体框架兼具用轮子与造轮子的能力第三部分第八十二章使用第二部分自研框架深入记忆与检索、上下文工程、Agent 训练、通信协议并掌握评估智能体系统性能的专业方法第四部分第十三十五章理论与实践的交汇点打造智能旅行助手、自动化深度研究智能体、模拟社会动态的赛博小镇第五部分第十六章毕业设计构建完整的属于自己的多智能体应用并展望智能体前沿方向。学习前置条件README 明确了读者画像与前置要求学习前请对照自查适合人群有一定编程基础的 AI 开发者、软件工程师、在校学生以及对前沿 AI 技术有兴趣的自学者前置能力基础 Python 编程能力对大语言模型有基本概念性了解例如知道如何通过 API 调用一个 LLM明确不要求深厚的算法或模型训练背景——项目重点在应用与构建。三、配套代码总览code 目录与章节一一对应README 强调智能体是一个飞速发展且极度依赖实践的领域并强烈建议将理论与实践结合亲手运行、调试甚至修改code/目录中的每一份代码。code/目录与docs/中的 16 个章节一一对应下面按学习顺序梳理各章配套代码的实际内容与结构。3.1 第一章第一次与智能体对话FirstAgentTest.py及同名 Notebook是全书的第一个程序用于完成最朴素的用户输入—模型响应闭环作为后续所有范式的对照基线。3.2 第四章三大经典范式的可运行实现第四章配套代码位于 code/chapter4 目录包含四个文件构成一个最小但完整的智能体运行时llm_client.pyHelloAgentsLLM客户端是全章及后续示例的模型调用底座tools.pyToolExecutor与内置工具如网页搜索演示注册—描述—执行的工具管理方式ReAct.py、Plan_and_solve.py、Reflection.py三种经典范式的独立实现。LLM 客户端与 .env 环境变量约定llm_client.py 中的HelloAgentsLLM初始化逻辑定义了全教程统一的环境变量约定这也是本地运行任何配套代码前的首要配置步骤self.model model or os.getenv(LLM_MODEL_ID) apiKey apiKey or os.getenv(LLM_API_KEY) baseUrl baseUrl or os.getenv(LLM_BASE_URL) timeout timeout or int(os.getenv(LLM_TIMEOUT, 60)) if not all([self.model, apiKey, baseUrl]): raise ValueError(模型ID、API密钥和服务地址必须被提供或在.env文件中定义。)对应的.env配置项含义如下环境变量说明默认值LLM_MODEL_ID模型标识兼容 OpenAI 接口的任意模型名必填无默认LLM_API_KEY服务商 API 密钥必填无默认LLM_BASE_URL兼容 OpenAI 接口的服务地址必填无默认LLM_TIMEOUT请求超时秒60客户端的think方法llm_client.py统一采用流式调用发起streamTrue的chat.completions.create请求后逐块打印delta.content并拼接返回完整文本temperature默认为 0保证推理任务的确定性。由于它只依赖openai官方客户端且仅要求接口兼容切换到任何 OpenAI 风格的服务端自部署、ModelScope、OpenAI 等只需改.env三个变量即可。ReAct 循环的最小实现ReAct.py 中的ReActAgent是理解推理—行动—观察循环的最佳样本核心机制有四点提示词约定REACT_PROMPT_TEMPLATE要求模型严格输出Thought:与Action:两段其中 Action 只有两种合法形式——{tool_name}[{tool_input}]调用工具或Finish[最终答案]结束ReAct.py最大步数控制构造参数max_steps默认为 5run循环超过步数即终止并返回None防止死循环正则解析_parse_output用Thought:\s*(.*?)(?\nAction:|$)与Action:\s*(.*?)$两条正则从模型输出中提取思考与行动_parse_action再按(\w)\[(.*)\]拆分工具名与参数历史回灌每轮执行后将Action与Observation追加进self.history下一轮提示词中作为上下文回灌形成记忆闭环。其主程序示例展示了工具注册与运行的完整链路llm HelloAgentsLLM() tool_executor ToolExecutor() search_desc 一个网页搜索引擎。当你需要回答关于时事、事实以及在你的知识库中找不到的信息时应使用此工具。 tool_executor.registerTool(Search, search_desc, search) agent ReActAgent(llm_clientllm, tool_executortool_executor) agent.run(华为最新的手机是哪一款它的主要卖点是什么)值得注意的细节工具注册时传入的自然语言描述会直接渲染进提示词的可用工具区——这正体现了 README 中LLM 作为数据处理后端的反面AI Native 范式中工具语义必须由模型自己理解并决策调用。3.3 第五、六章低代码平台与主流框架第五章配套材料位于 code/chapter5 目录包含 Coze、Dify、FastGPT、n8n 四个平台的可导入工程文件如 HelloAgent_difyCase.yml、HelloAgent_n8nCase.json可直接导入对应平台复现教程中的工作流。第六章配套代码按框架分子目录组织每个框架一个 Demo 目录含说明与依赖清单code/chapter6/AgentScopeDemocode/chapter6/AutoGenDemocode/chapter6/CAMELcode/chapter6/Langgraph这些 Demo 的作用是横向对比各框架对多智能体对话的抽象差异为第七章自研框架提供设计参照。3.4 第七章自研框架 HelloAgents 的分层扩展第七章配套代码 code/chapter7 演示了基于框架基类做扩展的三层结构LLM 层、Agent 层、编排层。LLM 层——以 provider 分发扩展模型接入。my_llm.py 中的MyLLM继承HelloAgentsLLM在构造函数中拦截providermodelscope的分支自行解析MODELSCOPE_API_KEY环境变量、指定 ModelScope 推理网关的base_url与默认模型并用OpenAI官方客户端创建连接其余 provider 则原样回落到super().__init__(...)if provider modelscope: self.api_key api_key or os.getenv(MODELSCOPE_API_KEY) self.base_url base_url or https://api-inference.modelscope.cn/v1/ ... self._client OpenAI(api_keyself.api_key, base_urlself.base_url, timeoutself.timeout) else: super().__init__(modelmodel, api_keyapi_key, base_urlbase_url, providerprovider, **kwargs)这个拦截 回落模式说明由于 OpenAI SDK 的接口兼容性为框架新增一个模型供应商只需要在构造期替换clientthink等运行时方法全部继承复用。my_main.py 则展示了最小验证方式MyLLM(providermodelscope)实例化后直接调用llm.think(messages)获得流式响应。Agent 层——继承基类重写 run 方法。my_simple_agent.py 中的MySimpleAgent(SimpleAgent)演示了带工具调用开关的对话 Agentrun方法先拼装 system含增强后的工具信息与历史消息若未启用工具调用则直接self.llm.invoke(messages)并记录Message历史启用时转入_run_with_tools处理多轮工具迭代默认max_tool_iterations3。my_react_agent.py 中的MyReActAgent(ReActAgent)则展示了提示词模板可替换性——custom_prompt参数允许传入自定义的MY_REACT_PROMPT结构上比第四章版本增加了工作流程重要提醒等结构化分节max_steps同样默认 5。从源码结构看第七章配套的my_*.py文件正是教材所讲的框架基类 用户扩展分层的实物基类负责消息管理、配置Config、工具注册表ToolRegistry等横切关注点用户只需关注提示词与执行策略。3.5 第八章记忆与检索的完整应用样例第八章配套 code/chapter8 共 11 个由浅入深的脚本从 01_MemoryTool_Basic_Operations.py 的 MemoryTool 基本操作到 04_RAGTool_MarkItDown_Pipeline.py 的 RAG 流水线再到 10_RAG_Pipeline_Complete.py 的完整 RAG 链路。最有实战价值的是 11_QA_Assistant.py——一个基于 HelloAgents 的 PDF 学习助手Gradio 界面。其PDFLearningAssistant类在初始化时同时挂载两个工具MemoryTool(user_id...)负责按用户隔离的学习历程记忆RAGTool(rag_namespacefpdf_{user_id})负责按用户隔离的文档知识库并内置会话统计加载文档数、提问数、学习概念数——这正是第八章记忆 检索两大主题在一个应用中的合体形态。3.6 第九章至第十二章上下文工程、协议、训练与评估code/chapter9上下文工程配套代码含 codebase_maintainer.py、上下文构建器、笔记工具、终端工具等 6 个示例脚本与 READMEcode/chapter10通信协议章节文件命名即实验序列——01_TestConnect.py到02_Connect2MCP.py建立 MCP 连接03_GitHubMCP.py使用现成 MCP04_MCPTransport.py与 my_mcp_server.py 自建 MCP 服务05_UseMCPToolInAgent.py把 MCP 工具接入智能体06_MultiAgentDocumentAssist.py做多智能体协作随后 A2A 系列07_SimpleA2AAgent.py至10_A2ATool_Simple.py与 ANP 系列11_ANPInit.py至13_ANPLoadBalancing.py分别覆盖点对点协议与网络协议并附带独立天气 MCP 服务器示例14_weather_mcp_server.pycode/chapter11Agentic-RL 训练实战按流水线组织01_dataset_loading.py → 02_reward_functions.py → 04_sft_training.py → 05_grpo_training.py → 07_model_evaluation.py并提供 06_complete_pipeline.py 一键全流水线、08_distributed_training.py 分布式训练以及accelerate_configs/下的多卡 YAML 配置code/chapter12性能评估实战含 BFCL 快速上手02_bfcl_quick_start.py、自定义评估03_bfcl_custom_evaluation.py、GAIA 基准实践05_gaia_quick_start.py、数据生成与 LLM-as-Judge 胜率评估08_data_generation_llm_judge.py、09_data_generation_win_rate.py并附 README。3.7 第十三章至第十六章综合案例工程第四部分与毕业设计对应的是四个完整工程目录工程对应章节路径智能旅行助手MCP 多智能体协作第十三章code/chapter13/helloagents-trip-planner自动化深度研究智能体DeepResearch 复现第十四章code/chapter14/helloagents-deepresearch赛博小镇Godot 游戏 Agent 社会模拟第十五章code/chapter15/Helloagents-AI-Town毕业设计共创路径说明第十六章code/chapter16/共创路径.md其中 code/chapter16/共创路径.md 指出生成毕业设计的具体实现统一收录在 Co-creation-projects 目录见 Co-creation-projects/README.md该目录汇集了社区贡献者提交的完整毕业设计项目如数据分析、数据库查询、股票洞察、邮件摘要、代码审查等数十个可运行的 Agent 应用可作为毕业设计选题的直接参照样本。四、本地运行指南从 clone 到跑通第一个 ReAct4.1 获取仓库本地学习需要克隆仓库文档与代码均在主干分支git clone https://gitcode.com/datawhalechina/hello-agents.git4.2 准备依赖与环境变量配套代码依赖openai官方 Python 客户端与python-dotenv.env 加载以第四章为例pip install openai python-dotenv然后在code/chapter4/下创建.env文件HelloAgentsLLM在 import 时会load_dotenv()LLM_MODEL_ID你的模型ID LLM_API_KEY你的API密钥 LLM_BASE_URL你的OpenAI兼容服务地址 LLM_TIMEOUT60配置缺失时客户端会抛出ValueError(模型ID、API密钥和服务地址必须被提供或在.env文件中定义。)见 llm_client.py这一显式报错机制便于快速定位配置问题。4.3 运行经典范式示例cd code/chapter4 python ReAct.py程序会按第 N 步分轮打印模型的思考Thought、行动Action与观察Observation最多执行 5 步后以Finish[最终答案]收尾或步数耗尽终止——对照 ReAct.py 的run方法即可逐步核对控制台输出与源码逻辑。第七章的 my_main.py 则是验证自研框架 LLM 层的最小入口运行前需额外设置MODELSCOPE_API_KEY或使用其他已支持的 provider。五、社区贡献精选与 Extra-Chapter 扩展阅读README 还维护了一张社区贡献精选表独立于正文的拓展内容统一放在 Extra-Chapter 目录。以下完整继承该表的 13 个扩展章节路径已转为仓库相对路径扩展章节内容主题Extra01-面试问题总结.mdAgent 岗位相关面试问题Extra01-参考答案.md相关面试问题答案Extra02-上下文工程补充知识.md上下文工程内容扩展Extra03-Dify智能体创建保姆级操作流程.mdDify 智能体创建保姆级教程Extra04-DatawhaleFAQ.mdDatawhale 课程常见问题Extra05-AgentSkills解读.mdAgent Skills 与 MCP 技术对比Extra06-GUIAgent科普与实战.mdGUI Agent 科普与多场景实战Extra07-环境配置.md环境配置Extra08-如何写出好的Skill.mdSkill 写作最佳实践Extra09-Agent应用开发实践踩坑与经验分享.mdCode Agent 应用开发踩坑与经验总结Extra10-Agent自进化.mdAgent 自进化四类闭环与代表项目Extra11-WebAgent科普与实战.mdWeb Agent 原理、反爬实战与 HelloAgents 集成Extra12-旅行助手后训练实战.md把旅行助手 Demo 打磨成能用的 PlannerExtra13-Hello-Agents视频课录制共创.md视频课程共创录制资源此外Co-creation-projects 目录收录了社区共创的毕业设计项目README 鼓励以 PR 形式向社区精选投稿。六、后续规划与许可说明README下一步规划部分给出了项目的演进方向视频课程陆续放出实践课将从设计思路讲到具体实施自研框架 HelloAgents 已更新至 V1.0.0 版本计划继续完善并增加更多轻量化工具与特性同时保持兼容学习版本计划推出后续作品《从零开始训练智能体》帮助学习者掌握从零到一训练自定义场景智能体模型的能力。关于引用与许可README 提供了 BibTeX 引用条目标题为Hello-Agents: Building an AI Agent from Scratch年份 2025供研究或工作引用本作品采用**知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议CC BY-NC-SA 4.0**许可二次传播请遵守该协议约定。七、小结Hello-Agents 以AI Native Agent为北极星用 16 章五部分搭建了一条从概念认知第一三章、范式实现第四七章、系统能力第八十二章到综合工程第十三十六章的完整学习路径code/目录中从 HelloAgentsLLM 客户端 到 ReAct 循环、框架扩展、MemoryTool RAGTool 应用、MCP/A2A/ANP 协议实验 直至 Agentic-RL 训练流水线 的可运行代码与正文形成一一对应的读一章、跑一章结构。建议的落地方式先按第二节的章节导航通读文档再在第三章对应小节运行配套代码遇到扩展主题面试、Skills、Web Agent、自进化等时查阅 Extra-Chapter最终以 Co-creation-projects 中的社区毕设作为选题参照完成属于自己的多智能体应用。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考