pguso/ai-agents-from-scratch

Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.

这个项目是什么？

pguso/ai-agents-from-scratch 是一个动手实践的教程仓库，教你从头开始构建AI代理——不使用任何流行的代理框架。相反，它使用运行在你自己计算机上的本地语言模型（LLM），通过一个名为node-llama-cpp的库实现。

核心理念是“通过构建来学习”：你从原始的LLM调用开始，逐步添加能力（工具、记忆、推理模式），直到你重现了现代代理框架所做的事情——这样你就理解了为什么这些框架会做出这样的设计选择。

你将学到什么？

README说你会理解：

LLM在基础层面是如何工作的
代理到底是什么（LLM + 工具 + 模式）
不同的代理架构是如何运作的
为什么框架会做出某些设计选择

核心定义

README给出了一个AI代理的简单公式：

AI代理 = LLM + 系统提示 + 工具 + 记忆 + 推理模式

LLM = “大脑”（语言模型）
系统提示 = “身份”（塑造行为的指令）
工具 = “手”（模型可以调用的函数）
记忆 = “状态”（持久信息）
推理模式 = “策略”（它如何逐步思考）

学习路径（15个示例，按顺序）

每个示例都建立在前一个示例的基础上。README将它们列为：

介绍 — 加载并运行本地LLM；基本的提示/响应循环。
OpenAI介绍 （可选） — 调用托管LLM，如GPT-4；了解温度、令牌使用、成本与控制、数据隐私。
翻译 — 使用系统提示来专业化代理的行为并控制输出格式。
思考 — 配置LLM进行逻辑推理；了解纯LLM推理的局限性以及何时使用外部工具。
批处理 — 并行处理多个请求以提高性能。
编码 — 实时逐令牌流式传输响应；管理令牌预算。
简单代理 — 重要的一步：函数调用。给LLM提供它可以决定使用的工具。README称这是“文本生成变成代理的地方”。
带记忆的简单代理 — 跨会话持久化事实和偏好；长期记忆管理。
ReAct代理 — 推理 → 行动 → 观察循环：迭代式问题解决与自我纠正。README称这是“现代代理框架的基础”。
AoT代理（思维原子） — 将任务分解为具有依赖关系的原子规划步骤，输出为结构化JSON，确定性执行。
错误处理 — 使LLM + 工具系统具有弹性：类型化错误、超时、带退避的重试、优雅降级。
思维树 — 生成多个候选下一步行动，对分支进行排名和剪枝（束搜索），验证获胜路径。
思维图 — 将推理建模为DAG（有向无环图）：并行源提取 → 合并规则 → 最终草稿。在生成前解决冲突。
思维链 — 将高风险决策拆分为明确的、可审计的推理阶段（例如，在应用策略之前仅提取事实）。
工具路由（嵌入） — 为工具描述预计算嵌入，按相似度对用户消息进行评分，并仅将top-k工具传递给模型以节省上下文。

示例的结构

每个示例文件夹包含三个文件：

<name>.js — 工作代码
CODE.md — 逐步代码解释（逐行分解）
CONCEPT.md — 高级概念、架构模式、实际应用、简单图表

README建议阅读这两个文件以获得完整理解。

运行要求

Node.js 18+
至少8GB RAM（推荐16GB）
下载模型并将其放置在./models/文件夹中（详情见DOWNLOAD.md）

使用npm install安装，然后运行示例，例如：

node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

配套网站

有一个配套网站，位于https://agentsfromscratch.com。它不是仓库的替代品——它是一个概念性伴侣，解释为什么每个示例存在并可视化学习路径。推荐的工作流程：使用GitHub运行和研究代码，使用网站获取心智模型和解释。README这样说：“把网站想象成地图，把这个仓库想象成地形。”

辅助工具

有一个PromptDebugger（helper/prompt-debugger.js），它显示LLM确切看到的内容——系统提示、函数定义、对话历史、上下文状态——对调试很有用。

引用的其他资源

node-llama-cpp — 用于本地推理的库
Hugging Face — GGUF模型的模型中心
GGUF格式 — 用于本地推理的量化模型

许可证和贡献

README声明它是一个教育资源——“根据需要用于学习”。欢迎贡献：文档改进、新的示例模式、错误修复，或分享你构建的内容。

作者

该仓库由pguso（Patric Gutersohn）创建，他提供AI工作流、上下文工程、RAG以及本地/生产LLM项目的自由职业/合同工作（联系方式：pguso@gmx.de）。

底线： 如果你想在使用框架之前真正理解AI代理的内部运作，这个仓库会带你一步一步地在自己的机器上构建它们，一次一个能力。