构建你的Agent框架：从零打造HelloAgents

在前几章中，我们学习了智能体的基础知识，也体验了主流框架带来的开发便利。但从本章开始，我们将进入一个更具挑战性也更有价值的阶段：从零构建一个属于自己的Agent框架——HelloAgents。

需要说明的是，“从零”并不意味着凭空发明——我们将基于对Agent工作原理的深入理解，参考HelloAgents的设计思路，亲手实现每一个核心组件。这是一次从 “使用者”到“构建者” 的能力跃迁。

📊 全文知识框架图

#mermaid-svg-FZxr1Tb8RBkbkTml{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FZxr1Tb8RBkbkTml .error-icon{fill:#552222;}#mermaid-svg-FZxr1Tb8RBkbkTml .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FZxr1Tb8RBkbkTml .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FZxr1Tb8RBkbkTml .marker.cross{stroke:#333333;}#mermaid-svg-FZxr1Tb8RBkbkTml svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FZxr1Tb8RBkbkTml p{margin:0;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge{stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 path{fill:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 text{fill:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon–1{font-size:40px;color:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge–1{stroke:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth–1{stroke-width:17;}#mermaid-svg-FZxr1Tb8RBkbkTml .section–1 line{stroke:hsl(60, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 path{fill:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-0{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-0{stroke:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-0{stroke-width:14;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-0 line{stroke:hsl(240, 100%, 83.5294117647%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 path{fill:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-1{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-1{stroke:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-1{stroke-width:11;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-1 line{stroke:hsl(260, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 path{fill:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 text{fill:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-2{font-size:40px;color:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-2{stroke:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-2{stroke-width:8;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 line{stroke:hsl(90, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 path{fill:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-3{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-3{stroke:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-3{stroke-width:5;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-3 line{stroke:hsl(120, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 path{fill:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-4{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-4{stroke:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-4{stroke-width:2;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-4 line{stroke:hsl(150, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 path{fill:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-5{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-5{stroke:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-5{stroke-width:-1;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-5 line{stroke:hsl(180, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 path{fill:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-6{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-6{stroke:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-6{stroke-width:-4;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-6 line{stroke:hsl(210, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 path{fill:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-7{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-7{stroke:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-7{stroke-width:-7;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-7 line{stroke:hsl(270, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 path{fill:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-8{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-8{stroke:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-8{stroke-width:-10;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-8 line{stroke:hsl(330, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 path{fill:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-9{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-9{stroke:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-9{stroke-width:-13;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-9 line{stroke:hsl(0, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 polygon,#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 path{fill:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 text{fill:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .node-icon-10{font-size:40px;color:black;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-edge-10{stroke:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .edge-depth-10{stroke-width:-16;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-10 line{stroke:hsl(30, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled circle,#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:lightgray;}#mermaid-svg-FZxr1Tb8RBkbkTml .disabled text{fill:#efefef;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-root rect,#mermaid-svg-FZxr1Tb8RBkbkTml .section-root path,#mermaid-svg-FZxr1Tb8RBkbkTml .section-root circle,#mermaid-svg-FZxr1Tb8RBkbkTml .section-root polygon{fill:hsl(240, 100%, 46.2745098039%);}#mermaid-svg-FZxr1Tb8RBkbkTml .section-root text{fill:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-root span{color:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .section-2 span{color:#ffffff;}#mermaid-svg-FZxr1Tb8RBkbkTml .icon-container{height:100%;display:flex;justify-content:center;align-items:center;}#mermaid-svg-FZxr1Tb8RBkbkTml .edge{fill:none;}#mermaid-svg-FZxr1Tb8RBkbkTml .mindmap-node-label{dy:1em;alignment-baseline:middle;text-anchor:middle;dominant-baseline:middle;text-align:center;}#mermaid-svg-FZxr1Tb8RBkbkTml :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

构建你的Agent框架

为什么自建框架

市场框架的局限

抽象过重

迭代太快

黑盒化严重

依赖复杂

自建框架的价值

深入理解原理

获得完全控制

培养系统设计能力

HelloAgents设计理念

轻量与教学友好

基于标准API

渐进式学习路径

统一工具抽象

核心架构

核心框架层

Message

Config

LLM客户端

Agent实现层

BaseAgent

范式实现

工具系统层

统一工具抽象

工具执行器

范式实现

ReAct

Reflection

Plan-and-Solve

一、为什么要自己造一个框架？

