第 0 章 全局地图：Agent 究竟是什么
沿运费修复任务拆开策略、工具、环境与完成验收
定位：面向 Agent 方向实习准备。按「概念 → 原理图 → 最小实现 → 工程权衡 → 面试追问」学习。本文是独立整理的学习笔记；Hello-Agents [导读] 提供了很好的系统课程与代码，建议并行阅读原项目，不照搬其正文或配图。
阅读顺序：先能解释一个完整闭环，再做单 Agent 工具调用，最后加入检索、状态、评测。基础资料于 2026-09-24 查阅；第 0–10、12 章于 2026-09-26 按教学流程重构，第 11、13 章新增前沿工程与产品资料同日核对。引用以官方文档或论文为准，协议和框架接口更新时核对原始资料。
学习地图
引用阅读：全文的论文、文章、文档与源码链接都配有「主要内容、核心要点、阅读提示」导读。网页中点击引用旁的「导读」，可跳到本节摘要；引用导读 · 内容汇总 按主题汇总全部来源，并解释这些资料合起来讲了什么。
怎样学这份手册：每章先看学习目标，带着案例读机制，再运行或手算例子，最后完成练习并对照参考检查。两个贯穿案例是“修复运费函数”和“检索政策证据”，用于把不同章节接到同一条数据与执行链上。先预测结果再运行；若预测错误，回到具体状态或证据，找出自己漏掉的条件。离线实验无需 API Key，使用预置教学策略，模型能力实验则需另外接入真实模型。
| 阶段 | 章节 | 应能交付 |
|---|---|---|
| 基础 | 0–2 | 画出环境闭环，解释 LLM 与 Agent 的差别，手写工具循环 |
| 能力 | 3–6 | 规划、工具、RAG、记忆与上下文管理的小系统 |
| 系统 | 7–10 | 协作、MCP/A2A、可复现评测、安全与观测 |
| 前沿与求职 | 11–13 | Harness、Context、Skills、Agentic RL、项目与五家产品对比 |
0.1 从一道任务理解 Agent，而不是背定义
本章目标：读完后，你应能画出 Agent 的执行边界，区分模型生成、工具执行和任务验收，并判断一个需求是否值得使用 Agent。
假设用户说：“运费函数在金额等于 100 时计算错误，请修复，同时确认会员免运费、负数金额报错。”如果只调用一次模型，它可能给出一段看起来正确的代码。但你仍不知道它是否读过实际文件、补丁是否写入、测试是否通过。一个能完成这项任务的系统需要接触仓库，并根据执行反馈继续决策。
先把需求写成可以检查的规则：普通用户金额低于 100 收 10，金额达到 100 免运费；会员无论合法金额大小都免运费；负数金额抛出 ValueError。最后一条优先于会员条件，否则会员的负数订单也可能被错误接受。需求的优先关系必须在行动之前说清。
# 教学案例中的初始错误代码。
def shipping_fee(total, member=False):
if total > 100:
return 0
return 10
它有三个可复现的问题：100 的边界错了，会员条件缺失，负数校验缺失。后面各章会反复用这段代码解释规划、工具、上下文、协作和验收。示例运行于临时工作区，不改动你的真实业务代码。
0.2 闭环中的每个量到底是什么
经典表达是：Agent 收到观察 o_t，依据历史 h_t 和策略 π 选择动作 a_t；环境执行动作，产生新的状态和观察。这里的“策略”是从可用信息到动作选择的规则，可以由手写规则、搜索算法或模型实现，不一定是神经网络。
| 概念 | 在运费任务中的具体对象 | 不应混淆为 |
|---|---|---|
环境状态 s_t |
磁盘代码、依赖、测试、进程状态 | 模型对项目的描述 |
观察 o_t |
读取到的文件片段、测试输出 | 整个环境的真实状态 |
动作 a_t |
读文件、写补丁、运行测试 | 模型说“我会测试” |
历史 h_t |
已执行动作及其反馈 | 未执行的计划清单 |
策略 π |
根据失败信息选择下一步 | 工具本身 |
| 目标与验收 | 当前代码符合全部运费规则 | 最终回复措辞自信 |
模型通常只能看到环境的一部分。它读到一个文件，不代表知道仓库中的其他调用者；它看到一次测试成功，不代表知道测试是否覆盖需求。因此，观察应附带路径、版本或时间，避免把过去的证据当成当前事实。
0.3 沿一条实际轨迹看系统分工
用户目标 → 运行测试：边界/会员/负数失败
→ 读 pricing.py：发现 > 100，且没有其他条件
→ 写补丁：先拒绝负数，再检查会员或 >= 100
→ 运行测试：五项检查通过
→ 验收：通过证据对应当前文件版本
→ 返回结果与限制
这里有三个不同角色。模型或策略提出候选动作；运行时检查工具是否存在、参数是否合理、是否允许执行，然后记录结果；验收器判断环境最终状态是否符合需求。它们可以放在同一程序里，但职责必须分清。
如果策略提前说“全部完成”，运行时不应该因此伪造测试成功。第 2 章的实验会专门演示这种失败：最终回答收到拒绝，因为当前文件没有通过检查的证据。一次模型调用可以生成动作，也可以生成答案；行动能力来自模型与执行系统的结合。
0.4 单次调用、工作流和 Agent 怎么选
Building effective agents [导读] 用“下一步由预定义代码还是模型决定”区分 workflow 和 Agent。实际产品也常混合二者：外层代码控制权限和预算，某个节点内允许模型动态探索。
| 需求 | 更简单的起点 | 原因 |
|---|---|---|
| 从已给文本提取论文标题 | 单次结构化生成 | 输入齐全，无需与环境交互 |
| 每天读取固定报表并生成摘要 | 固定工作流 | 来源与步骤已知，异常可以定义 |
| 在陌生仓库定位并修复错误 | 受约束的 Agent 循环 | 下一步依赖搜索、代码和测试反馈 |
“用了工具”也不必然意味着模型控制了流程。代码固定执行搜索、读取和总结，仍可是一条带 LLM 节点的工作流。反过来，一个 Agent 的停止条件、写入范围和验收流程完全可以由确定性代码控制。
选择时问：是否需要外部状态？步骤能否预先穷举？异常是否足够少？是否有明确验收？如果固定代码已能可靠完成，增加模型决策可能只增加调用成本和行为波动。
0.5 第一次动手：比较“说完成”和“真的完成”
在仓库根目录运行以下两个命令。脚本使用标准库和确定性教学策略，不需要 API Key。
python3 agent/examples/repair_lab.py --scenario happy
python3 agent/examples/repair_lab.py --scenario false_final
也可以下载 repair_lab.py 后直接运行。先读输出的 status、reason 和 trace，暂时不用理解整个实现。正常路径包含五次决策：测试、读取、修改、测试、最终回答；提前结束路径只有一次决策，但状态是 rejected。
这个差异说明：生成一条完成声明很便宜，取得完成证据需要执行。 这里的修复答案预先写在策略中，实验验证的是运行时闭环，不是模型编程能力。第 2 章会拆开实现。
0.6 自测与参考解答
题目一：系统读取代码、让模型生成补丁，却没有应用补丁。算完成修复吗？
参考解答：没有。生成补丁只是候选产物，环境状态尚未变化；还需写入、运行验收并确认结果对应当前代码。
题目二：Agent 通过了五项测试，能否保证没有任何 bug？
参考解答：只能说明当前环境中这五项检查通过。还需说明需求覆盖范围与未测试输入；完整质量还可能涉及类型、并发、性能和集成行为。先让验收覆盖明确需求，再按项目风险扩展。
本章交付物：一张包含策略、运行时、环境和验收器的闭环图，以及两条运行结果的差异解释。能给每条箭头指出实际传递的数据，就比记住一句定义更进一步。