agents-from-scratch是一个教你"从零构建 AI Agent"的开源项目：它不使用任何框架、不依赖云 API，只用一个本地 LLM，通过 12 个递进课程，带你亲手把一个最简单的模型调用逐步"养大"成一个具备决策、工具调用、记忆和规划能力的 AI Agent。每一行逻辑都摊在阳光下，让 Agent 不再是黑盒。

为什么大多数教程让你越学越迷茫？

如果你用过 LangChain、CrewAI 这类框架，可能有这样的经历：

• 🤔 调用几行代码就能跑，但出错时完全无法调试——问题藏在框架抽象层里
• 🤔 Agent "看起来会思考"，实际发生了什么？没人说得清
• 🤔 换一个框架，所有知识几乎要清零

这个项目的哲学写得很直白（见 PHILOSOPHY.md）：

Agent 不是人格，而是循环、状态与约束（loops, state, and constraints）。如果某件事看起来像魔法，打开文件看看——这个仓库里没有隐藏逻辑。

它刻意避免四件事：框架抽象、拟人化语言、隐藏推理过程、过早的自主性。目标只有一个：机械式理解——让你能调试、能扩展、能推理 Agent 系统的每一步。

上图就是它的核心架构：用户输入进入 Agent 编排层（提示词构建、决策、循环控制、规划），然后分发到三大组件——LLM（推理）、Memory（状态与记忆）、Tools（执行），最后输出结果。整个仓库的所有代码，就是围绕这张图展开的。

快速开始：10分钟跑通第一个本地Agent

项目要求不高：Python 3.10+、8GB 内存、约 5–10GB 磁盘空间。

① 安装依赖

pip install llama-cpp-python

② 准备本地模型：下载一个 GGUF 模型（如 Meta-Llama-3-8B-Instruct-Q4_K_M.gguf，约 5GB），放入models/目录。

③ 检查环境并运行示例

python setup_check.py python complete_example.py

complete_example.py 内置了 12 个独立可运行的演示函数（lesson_01_basic_chat到lesson_12_telemetry），你可以逐课运行验证。详细的安装说明和常见问题（内存不足、响应慢等）都写在 QUICKSTART.md 里。

💡 本地模型的好处：无 API 费用、无速率限制、数据不出本机、可完全掌控——对学习而言，比云 API 更适合反复试验。

12课路线图：从"文本进文本出"到"可观测的Agent"

课程的精髓是：同一个 Agent 类（agent/agent.py）贯穿全部 12 课，每课只增加恰好一个新概念。不跳课、不推倒重来，这就像真实开发中一个系统逐步演进。

阶段一：基础（第 01–03 课）——让模型可靠地说话

第 3 课是关键转折：自由文本是概率性的、不可靠的，而结构化输出是契约——可以被验证、重试和信任。shared/utils.py 中的 JSON 提取工具配合最多 3 次重试，把概率性的 LLM 变成一个可靠的组件。

阶段二：Agency（第 04–06 课）——从聊天机器人到Agent

• 第 04 课 · 决策：让模型在有限的选项集合中选择（路由逻辑），而不是自由发挥
• 第 05 课 · 工具：模型不再自己回答数学题，而是"请求"调用 calculator 工具——能力边界由此打开（见 lessons/05_tools.md）
• 第 06 课 · Agent 循环：当它能observe → decide → act并循环、携带状态时，聊天机器人就变成了 Agent

状态（agent/state.py）不是藏在对话历史里的神秘上下文，而是一个可以直接检查、修改的 Python 对象——步数、是否完成、当前计划，一目了然。

阶段三：Intelligence（第 07–10 课）——给Agent装上记忆与计划

• 第 07 课 · 记忆：区分 Context（当前提示词里的）与 Memory（跨交互持久化的）。用户说"我叫 Alice"，这条事实会被存入 agent/memory.py，下次对话依然记得
• 第 08 课 · 规划：计划不是"想法"，而是数据结构——可检查、可修改、可安全执行
• 第 09 课 · 原子动作：把计划步骤拆成最小可验证、可回滚的动作单元
• 第 10 课 · AoT（Atom of Thought）：用依赖图编排原子节点，让复杂任务在保持可控的前提下扩展

阶段四：Observability（第 11–12 课）——像工程师一样保障质量

• 第 11 课 · Evals：改一个提示词可能导致 JSON 解析崩掉、工具调用变差——没有回归测试，质量是"悄悄腐烂"的。evals/golden_datasets.py 维护"黄金数据集"（必须永远通过的基准用例），配合 agent/evals.py 在每次改动后跑一遍
• 第 12 课 · Telemetry：结构化 JSON 日志记录每一次 LLM 调用、工具成功率和延迟，让线上调试不再是猜谜（agent/telemetry.py）

可靠性从哪里来？4条值得抄走的原则

这个项目反复强调的信念（见 README.md），其实是构建任何可靠 AI Agent 的通用法则：

1. 🏗️结构胜过花哨：一个普通提示词 + 好的结构，永远赢过一个聪明提示词 + 自由输出
2. 🔒约束带来可靠：Agent 的动作空间越受限，行为越可靠。看似限制，实则解放
3. 🔁验证 + 重试 = 确定性：LLM 是概率性的，但"输出契约 + 解析验证 + 重试"能把它变成可靠组件
4. 📊自主性最后才加：先会响应 → 再会决策 → 再会请求动作 → 最后才是安全执行

仓库结构速览

agents-from-scratch/ ├─ lessons/ # 12 步教程（01-12），按顺序阅读 ├─ agent/ │ ├─ agent.py # 核心：贯穿12课不断成长的Agent类 │ ├─ memory.py # 记忆系统 │ ├─ planner.py # 规划与原子动作 │ ├─ state.py # 状态管理 │ ├─ tools.py # 工具定义 │ ├─ evals.py # 评估框架（第11课） │ └─ telemetry.py # 遥测系统（第12课） ├─ shared/ # LLM封装、提示词、工具函数 ├─ evals/ # 黄金数据集 └─ complete_example.py # 12课全部可运行示例

其中 shared/llm.py 封装了本地模型加载（基于 llama-cpp-python），所有课程都只依赖这一个入口，没有任何隐藏 API 调用。

谁适合学？学完能获得什么？

适合你，如果：你能写代码但对 Agent 感到迷茫；听腻了"直接用 LangChain 吧"；想用本地模型；想要机械式理解而非玄学。

不适合你，如果：只想要最快的 demo、SaaS 模板，或者相信 Agent 真的在"思考"。

学完这 12 课，你应该能做到：一下午从零搭出简单 Agent ✅ 解释每个部件如何工作 ✅ 系统化调试 Agent 失败 ✅ 理性判断何时该用框架 ✅ 读懂框架源码而不发怵 ✅

框架会变成你的工具，而不是魔法黑盒。🚀