在Agent技术飞速发展的今天，市面上已经有了LangChain、AutoGen等成熟的框架。为什么还要自己造一个？

1.1 市场框架的“四重困境”

第一重：抽象过重

许多框架为了追求通用性，引入了大量抽象层和配置选项。以LangChain为例，它的链式调用机制虽然灵活，但对初学者来说学习曲线陡峭——为了完成一个简单任务，往往需要理解Chain、Agent、Tool、Memory、Retriever等十多个概念。

第二重：迭代太快

商业框架为了抢占市场，API接口频繁变更。开发者常常遇到“代码升级后无法运行”的窘境，维护成本居高不下。

第三重：黑盒化严重

许多框架将核心逻辑封装得太严实，开发者难以理解Agent内部的工作机制，缺乏深度定制能力。遇到问题时只能依赖文档和社区，如果社区不够活跃，反馈可能需要很长时间。

第四重：依赖复杂

成熟框架往往携带大量依赖包，安装包体积庞大，当需要与其他项目代码配合时，可能引发依赖冲突问题。

1.2 从“使用者”到“构建者”的能力跃迁

自己构建Agent框架，实际上是一次从“使用者”到“构建者”的转变。这种转变带来的价值是长期的：

在实际应用中，不同场景对Agent的需求差异很大，往往需要基于通用框架进行二次开发。垂直领域（如金融、医疗、教育）通常需要有针对性的提示词模板、特殊的工具集成和定制化的安全策略。自建框架让我们能够精确控制响应时间、内存使用和并发处理能力，满足生产环境的精细化需求。

二、HelloAgents的设计理念

构建一个新框架，关键不在于功能多寡，而在于设计理念能否真正解决现有框架的痛点。

HelloAgents围绕一个核心问题展开设计：如何让学习者既能快速上手，又能深入理解Agent的工作原理？

2.1 轻量与教学友好的平衡

优秀的教学框架应该具备完整的可读性。HelloAgents按章节分离核心代码，遵循一个简单的原则：任何有一定编程基础的开发者，都应该能在合理时间内完全理解框架的工作原理。

在依赖管理上，框架采用极简策略——除了必要的HTTP请求库和基础工具库外，不引入任何与特定平台绑定的重型依赖。遇到问题时，可以直接定位到框架自身代码，无需在复杂的依赖关系中寻找答案。

2.2 基于标准API的务实选择

OpenAI的API已成为行业标准，几乎所有主流LLM提供商都在努力兼容这一接口。HelloAgents选择基于这一标准构建，而非重新发明一套抽象接口。

这一决策主要基于三点考虑：

• 兼容性保障：掌握HelloAgents后，迁移到其他框架或将其集成到现有项目中时，底层的API调用逻辑完全一致。
• 降低学习成本：无需学习新的概念模型，所有操作都基于你已熟悉的标准接口。
• 跨平台扩展：通过继承HelloAgentsLLM类并重写部分方法，可以轻松扩展对ModelScope、智谱AI等不同平台的支持。

2.3 渐进式的学习路径

HelloAgents提供一条清晰的学习路径。每一章的学习代码都会保存为一个可通过pip安装的历史版本，无需担心使用代码的成本——因为每个核心功能都将由你自己编写。

这种设计让你可以根据自己的需求和节奏前进。每一次升级都是自然的，不会出现概念跳跃或理解断层。

2.4 统一工具抽象：“一切皆工具”

为了彻底贯彻轻量和教学友好的理念，HelloAgents在架构上做了一个关键简化：除了核心的Agent类，一切都是工具。

记忆（Memory）、RAG（检索增强生成）、RL（强化学习）、MCP（协议）等模块，在众多其他框架中需要独立学习。但在HelloAgents中，它们都被统一抽象为“工具”，极大地降低了学习负担。

三、核心架构：一张图看懂HelloAgents

