用 Datawhale Hello-Agents 从零构建智能体：环境配置、三大范式与自研框架实操

Hello-Agents 有两种打开方式。只想系统地读，直接开在线文档站即可，无需安装任何东西，全部 16 章在浏览器里就能看，国内还有加速镜像。想动手写代码（强烈建议，这个项目的价值有一半在代码里），就克隆仓库到本地：仓库里的 docs 目录是教程原文，code 目录是每一章配套的示例代码，Extra-Chapter 与 Co-creation-projects 是社区贡献的扩展章节与共创案例。别急着通读，正确姿势是「读一章、跑一章」，遇到报错去 Issue 区翻，社区很活跃。

# 路线一：在线阅读（零安装）
# https://datawhalechina.github.io/hello-agents/

# 路线二：本地跑代码
git clone https://github.com/datawhalechina/hello-agents.git
cd hello-agents

# 建独立虚拟环境，避免污染全局依赖
python -m venv .venv
source .venv/bin/activate          # Windows 用 .venv\Scripts\activate
pip install -r requirements.txt    # 或用官方包：pip install hello-agents

密钥这一步值得多说两句。框架用项目根目录的 .env 文件管理凭证，HelloAgentsLLM 会依据你填了哪些环境变量自动判断该走哪家供应商，所以你不必在代码里硬编码模型地址。常见的三个变量是 LLM_API_KEY、LLM_BASE_URL 与 LLM_MODEL_ID：只填 KEY 时走 OpenAI 官方；把 BASE_URL 指向 DeepSeek、通义千问或本地 Ollama，再配 MODEL_ID，就完成了换模型。.env 一定要进 .gitignore，千万不要提交到公开仓库。

# 复制模板再改，别直接改 .env.example
cp .env.example .env

# .env 示例（三选一思路）
# A. OpenAI 官方
LLM_API_KEY=sk-你的密钥
LLM_MODEL_ID=gpt-4o-mini

# B. 国内供应商（改 BASE_URL 即可换）
LLM_API_KEY=你的密钥
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL_ID=deepseek-chat

# C. 本地模型（先把 Ollama 跑起来）
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL_ID=qwen2.5:7b

框架把智能体拆成四件事：感知（用户消息、工具输出、记忆）、规划（任务分解与步骤编排）、行动（调工具、调接口）、记忆（短期对话与长期存储）。SimpleAgent 就是这四件事的最小实现——它不带工具、不带复杂循环，只负责「把系统提示词和你这句话交给模型，拿回回答」。先让它跑起来，是为了确认密钥、网络与依赖链路都通了；跑通之后再加工具与循环，出问题时就能快速定位是新加的部分出错，还是底座就没配好。

# 官方 README 的导入路径（不同版本可能略有差异，以本地安装为准）
from hello_agents.agent import SimpleAgent
from hello_agents.llm import HelloAgentsLLM

llm = HelloAgentsLLM()                 # 自动读取 .env 里的配置

agent = SimpleAgent(
    llm=llm,
    system_prompt="你是一名严谨的技术文档助手，回答要给出依据，不确定就明说。",
)

print(agent.run("用三句话解释什么是智能体。"))

这一段跑通之后，建议立刻做一件小事：把 system_prompt 换成两种风格（比如「简洁的运维工程师」与「啰嗦的大学老师」），用同一个问题各问一次。你会直观感受到「人设与约束」对输出的影响有多大，而这恰恰是后面所有范式里最容易被忽视、却最影响效果的一层。官方在学习建议里也反复强调：强烈建议亲自运行、调试甚至修改项目里的每一段代码，只看不动手等于没学。

第 4 章是整套教程的分水岭：它不让你调任何现成框架，而是要求你自己把三个范式写出来。ReAct 的核心是一个 Thought（想）→ Action（做）→ Observation（看）的循环，模型每一步先说想法，再决定调哪个工具，拿到结果后拼回上下文继续下一轮，直到给出最终答案；它适合步骤不多、边查边定的任务。Plan-and-Solve 反过来，先一次性把任务拆成计划，再逐步执行、最后整合，适合路径较长、需要先看清全局的任务。Reflection 则多一道自我检查：先生成，再让模型自己按标准挑毛病，然后改一版。

# 一个极简 ReAct 循环的骨架（对照第 4 章补齐细节）
for step in range(MAX_STEPS):
    thought = llm.invoke(prompt_of(messages))     # 1) 想：本步要做什么
    action  = parse_action(thought)               # 2) 解析出工具名与参数
    if action is None:
        return thought                            #    没动作 = 已得出结论
    observation = tool_registry.run(action)       # 3) 做：真正执行
    messages.append({"role": "system",            # 4) 看：结果回写上下文
                     "content": f"Observation: {observation}"})
return "达到步数上限仍未完成，请缩小任务范围"

