ai-agents-from-scratch：用本地模型亲手拆解 Agent，而不是套框架
Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.
秒懂
- 它是什么？
- 这个 JavaScript 教程仓库用 node-llama-cpp 和本地模型，从零实现函数调用、记忆和 ReAct 模式。它不追求性能，而是把黑盒打开给你看。适合想理解 Agent 本质、再决定是否用框架的工程师。
- 适合谁用？
- 适合想先理解 Agent 内部机制再接触生产框架的开发者，尤其是熟悉 Node.js 且愿意下载本地模型、忍受 8GB 以上内存占用的人。不适合需要快速交付可用 Agent 的团队，因为它不提供任何封装好的运行时，所有示例都是教学片段。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 54 天前。
- 用什么语言写的？
- 主要是 JavaScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
这个仓库解决什么问题
AI Agent 框架层出不穷，LangChain 之类的工具把函数调用、记忆和推理循环都封装成了高层 API。用起来方便，但出了问题很难排查，因为你不知道框架在背后做了什么。ai-agents-from-scratch 反其道而行，它不提供任何框架，而是用 node-llama-cpp 直接驱动本地 LLM，一步步演示 Agent 的每个组成部分。目标读者是那些想理解 Agent 本质的工程师，尤其是 JavaScript 生态里的人。仓库的哲学写得很直白：先深入理解，再明智地用框架。它不解决生产环境的性能问题，解决的是认知问题。
学习路径的编排逻辑
仓库把学习过程拆成十一个递进示例，每个示例对应一个独立目录，从 intro 到 error-handling。前六个示例不涉及 Agent 概念，只处理 LLM 的基础操作：加载模型、系统提示词、流式输出、批量处理。到第七个 simple-agent 才引入函数调用，README 里特意标注这是文本生成变成 Agent 的转折点。第九个 react-agent 实现 ReAct 模式，也就是推理、行动、观察的循环。第十个 aot-agent 更进一步，用原子化规划和 JSON 输出做多步计算。这种编排不是随便排列的，每个示例都建立在前一个的基础上，例如记忆功能是在函数调用之后才加入，因为持久化状态需要先有工具交互才有意义。
核心机制：从模型调用到 Agent 循环
仓库展示的 Agent 本质是 LLM 加工具加模式。在 simple-agent 示例中，函数调用的实现方式是定义 JSON Schema 描述工具参数，然后让模型决定是否调用以及传什么参数。模型不执行代码，它只输出结构化的调用意图，由你的 JavaScript 代码去实际执行。ReAct 示例则把这一过程循环化：模型先推理下一步做什么，调用工具，拿到观察结果，再推理，直到完成任务。AoT 示例换了一种策略，它让模型一次性生成完整的原子操作计划，用 JSON 表达操作之间的依赖关系，然后由代码确定性执行。这三种模式各自有不同的错误恢复能力，ReAct 可以在中途修正方向，AoT 则依赖计划本身的正确性。
运行方式与硬件门槛
运行这些示例需要 Node.js 18 以上版本，README 建议至少 8GB 内存，推荐 16GB。安装步骤只有一条命令：npm install。然后你需要按照 DOWNLOAD.md 的说明下载模型并放进 ./models/ 目录。运行示例也是直接的 node 命令，例如 node intro/intro.js、node simple-agent/simple-agent.js、node react-agent/react-agent.js。没有复杂的配置项，没有环境变量模板，模型路径硬编码在脚本里。这种简洁对教学有利，但也意味着要换模型得改代码。仓库还附带一个配套网站 agentsfromscratch.com，README 说网站是概念地图，仓库是实地地形，两者互补。
真正的局限：教学代码不是产品
这个仓库的局限很明显，它刻意不做任何工程化处理。没有错误重试机制，没有并发控制，没有模型抽象层。每个示例都是独立的脚本，你无法把它们组合成一个可复用的 Agent 库。error-handling 示例虽然引入了类型化错误分类和超时重试，但那本身也是教学内容，不是现成的健壮性方案。另一个限制是它完全依赖本地模型，这意味着推理速度受限于你的 GPU 或 CPU。README 提到一个可选的 OpenAI intro 示例，用于对比托管模型的成本与延迟，但主路径始终是本地推理。如果你的目标是构建一个能用的产品，这个仓库只能作为理解原理的起点，不能作为代码基础。
与 Python 版本的差异和替代选择
README 明确提到存在一个 Python 版本，地址是 github.com/pguso/agents-from-scratch。两个版本的教学结构相同，但底层绑定不同，JavaScript 版用 node-llama-cpp，Python 版大概率用 llama-cpp-python 之类的库。选择哪个版本取决于你的技术栈，而不是哪个更好。如果你想用更成熟的框架直接上手，可以去看 LangChain.js 或 Vercel AI SDK，它们把函数调用和 Agent 循环封装成了可配置的模块。区别在于，框架版你只需要声明工具列表和模型，循环逻辑由框架处理，而本仓库要求你手动写循环。框架适合验证想法，本仓库适合理解想法。一个务实的路径是先跑完本仓库的 react-agent 示例，再去看框架源码，你会突然明白那些抽象层在做什么。
维护状态与许可证
仓库的默认分支是 main，最后一次推送是 2026 年 7 月 24 日，没有被归档。README 显示项目仍在演进，例如新增了配套网站和错误处理示例。不过没有检索到任何 release 版本，这意味着没有稳定的版本号，也没有语义化版本控制。依赖 node-llama-cpp 的版本变动可能会破坏示例，你需要自行跟踪更新。许可证是 MIT，这意味着你可以自由使用、修改和分发代码，包括商用。但要注意，教程里的代码片段本身是教学工具，没有提供任何保证。如果你要把它的一部分用在生产项目里，应该把每个示例当作参考实现，而不是直接复制粘贴。
编辑结论
适合想先理解 Agent 内部机制再接触生产框架的开发者，尤其是熟悉 Node.js 且愿意下载本地模型、忍受 8GB 以上内存占用的人。不适合需要快速交付可用 Agent 的团队，因为它不提供任何封装好的运行时，所有示例都是教学片段。也不适合只想调 API 的业务开发者，OpenAI 部分只是可选的对照实验。采用前先确认你的机器能跑 node-llama-cpp 支持的量化模型，并通读 DOWNLOAD.md 中关于模型文件放置路径的说明。这个仓库的价值不在代码本身，而在 CODE.md 和 CONCEPT.md 里对每个设计决策的解释，跳过那些文件等于只拿到一堆没有上下文的脚本。
社区笔记