#mermaid-svg-ghyMrCiLIHdtK7Sx{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ghyMrCiLIHdtK7Sx .error-icon{fill:#552222;}#mermaid-svg-ghyMrCiLIHdtK7Sx .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ghyMrCiLIHdtK7Sx .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .marker.cross{stroke:#333333;}#mermaid-svg-ghyMrCiLIHdtK7Sx svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ghyMrCiLIHdtK7Sx p{margin:0;}#mermaid-svg-ghyMrCiLIHdtK7Sx .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster-label text{fill:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster-label span{color:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster-label span p{background-color:transparent;}#mermaid-svg-ghyMrCiLIHdtK7Sx .label text,#mermaid-svg-ghyMrCiLIHdtK7Sx span{fill:#333;color:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .node rect,#mermaid-svg-ghyMrCiLIHdtK7Sx .node circle,#mermaid-svg-ghyMrCiLIHdtK7Sx .node ellipse,#mermaid-svg-ghyMrCiLIHdtK7Sx .node polygon,#mermaid-svg-ghyMrCiLIHdtK7Sx .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .rough-node .label text,#mermaid-svg-ghyMrCiLIHdtK7Sx .node .label text,#mermaid-svg-ghyMrCiLIHdtK7Sx .image-shape .label,#mermaid-svg-ghyMrCiLIHdtK7Sx .icon-shape .label{text-anchor:middle;}#mermaid-svg-ghyMrCiLIHdtK7Sx .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .rough-node .label,#mermaid-svg-ghyMrCiLIHdtK7Sx .node .label,#mermaid-svg-ghyMrCiLIHdtK7Sx .image-shape .label,#mermaid-svg-ghyMrCiLIHdtK7Sx .icon-shape .label{text-align:center;}#mermaid-svg-ghyMrCiLIHdtK7Sx .node.clickable{cursor:pointer;}#mermaid-svg-ghyMrCiLIHdtK7Sx .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .arrowheadPath{fill:#333333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ghyMrCiLIHdtK7Sx .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ghyMrCiLIHdtK7Sx .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ghyMrCiLIHdtK7Sx .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster text{fill:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx .cluster span{color:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ghyMrCiLIHdtK7Sx .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ghyMrCiLIHdtK7Sx rect.text{fill:none;stroke-width:0;}#mermaid-svg-ghyMrCiLIHdtK7Sx .icon-shape,#mermaid-svg-ghyMrCiLIHdtK7Sx .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ghyMrCiLIHdtK7Sx .icon-shape p,#mermaid-svg-ghyMrCiLIHdtK7Sx .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ghyMrCiLIHdtK7Sx .icon-shape .label rect,#mermaid-svg-ghyMrCiLIHdtK7Sx .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ghyMrCiLIHdtK7Sx .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ghyMrCiLIHdtK7Sx .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ghyMrCiLIHdtK7Sx :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

工具系统层

Agent实现层

核心框架层

📨 Message统一消息格式

⚙️ Config配置管理

🧠 HelloAgentsLLMLLM客户端

📋 BaseAgent智能体基类

🔄 ReActAgent思考-行动-观察

🔍 ReflectionAgent自我反思

📝 PlanAndSolveAgent先规划后执行

🔧 Tool统一工具抽象

⚡ ToolExecutor工具执行器

💾 Memory记忆工具

📚 RAG检索工具

HelloAgents的架构分为三个层次：

核心框架层：提供最基础的组件——Message（统一消息格式）、Config（配置管理）和HelloAgentsLLM（LLM客户端）。这一层是框架的“地基”。

Agent实现层：在核心框架层之上，实现具体的智能体范式——BaseAgent作为所有智能体的基类，以及ReActAgent、ReflectionAgent、PlanAndSolveAgent等具体实现。

工具系统层：提供统一的工具抽象和工具执行器，让智能体能够调用外部能力。

四、核心组件详解

4.1 Message类：统一消息格式

Message类是框架中最基础的组件之一，负责统一管理智能体之间的消息传递。