写这一遍的价值在于，你会亲手撞上三件事：上下文怎么越滚越长、工具解析失败时怎么兜底、以及「步数上限」到底该设多少。这三件事在任何框架里都存在，只是被封装起来了；先在被封装的地方吃过亏，后面用 LangGraph、AutoGen 之类的框架时，你才知道每个参数在保护你免受什么伤害。第 6 章会带你用这些框架重做一遍同样的任务，那时对比会非常强烈。

没有工具的智能体只会说话。框架用 ToolRegistry 统一管理工具，你只要继承 BaseTool，写清楚 name、description 与 run 方法，再 register 进去，模型就能按描述自行决定是否调用。这里最关键也最容易被低估的是 description：模型是照着这段自然语言来决定要不要用、传什么参数的，写得含糊（比如「处理数据」）会导致它要么不用、要么乱传参数；写得具体（比如「读取 CSV 文件，返回行列数与前 5 行预览」）命中率会明显上升。

from hello_agents.tool import ToolRegistry, BaseTool

class DataReadTool(BaseTool):
    name = "data_read_tool"
    description = "读取 CSV 数据文件，返回数据形状与前 5 行预览"

    def run(self, file_path: str) -> str:
        import pandas as pd
        try:
            df = pd.read_csv(file_path)
        except Exception as exc:
            return f"读取失败：{exc}"          # 失败要返回可读文本，别抛异常
        return f"形状 {df.shape}\n{df.head().to_string()}"

registry = ToolRegistry()
registry.register_tool(DataReadTool())
print(registry.list_tools())                  # 确认注册成功再往下走

工具写法的两条经验值得照抄。一是 run 的返回值要「给模型看」而不是「给程序看」：抛异常会让整轮循环崩掉，而返回一句「读取失败：文件不存在，请检查路径」能让模型自己纠错、换个路径重试，这是工具调用健壮性的分水岭。二是工具要小而专：一个工具只做一件事，比一个工具接受十几个参数更好调用；需要组合能力时，让模型连着调两次，而不是塞进一个巨型工具里。

第 8、9 两章处理的是长任务里最现实的问题：上下文是有限的，而工具输出与历史对话会把它迅速塞满。做法是把记忆分成两层——短期记忆就是当前这轮对话的消息列表，靠裁剪与摘要控制在窗口内；长期记忆则放进外部存储（向量库或键值库），需要时按相关性检索回来。第 8 章会带你搭一个可用的记忆与检索系统，并演示 RAG 的接入方式；第 9 章的上下文工程则更进一步，讲怎么在持续交互中保持「上下文理解」，包括该保留什么、该压缩什么、该在什么时候重新注入系统约束。

# 思路示意：短期记忆裁剪 + 长期记忆按需回填
short_term = keep_last_n(messages, n=8)          # 只留最近若干轮
summary    = llm.invoke(SUMMARY_PROMPT + older)  # 更早的压成一段摘要
long_term  = memory.search(current_query, k=3)   # 长期记忆按相关度取回

messages = [system_msg, summary_msg] + long_term + short_term

把这一层做对，收益非常直接：同一批任务在长会话下的表现会稳定得多，而且 token 开销可控。反过来，跳过这一步直接往 messages 里无限追加，你会看到典型的「越聊越笨」——模型开始遗忘开头定下的约束、重复已经做过的步骤。这也是为什么教程把记忆与上下文工程放在框架之后、协议之前：它是从「能跑」到「能稳定跑」之间那道坎。

第 12 章是很多人会跳过、但真正拉开差距的一章。它给出两套互补的评估手段：LLM Judge 让一个模型当评委，按正确性、清晰度、完整性等维度对输出打分，适合衡量主观质量；Win Rate 则把智能体的输出与参考答案成对比较，统计「优于参考答案」的比例，适合量化对比两个版本的好坏。两者都要先准备一个小而稳的测试集——几十条你真正在意的任务就够，比临时想三条强得多。跑评估的正确节奏是：改一处，跑一轮，看分数变了没有；一次改三处，你永远不知道是哪处在起作用。

# 评估循环的最小骨架（评分维度与提示词见第 12 章）
cases = load_cases("eval/cases.jsonl")     # 每条：{"input": ..., "reference": ...}
scores = []
for case in cases:
    output = agent.run(case["input"])
    scores.append({
        "judge":  judge_llm.score(case["input"], output),        # 主观质量分
        "win":    judge_llm.compare(output, case["reference"]),  # 对比胜/平/负
        "steps":  output.step_count,                             # 平均步数
        "tokens": output.token_usage,                            # 成本
    })
report(scores)   # 看均值、看分布，重点看低分样本长什么样

把评估跑起来之后，你的智能体开发才算闭环：改提示词、换模型、调工具，都有了可比较的依据。教程后半部分的综合案例（智能旅行助手、自动化深度研究智能体、赛博小镇）也都建议照着这条路线做——先定任务集，再实现，最后评估。至于第 11 章的 Agentic RL（从 SFT 到 GRPO 训练自己的模型），则需要 GPU 资源，新手可以先跳过，等前面的链路都熟了再回来啃。