从零构建 AI 智能体
用本地 LLM 和 node-llama-cpp 从零构建 AI 智能体，深入理解工具调用、记忆与 ReAct 模式。
- Star 数
- ★ 4.9k
- 最近更新
- 2 个月前
- License
- MIT
- 主语言
- JavaScript
- FA 评分
- 28/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用
- 费用
- 免费，无需付费服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 希望在应用中使用本地 LLM 生成文本，但需要理解底层机制的 Node.js 开发者。
- 不适合
- 需要开箱即用生产级 Agent 框架的团队
- 硬件不足 8GB 内存或不愿手动下载 GGUF 模型的用户
- 希望用云端 API 免本地配置直接上手的人
这个 Agent 能做什么，适合哪些场景？
该仓库是一个循序渐进的学习资源，指导开发者如何使用本地 LLM（通过 node-llama-cpp）从第一性原理构建 AI 智能体，避免使用框架。它包含 15 个示例，从基础 LLM 交互开始，逐步涵盖系统提示词、推理、批处理、流式输出、函数调用、持久记忆、ReAct、AoT、错误处理、ToT、GoT、CoT 以及基于嵌入的工具路由。每个示例都附带完整的代码（.js）以及独立的文档（CODE.md 和 CONCEPT.md），用于解释实现细节和高级概念。该项目强调本地推理，需要用户下载 GGUF 模型，并提供了 companion website 作为概念地图。最终目标是让学习者深刻理解智能体的内部工作原理，以便日后明智地使用生产级框架。
该仓库运行一系列 Node.js 脚本，使用 node-llama-cpp 加载本地 GGUF 模型并执行推理。示例包括 intro/intro.js（基础提示）、simple-agent/simple-agent.js（函数调用）、react-agent/react-agent.js（ReAct 模式）、tree-of-thought/tree-of-thought.js（束搜索）等。每个脚本读取本地模型、接收输入、调用 LLM，并可选地使用工具函数（例如 simple-agent 中的函数定义）。它提供了一个 PromptDebugger 工具（helper/prompt-debugger.js）用于检查发送给模型的确切提示。用户通过命令行直接运行脚本，并根据每个示例文件夹中的 CODE.md 和 CONCEPT.md 文件调整参数。
- 希望在应用中使用本地 LLM 生成文本，但需要理解底层机制的 Node.js 开发者。
- 正在学习函数调用，并希望看到一个在本地 LLM 上实现工具定义的完整示例的开发者。
- 希望深入学习 ReAct 模式以及推理、行动、观察循环的 AI 工程师。
- 希望为 LLM 应用添加持久记忆功能，并了解状态管理方式的开发者。
- 需要实现工具路由以减少上下文长度，并观察嵌入相似度如何选择相关工具的工程师。
- 在构建生产级智能体框架之前，希望通过动手示例快速了解智能体架构的学生或爱好者。
如何安装或部署这个 Agent？
首先，确保已安装 Node.js 18 或更高版本以及 npm。然后，克隆仓库并进入目录，运行 npm install 安装依赖。接着，在仓库根目录创建 models/ 文件夹，并从 Hugging Face 等来源下载所需的 GGUF 格式模型，将模型文件放入该文件夹。具体模型下载链接和推荐型号请参考 DOWNLOAD.md 文件。
如何使用这个 Agent？
安装完成后，在仓库根目录运行 npm install。然后按照 README 中的说明运行示例，例如：node intro/intro.js 或 node react-agent/react-agent.js。确保已下载模型并放置在 ./models/ 目录中。每个示例文件夹都包含 CODE.md（逐步代码解释）和 CONCEPT.md（概念讲解），建议同时阅读以获得完整理解。
这个 Agent 有哪些优点和局限？
- 所有代码均使用本地 LLM，通过 node-llama-cpp 实现，无外部 API 依赖，保护隐私且无网络延迟。
- 每个示例都提供 CODE.md 和 CONCEPT.md，详细解释代码和概念，适合教育目的。
- 涵盖多种高级智能体模式，包括 ReAct、Tree of Thought、Graph of Thought 和 Chain of Thought，提供广泛的架构视角。
- 包含 PromptDebugger 工具，帮助开发者调试发送给 LLM 的准确提示，提升可观测性。
- 提供 companion website，从概念上补充仓库，帮助理解学习路径。
- 使用 node-llama-cpp 和本地 GGUF 模型，开发者需要熟悉本地模型配置和硬件要求（至少 8GB RAM）。
- 示例是独立的脚本，未提供部署到生产环境的集成指南或规范化 API。
- 该项目主要针对教程学习，不适合直接作为生产级智能体框架，需要额外工程化工作。
- 模型下载过程未自动化，用户需手动下载 GGUF 文件，增加部署步骤。
- 核心依赖于 node-llama-cpp，迁移到其他推理引擎需额外适配。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| 从零构建 AI 智能体 当前 | 28 · 缺口较多 | 命令行工具免费 | ★ 4.9k | 2 个月前 | JavaScript | — |
| KodeAgent | 43 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 43 | 15 天前 | Python | OpenAI API · Claude API |
| Vibe Vibe —— 人人都能学会的 AI 编程指南 | 22 · 缺口较多 | 网页应用免费 | ★ 6.2k | 5 个月前 | Dockerfile | — |
| hax | 62 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 924 | 1 天前 | C | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：仓库未提供任何权限管理、用户确认、数据流透明、敏感数据处理、依赖安全、外部影响、回滚或来源归属的机制或说明。所有信任相关标准均未得到支持，因此得分为0。
证据显示：README中列出的示例路径与项目结构部分存在不一致（如README中'01_intro'与项目结构中的'01_intro'，但README中链接为'examples/01_intro/intro.js'，而项目结构显示为'01_intro/intro.js'），存在轻微不一致。依赖项在package.json中列出，但未提供版本锁定或完整性校验。错误处理示例（11_error-handling）提及了错误分类和重试，但未提供具体实现细节。因此，自我一致性、依赖可用性和失败消息均得分为1。
证据显示：README明确面向希望理解AI代理内部原理的开发者，并提供了从基础到高级的渐进式学习路径，覆盖多种场景。能力边界在README中有所提及（如'Limitations of pure LLM reasoning'），但未详细说明。触发精度方面，示例的触发方式（如命令行运行）在README中有说明，但未提供详细的参数或配置。环境适配方面，README提到了Node.js 18+和内存要求，但未提供详细的系统兼容性说明。因此，受众与场景得分为2，其余为1。
证据显示：README提供了清晰的项目结构、安装说明和示例，但缺少FAQ、已知限制的详细说明、版本变更日志和明确的维护责任。LICENSE.md为MIT，但版权年份和作者为占位符。因此，信息架构、示例和FAQ得分为2，安装说明、命名稳定性、已知限制、许可证和维护责任得分为1，版本变更日志为0。
证据显示：示例代码的输出格式未详细说明，但README提供了运行示例的命令。边际价值较高，因为该仓库提供了从零构建AI代理的独特学习资源。成本效益方面，本地LLM运行需要较高的硬件要求，但未提供详细的成本分析。因此，输出可用性得分为1，边际价值为2，成本效益为1。
证据显示：README中的声明（如'This is where text generation becomes agency!'）未提供可验证的证据。仓库未提供测试或基准数据来支持其教学效果。事实与推断的分离不明确，例如README中关于'ReAct pattern'的描述是事实性陈述，但未提供来源。因此，声明可追溯性得分为1，跨来源佐证为0，事实与推断分离为1。
- 源码中未见：最小权限约束只授予完成任务所需的权限：用专用账号或只读令牌，并限定可访问的目录和仓库。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：数据流向说明运行时观察它连接了哪些外部服务（代理或防火墙日志）；弄清数据去向之前不要输入敏感数据。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 源码中未见：依赖安全审查安装前固定版本并做一次依赖扫描（如 npm audit、pip-audit）；优先放在容器里运行。
- 源码中未见：外部影响披露先弄清它会写入、发送或修改哪些外部系统，用测试账号或测试仓库验证后再接入正式环境。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 源码中未见：来源归属可核验从官方仓库或包源安装，核对发布者和仓库地址，避免同名仿冒包。
- 仓库未提供任何安全机制或权限管理，使用时需自行评估风险。
- README中的示例路径与项目结构存在不一致，可能导致用户混淆。
- LICENSE.md中的版权信息为占位符，需确认实际授权。
- 依赖项未锁定版本，存在供应链风险。