#mermaid-svg-r04NKxS9OCBxnxX6{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-r04NKxS9OCBxnxX6 .error-icon{fill:#552222;}#mermaid-svg-r04NKxS9OCBxnxX6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-r04NKxS9OCBxnxX6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-r04NKxS9OCBxnxX6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-r04NKxS9OCBxnxX6 .marker.cross{stroke:#333333;}#mermaid-svg-r04NKxS9OCBxnxX6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-r04NKxS9OCBxnxX6 p{margin:0;}#mermaid-svg-r04NKxS9OCBxnxX6 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster-label text{fill:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster-label span{color:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster-label span p{background-color:transparent;}#mermaid-svg-r04NKxS9OCBxnxX6 .label text,#mermaid-svg-r04NKxS9OCBxnxX6 span{fill:#333;color:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 .node rect,#mermaid-svg-r04NKxS9OCBxnxX6 .node circle,#mermaid-svg-r04NKxS9OCBxnxX6 .node ellipse,#mermaid-svg-r04NKxS9OCBxnxX6 .node polygon,#mermaid-svg-r04NKxS9OCBxnxX6 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-r04NKxS9OCBxnxX6 .rough-node .label text,#mermaid-svg-r04NKxS9OCBxnxX6 .node .label text,#mermaid-svg-r04NKxS9OCBxnxX6 .image-shape .label,#mermaid-svg-r04NKxS9OCBxnxX6 .icon-shape .label{text-anchor:middle;}#mermaid-svg-r04NKxS9OCBxnxX6 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-r04NKxS9OCBxnxX6 .rough-node .label,#mermaid-svg-r04NKxS9OCBxnxX6 .node .label,#mermaid-svg-r04NKxS9OCBxnxX6 .image-shape .label,#mermaid-svg-r04NKxS9OCBxnxX6 .icon-shape .label{text-align:center;}#mermaid-svg-r04NKxS9OCBxnxX6 .node.clickable{cursor:pointer;}#mermaid-svg-r04NKxS9OCBxnxX6 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-r04NKxS9OCBxnxX6 .arrowheadPath{fill:#333333;}#mermaid-svg-r04NKxS9OCBxnxX6 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-r04NKxS9OCBxnxX6 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-r04NKxS9OCBxnxX6 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-r04NKxS9OCBxnxX6 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-r04NKxS9OCBxnxX6 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-r04NKxS9OCBxnxX6 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster text{fill:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 .cluster span{color:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-r04NKxS9OCBxnxX6 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-r04NKxS9OCBxnxX6 rect.text{fill:none;stroke-width:0;}#mermaid-svg-r04NKxS9OCBxnxX6 .icon-shape,#mermaid-svg-r04NKxS9OCBxnxX6 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-r04NKxS9OCBxnxX6 .icon-shape p,#mermaid-svg-r04NKxS9OCBxnxX6 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-r04NKxS9OCBxnxX6 .icon-shape .label rect,#mermaid-svg-r04NKxS9OCBxnxX6 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-r04NKxS9OCBxnxX6 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-r04NKxS9OCBxnxX6 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-r04NKxS9OCBxnxX6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Message类设计

🎭 角色user/system/assistant/tool

📝 内容消息正文

⏱️ 时间戳创建时间

📊 元数据扩展信息

📨 Message

📄 to_dict()转换为OpenAI格式

设计上，role字段严格限制为四种类型："user"、"assistant"、"system"、"tool"，直接对应OpenAI API规范，确保类型安全。除了content和role两个核心字段，还增加了timestamp和metadata，为日志记录和未来功能扩展预留了空间。

to_dict()方法是其核心功能之一，负责将内部使用的Message对象转换为兼容OpenAI API的字典格式，体现了“内部丰富、对外兼容”的设计原则。

4.2 Config类：集中配置管理

Config类的职责是将代码中的硬编码配置参数集中管理，并支持从环境变量读取。它基于Pydantic的BaseModel实现，提供类型安全和自动验证。

# 需要从 typing 导入 Optional
from typing import Optional
from pydantic import BaseModel

class Config(BaseModel):
"""HelloAgents配置类"""
# LLM配置
default_model: str = "gpt-3.5-turbo"
default_provider: str = "openai"
temperature: float = 0.7
max_tokens: Optional[int] = None
# 系统配置
debug: bool = False
log_level: str = "INFO"

这种设计让配置管理更加清晰，也方便在不同环境中切换配置。

4.3 HelloAgentsLLM：智能的LLM客户端

HelloAgentsLLM是框架与外部LLM服务交互的核心桥梁。它的设计体现了“约定优于配置”的原则——尽量减少用户的配置负担。

自动检测Provider的优先级：

