为什么不用LangChain？agents-from-scratch 第一性原理哲学深度解析-平芜编程栈

【免费下载链接】agents-from-scratch

Build AI agents from first principles using a local LLM - no frameworks, no cloud APIs, no hidden reasoning.

项目地址：https://gitcode.com/gh_mirrors/age/agents-from-scratch

如果你正在学习AI Agent（智能体），大概率听过一句话：“直接上 LangChain 就行了”。但 agents-from-scratch 这个项目偏偏反其道而行之：不用任何框架、不依赖云端 API、没有隐藏的推理过程，仅凭一个本地 LLM，从第一性原理出发，一步步教你造出一个真正“看得见内部”的 AI Agent。这篇深度解析将带你看懂：为什么它敢对 LangChain 说不，以及这种哲学为什么更适合想真正搞懂 AI Agent 内部机制的新手。

一、先问一个问题：框架到底藏起了什么？

大多数教程教你怎么用Agent，而这个仓库教你理解 Agent如何工作。

LangChain、CrewAI、AutoGen 这些框架确实强大，但 PHILOSOPHY.md 开篇就点出了核心矛盾：

"Frameworks hide the mechanisms that make agents work. By the time you understand what they abstract, you no longer need them." （框架隐藏了让 Agent 运转的机制。等你搞懂了它抽象的东西，你就不再需要它了。）

用表格来对比两种路线，一目了然：

维度	框架路线（如 LangChain）	agents-from-scratch 路线
上手速度	快，几行代码跑起来 demo	慢一点，但每个环节都能解释
可调试性	出错时常需翻框架源码	每一步决策、状态转换都可见
学习成本	先学框架概念，再学 Agent 概念	直接学 Agent 的机制本身
依赖	云端 API、API Key	本地模型，无 API 费用、无速率限制

关键不是"框架不好"，而是：在理解机制之前使用抽象，学到的只是"会用"，而不是"懂了"。

二、第一性原理哲学：它明确拒绝的 4 件事

打开 PHILOSOPHY.md，作者把哲学浓缩成了"我们避免什么"。这 4 条拒绝，恰恰是对新手最有价值的部分：

🚫 拒绝框架抽象—— 先理解机制，再决定是否需要框架
🚫 拒绝拟人化语言—— Agent 不"思考"、不"理解"，它只是处理文本、遵循模式、做结构化决策
🚫 拒绝隐藏推理—— 每个决策显式、每个状态转换可见、每个 prompt 可读，"幕后没有任何事发生"
🚫 拒绝过早自主—— 自主性是最后加的东西，不是第一件

这条"渐进自主"路径值得新手特别注意：

模型先会响应→ 再会决策→ 再会请求动作→ 最后由系统安全地执行。

这正对应仓库 12 课的教学顺序（见 README.md 中的课程表）：第 1 课只是最普通的"文本进、文本出"，第 6 课才出现循环，第 9 课才引入安全的原子化执行。复杂度是一层一层加上去的，而不是开头就给你一坨"魔法"。

三、Agent 不是性格，是一个循环

这是整个仓库最反直觉、也最核心的观点：

"Agents are not personalities. They are loops, state, and constraints."（Agent 不是性格。它是循环、状态和约束。）

很多人把 Agent 想象成一个"会思考的小助手"。但在这个仓库里，Agent 就是下面这个朴素的循环（来自 PHILOSOPHY.md）：

while not done: observation = perceive(环境) decision = decide(观察, 状态) state = act(决策, 状态)

它不是人格，不是意识，就是一个循环。这个循环的完整形态如下图所示——从用户目标出发，构建上下文、LLM 推理、决定下一个动作、执行动作，直到达成目标或到达最大步数才结束：

理解了这一点，你就不会再问"Agent 在想什么"，而是问"这一轮它的状态是什么、它决定做什么、为什么终止"。这正是从"神秘感"走向"机械式理解"的关键一步。

四、三个让可靠性落地的工程原则

"没有魔法"不是一句口号，它落在三个具体的工程做法上（详见 PHILOSOPHY.md 的 "What We Focus On" 一节）：

显式状态（Explicit State）状态不藏在对话历史里，而是一个可以检查、修改、推理的普通 Python 对象——agent/state.py 里的AgentState从第 9 行起就直白地维护着steps（步数）和done（是否完成）等字段。
结构化输出（Structured Outputs）自由文本是概率性的、不可靠的；结构化输出是契约，可以被校验、重试、信任。LLM 每次只允许返回 JSON，解析失败就重试——这就是"把概率组件变成可靠组件"的手法。
数据驱动的计划（Planning as Data）计划不是"想法"，而是数据结构。计划变成数据后，就可检查、可修改、可安全执行。

把这三点拼在一起，就是仓库中那个"持续进化"的 Agent 的完整架构——它只有一个大脑（Agent 编排层）和三类组件（LLM 负责推理、Memory 负责状态、Tools 负责执行），没有任何隐藏模块：

而 Memory 组件的工作方式同样直白：每轮先加载记忆构建上下文，推理后再评估"这条信息值得存吗"，值得就存，不值得就遗忘（forget），不存在任何黑盒向量库：

五、为什么选本地模型？

PHILOSOPHY.md 给出的答案非常朴素：

零 API 成本—— 放心大胆地做实验
无速率限制—— 快速迭代
完全控制—— 看到实际发生的一切
隐私—— 数据不出本机
学习—— 理解完整技术栈

一句话总结："云端 API 适合生产环境，本地模型适合学习。" 配合 QUICKSTART.md 的指引，你只需要安装依赖、下载一个 GGUF 模型到models/目录，运行python complete_example.py就能看到 12 课所有概念的完整演示。

六、那到底什么时候才该用 LangChain？

这个问题仓库自己也回答了，而且是正向的回答（见 PHILOSOPHY.md 的 "When to Use Frameworks"）：

学完这个仓库之后，你会知道框架抽象了什么、什么时候这种抽象有帮助、什么时候有害、以及如何调试它们。那时，框架会成为工具，而不是魔法盒子。

换句话说：不是"不用 LangChain"，而是先不用。当你能在一下午从零搭出一个 Agent、能解释每个部件的工作原理、能系统性地调试失败时，你再回头看框架源码，那些"魔法"都会现出原形——那不过是循环、状态和约束。

七、结语：Confident, Mechanical Understanding

这个仓库的目标只有五个：

一下午从零构建一个简单 Agent
能解释它每个部分如何工作
能系统性地调试 Agent 失败
能评估"该不该用框架"
能读懂框架源码并理解它

它的最后两句话，也是整本哲学的注脚：

"Not hype. Not magic. Just systems." （不是炒作，不是魔法，只是系统。）

如果你受够了"just use LangChain"，想真正搞懂 AI Agent 到底怎么运转，这份课程清单就是起点：从 01_basic_llm_chat.md 到 12_telemetry.md，一课只加一个新概念，代码始终写在同一个 agent/agent.py 里，像真实开发一样逐步生长。打开任何一个文件，你都会发现——这里没有隐藏逻辑，只有可以被读透的系统。