#mermaid-svg-RJUlQ0BXZbJCclTU{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-RJUlQ0BXZbJCclTU .error-icon{fill:#552222;}#mermaid-svg-RJUlQ0BXZbJCclTU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-RJUlQ0BXZbJCclTU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-RJUlQ0BXZbJCclTU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-RJUlQ0BXZbJCclTU .marker.cross{stroke:#333333;}#mermaid-svg-RJUlQ0BXZbJCclTU svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-RJUlQ0BXZbJCclTU p{margin:0;}#mermaid-svg-RJUlQ0BXZbJCclTU .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster-label text{fill:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster-label span{color:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster-label span p{background-color:transparent;}#mermaid-svg-RJUlQ0BXZbJCclTU .label text,#mermaid-svg-RJUlQ0BXZbJCclTU span{fill:#333;color:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU .node rect,#mermaid-svg-RJUlQ0BXZbJCclTU .node circle,#mermaid-svg-RJUlQ0BXZbJCclTU .node ellipse,#mermaid-svg-RJUlQ0BXZbJCclTU .node polygon,#mermaid-svg-RJUlQ0BXZbJCclTU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-RJUlQ0BXZbJCclTU .rough-node .label text,#mermaid-svg-RJUlQ0BXZbJCclTU .node .label text,#mermaid-svg-RJUlQ0BXZbJCclTU .image-shape .label,#mermaid-svg-RJUlQ0BXZbJCclTU .icon-shape .label{text-anchor:middle;}#mermaid-svg-RJUlQ0BXZbJCclTU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-RJUlQ0BXZbJCclTU .rough-node .label,#mermaid-svg-RJUlQ0BXZbJCclTU .node .label,#mermaid-svg-RJUlQ0BXZbJCclTU .image-shape .label,#mermaid-svg-RJUlQ0BXZbJCclTU .icon-shape .label{text-align:center;}#mermaid-svg-RJUlQ0BXZbJCclTU .node.clickable{cursor:pointer;}#mermaid-svg-RJUlQ0BXZbJCclTU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-RJUlQ0BXZbJCclTU .arrowheadPath{fill:#333333;}#mermaid-svg-RJUlQ0BXZbJCclTU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-RJUlQ0BXZbJCclTU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-RJUlQ0BXZbJCclTU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RJUlQ0BXZbJCclTU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-RJUlQ0BXZbJCclTU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RJUlQ0BXZbJCclTU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster text{fill:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU .cluster span{color:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-RJUlQ0BXZbJCclTU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-RJUlQ0BXZbJCclTU rect.text{fill:none;stroke-width:0;}#mermaid-svg-RJUlQ0BXZbJCclTU .icon-shape,#mermaid-svg-RJUlQ0BXZbJCclTU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RJUlQ0BXZbJCclTU .icon-shape p,#mermaid-svg-RJUlQ0BXZbJCclTU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-RJUlQ0BXZbJCclTU .icon-shape .label rect,#mermaid-svg-RJUlQ0BXZbJCclTU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RJUlQ0BXZbJCclTU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-RJUlQ0BXZbJCclTU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-RJUlQ0BXZbJCclTU :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

找到

未找到

匹配域名/端口

无法匹配

匹配格式

无法确定

🔍 开始检测Provider

🥇 最高优先级检查特定服务商的环境变量如 MODELSCOPE_API_KEY

✅ 确定Provider

🥈 第二优先级解析LLM_BASE_URL

🥉 第三优先级分析API Key格式

🔄 默认返回'auto'

Provider检测机制的核心逻辑：

一旦provider确定（无论是用户指定还是自动检测），_resolve_credentials方法会根据provider的值主动搜索对应的环境变量并设置默认的base_url。

4.4 扩展LLM客户端：支持新平台

HelloAgents的设计让扩展新的LLM平台变得非常简单——只需继承HelloAgentsLLM类并重写部分方法。

以扩展ModelScope平台为例：

这种“覆写”的方式确保了代码的整洁性和可维护性，即使未来升级hello-agents库，定制化的功能也不会丢失。

五、从范式到框架：ReAct、Reflection与Plan-and-Solve的实现

第四章我们学习了ReAct、Reflection和Plan-and-Solve三种经典范式。在HelloAgents框架中，我们将这些范式从“独立脚本”升级为“框架的标准化组件”。

#mermaid-svg-c0rQ81vTKCGjvJGX{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-c0rQ81vTKCGjvJGX .error-icon{fill:#552222;}#mermaid-svg-c0rQ81vTKCGjvJGX .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-c0rQ81vTKCGjvJGX .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-c0rQ81vTKCGjvJGX .marker{fill:#333333;stroke:#333333;}#mermaid-svg-c0rQ81vTKCGjvJGX .marker.cross{stroke:#333333;}#mermaid-svg-c0rQ81vTKCGjvJGX svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-c0rQ81vTKCGjvJGX p{margin:0;}#mermaid-svg-c0rQ81vTKCGjvJGX .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster-label text{fill:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster-label span{color:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster-label span p{background-color:transparent;}#mermaid-svg-c0rQ81vTKCGjvJGX .label text,#mermaid-svg-c0rQ81vTKCGjvJGX span{fill:#333;color:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX .node rect,#mermaid-svg-c0rQ81vTKCGjvJGX .node circle,#mermaid-svg-c0rQ81vTKCGjvJGX .node ellipse,#mermaid-svg-c0rQ81vTKCGjvJGX .node polygon,#mermaid-svg-c0rQ81vTKCGjvJGX .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-c0rQ81vTKCGjvJGX .rough-node .label text,#mermaid-svg-c0rQ81vTKCGjvJGX .node .label text,#mermaid-svg-c0rQ81vTKCGjvJGX .image-shape .label,#mermaid-svg-c0rQ81vTKCGjvJGX .icon-shape .label{text-anchor:middle;}#mermaid-svg-c0rQ81vTKCGjvJGX .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-c0rQ81vTKCGjvJGX .rough-node .label,#mermaid-svg-c0rQ81vTKCGjvJGX .node .label,#mermaid-svg-c0rQ81vTKCGjvJGX .image-shape .label,#mermaid-svg-c0rQ81vTKCGjvJGX .icon-shape .label{text-align:center;}#mermaid-svg-c0rQ81vTKCGjvJGX .node.clickable{cursor:pointer;}#mermaid-svg-c0rQ81vTKCGjvJGX .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-c0rQ81vTKCGjvJGX .arrowheadPath{fill:#333333;}#mermaid-svg-c0rQ81vTKCGjvJGX .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-c0rQ81vTKCGjvJGX .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-c0rQ81vTKCGjvJGX .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-c0rQ81vTKCGjvJGX .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-c0rQ81vTKCGjvJGX .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-c0rQ81vTKCGjvJGX .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster text{fill:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX .cluster span{color:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-c0rQ81vTKCGjvJGX .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-c0rQ81vTKCGjvJGX rect.text{fill:none;stroke-width:0;}#mermaid-svg-c0rQ81vTKCGjvJGX .icon-shape,#mermaid-svg-c0rQ81vTKCGjvJGX .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-c0rQ81vTKCGjvJGX .icon-shape p,#mermaid-svg-c0rQ81vTKCGjvJGX .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-c0rQ81vTKCGjvJGX .icon-shape .label rect,#mermaid-svg-c0rQ81vTKCGjvJGX .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-c0rQ81vTKCGjvJGX .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-c0rQ81vTKCGjvJGX .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-c0rQ81vTKCGjvJGX :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

范式实现

从范式到框架的升级

第四章独立脚本实现

升级重构

第七章框架标准化组件

🔄 ReAct范式

🔍 Reflection范式

📝 Plan-and-Solve范式

🔧 集成工具系统

💾 集成记忆模块

⚙️ 集成配置管理

5.1 从独立脚本到框架组件

在第四章中，我们通过编写独立的Python脚本来实现ReAct、Reflection和Plan-and-Solve。在HelloAgents框架中，这些实现被重新组织为：

• 继承BaseAgent：所有范式实现都继承自统一的BaseAgent基类
• 集成工具系统：ReAct的工具调用机制与框架的ToolExecutor无缝对接
• 统一消息格式：所有输入输出都使用Message类进行标准化
• 配置驱动：通过Config类集中管理各范式的参数

这种升级的核心价值在于复用性和可维护性——在框架层面实现一次，就可以在多个应用场景中重复使用。

5.2 设计原则

六、核心概念速查表（新手友好）

七、思考题（帮助加深理解）

参考资料

结语

在这一章中，我们完成了从“框架使用者”到“框架构建者”的转变：

• 为什么自建框架——市场框架存在抽象过重、迭代太快、黑盒化、依赖复杂等问题，自建框架能带来深入理解原理、获得完全控制、培养系统设计能力等长期价值
• HelloAgents的设计理念——轻量与教学友好、基于标准API、渐进式学习路径、统一工具抽象
• 核心架构——分为核心框架层（Message、Config、LLM客户端）、Agent实现层（BaseAgent及范式实现）和工具系统层
• 核心组件——Message统一消息格式、Config集中配置管理、HelloAgentsLLM智能客户端

从第四章的手写ReAct，到第五章的低代码平台，到第六章的专业框架，再到本章的自建框架——我们完成了一条完整的学习进阶路径。现在，你不仅知道如何使用Agent框架，更知道如何构建一个Agent框架。

本文参考：Datawhale《Hello-Agents》教程第七章《构建你的Agent框架》的内容框架与核心知识点。本文在忠实呈现该教程内容的基础上，为便于新手理解进行了通俗化改写和图表化呈现。