ai-agents-from-scratch
ai-agents-from-scratch 是一个致力于揭开 AI 智能体神秘面纱的开源项目。它主张通过从零构建来学习，让开发者在本地环境中使用 LLM 亲手搭建智能体，而非直接套用复杂的现成框架。这有效解决了许多人在使用 AI 技术时面临的“黑盒”困境——即不清楚函数调用、记忆机制及 ReAct 模式背后的真实逻辑。
它特别适合希望夯实基础的开发者、AI 研究者以及关注本地化部署的技术人员。借助 Node.js 和 node-llama-cpp，用户可以直观地看到模型加载、上下文管理及推理流程的每一个细节。其独特亮点在于“由建而学”的理念，不仅提供代码示例，还配有详细的原理解析和可视化图表。项目后续甚至计划用原生代码复现 LangChain 等框架的核心概念，帮助用户真正理解框架的设计哲学，从而更明智地使用现有工具。如果你想摆脱对封装层的依赖，深入掌握 AI 技术的本质，这里是非常好的起点。
使用场景
某金融科技公司内部数据团队计划构建一个私有化部署的智能分析助手，用于处理敏感的财务日志查询与报告生成。
没有 ai-agents-from-scratch 时
- 过度依赖成熟框架的黑盒封装，当 Agent 出现逻辑死循环时无法定位底层原因。
- 主流方案多强制调用云端 API，导致敏感财务数据面临泄露风险，不符合合规要求。
- 对 Function Calling 和记忆机制理解模糊，难以根据业务需求定制工具响应格式。
- 调试过程缺乏可视化支持，排查 ReAct 推理路径中的错误耗时极长。
使用 ai-agents-from-scratch 后
- 基于本地 LLM 构建流程，所有数据处理均在本地完成，彻底消除数据外泄隐患。
- 亲手实现 ReAct 模式核心逻辑，能精准控制工具调用时机，显著提升任务成功率。
- 深入理解内存管理机制，灵活设计上下文窗口，有效解决长对话中的信息遗忘问题。
- 结合源码逐步调试，直观看到 Token 消耗与决策过程，大幅缩短故障排查时间。
通过从零构建，开发者不仅能掌握 Agent 核心原理，更能打造安全、透明且高度可定制的本地智能应用。
运行环境要求
- 未说明
未说明
至少 8GB (推荐 16GB)
快速开始
阅读完整的交互式版本：
本仓库是 AI Agents From Scratch（从零开始构建 AI 智能体）的一部分——这是一个动手学习系列，我们逐步构建 AI 智能体，解释每一个设计决策，并可视化底层发生了什么。👉 https://agentsfromscratch.com
如果你更喜欢长篇解释、图表和概念深入探讨，请从那里开始——然后回到这里探索代码。
从零开始构建 AI 智能体 (AI Agents From Scratch)
无需框架即可在本地构建 AI 智能体。在使用生产级框架之前，先理解其底层机制。
目标
本仓库教你使用 本地大语言模型 (LLMs) 和 node-llama-cpp 基于第一性原理构建 AI 智能体。通过完成这些示例，你将理解：
- LLM 的基本工作原理
- 智能体的本质（LLM + 工具 + 模式）
- 不同智能体架构的运作方式
- 框架为何做出某些设计选择
理念：通过构建来学习。深入理解，然后明智地使用框架。
相关项目
从零开始构建 AI 产品
使用本地 LLM 学习 AI 产品开发基础。涵盖提示工程、结构化输出、多步推理、API 设计和前端集成，通过 10 个带有视觉图表的综合课程进行讲解。
Python 版从零开始构建 AI 智能体
下一阶段：从零开始构建 LangChain 与 LangGraph 概念
掌握基础后，本项目的下一阶段将带你使用原生 JavaScript 和本地模型重新实现 LangChain 和 LangGraph 的核心部分。 这不是为了构建新框架，而是为了理解框架是如何工作的。
第一阶段：智能体基础 - 从 LLM 到 ReAct
前置要求
- Node.js 18+
- 至少 8GB 内存（推荐 16GB）
- 下载模型并放入
./models/文件夹，详情见 DOWNLOAD.md
安装
npm install
运行示例
node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js
学习路径
按顺序跟随这些示例以逐步建立理解：
1. 入门 - 基础 LLM 交互
你将学到：
- 加载和运行本地 LLM
- 基本的提示/响应循环
关键概念：模型加载、上下文、推理流水线、Token 生成
2. (可选) OpenAI 入门 - 使用专有模型
openai-intro/ | 代码 | 代码解释 | 概念
你将学到：
- 如何调用托管 LLM（如 GPT-4）
- 温度控制
- Token 使用情况
关键概念：推理端点、网络延迟、成本与控制、数据隐私、供应商依赖
3. 翻译 - 系统提示与专业化
你将学到：
- 使用系统提示对智能体进行专业化
- 输出格式控制
- 基于角色的行为
- 针对不同模型的聊天封装器
关键概念：系统提示、智能体专业化、行为约束、提示工程
4. 思考 - 推理与问题解决
你将学到：
- 配置 LLM 进行逻辑推理
- 复杂定量问题
- 纯 LLM 推理的局限性
- 何时使用外部工具
关键概念：推理智能体、问题分解、认知任务、推理局限性
5. 批处理 - 并行处理
你将学到：
- 并发处理多个请求
- 用于并行的上下文序列
- GPU 批处理
- 性能优化
关键概念：并行执行、序列、批量大小、吞吐量优化
6. 编码 - 流式传输与响应控制
你将学到：
- 实时流式响应
- Token 限制与预算管理
- 渐进式输出显示
- 用户体验优化
关键概念：流式传输、逐 Token 生成、响应控制、实时反馈
7. 简单智能体 - 函数调用（工具）
simple-agent/ | 代码 | 代码解释 | 概念
你将学到：
- 函数调用/工具使用基础
- 定义 LLM 可使用的工具
- 参数的 JSON Schema
- LLM 如何决定何时使用工具
关键概念：函数调用、工具定义、智能体决策、行动执行
这就是文本生成转变为智能性的地方！
8. 带记忆的简单智能体 - 持久化状态
simple-agent-with-memory/ | 代码 | 代码解释 | 概念
你将学到：
- 跨会话持久化信息
- 长期记忆管理
- 事实与偏好存储
- 记忆检索策略
关键概念：持久化记忆、状态管理、记忆系统、上下文增强
9. ReAct 智能体 - 推理 + 行动
你将学到：
- ReAct 模式（推理 → 行动 → 观察）
- 迭代问题解决
- 逐步工具使用
- 自我修正循环
关键概念：ReAct 模式、迭代推理、观察 - 行动循环、多步智能体
这是现代智能体框架的基础！
10. AoT Agent - 思维原子规划
你将学到：
- 思维原子方法论
- 多步计算的原子化规划
- 操作间的依赖管理
- 用于推理计划的 JSON 结构化输出
- 计划的确定性执行
关键概念: AoT 规划，原子操作，依赖解析，计划验证，结构化推理
文档结构
每个示例文件夹包含：
<name>.js- 可运行的代码示例CODE.md- 逐步代码解释- 逐行分解
- 各部分功能说明
- 工作原理
CONCEPT.md- 高层概念- 对智能体为何重要
- 架构模式
- 实际应用
- 简单图表
核心概念
什么是 AI 智能体？
AI Agent = LLM + System Prompt + Tools + Memory + Reasoning Pattern
─┬─ ──────┬────── ──┬── ──┬─── ────────┬────────
│ │ │ │ │
Brain Identity Hands State Strategy
能力演进
1. intro → Basic LLM usage
2. translation → Specialized behavior (system prompts)
3. think → Reasoning ability
4. batch → Parallel processing
5. coding → Streaming & control
6. simple-agent → Tool use (function calling)
7. memory-agent → Persistent state
8. react-agent → Strategic reasoning + tool use
架构模式
简单智能体 (步骤 1-5)
User → LLM → Response
工具使用智能体 (步骤 6)
User → LLM ⟷ Tools → Response
记忆智能体 (步骤 7)
User → LLM ⟷ Tools → Response
↕
Memory
ReAct 智能体 (步骤 8)
User → LLM → Think → Act → Observe
↑ ↓ ↓ ↓
└──────┴──────┴──────┘
Iterate until solved
🛠️ 辅助工具
PromptDebugger
helper/prompt-debugger.js
用于调试发送给 LLM (大型语言模型) 的提示词的工具。显示模型确切看到的内容，包括：
- 系统提示词 (System prompts)
- 函数定义 (Function definitions)
- 对话历史 (Conversation history)
- 上下文状态 (Context state)
在 simple-agent/simple-agent.js 中的使用示例
📂 项目结构 - 基础篇
ai-agents/
├── README.md ← You are here
├─ examples/
├── 01_intro/
│ ├── intro.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 02_openai-intro/
│ ├── openai-intro.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 03_translation/
│ ├── translation.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 04_think/
│ ├── think.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 05_batch/
│ ├── batch.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 06_coding/
│ ├── coding.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 07_simple-agent/
│ ├── simple-agent.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 08_simple-agent-with-memory/
│ ├── simple-agent-with-memory.js
│ ├── memory-manager.js
│ ├── CODE.md
│ └── CONCEPT.md
├── 09_react-agent/
│ ├── react-agent.js
│ ├── CODE.md
│ └── CONCEPT.md
├── helper/
│ └── prompt-debugger.js
├── models/ ← Place your GGUF models here
└── logs/ ← Debug outputs
第二阶段：构建生产级框架 (教程)
掌握上述基础后，第二阶段将带你从入门示例过渡到生产级框架设计。你将重新构建 LangChain 和 LangGraph 的核心概念，以理解真实框架的内部运作机制。
你将构建什么
一个轻量但完整的智能体框架，包含：
- 可运行接口 (Runnable Interface)，驱动一切的可组合模式
- 消息系统 (Message System)，类型化的对话结构 (人类、AI、系统、工具)
- 链 (Chains)，将多个操作组合成流水线
- 记忆 (Memory)，跨对话的持久状态
- 工具 (Tools)，函数调用与外部集成
- 智能体 (Agents)，决策循环 (ReAct, 工具调用)
- 图 (Graphs)，复杂工作流的状态机 (LangGraph 概念)
学习方法
以教程为先导：带有练习的分步课程
以实现为导向：亲手构建每个组件
与框架兼容：学习 LangChain.js 中使用的模式
结构概览
tutorial/
├── 01-foundation/ # 1. Core Abstractions
│ ├── 01-runnable/
│ │ ├── lesson.md # Why Runnable matters
│ │ ├── exercises/ # Hands-on practice
│ │ └── solutions/ # Reference implementations
│ ├── 02-messages/ # Structuring conversations
│ ├── 03-llm-wrapper/ # Wrapping node-llama-cpp
│ └── 04-context/ # Configuration & callbacks
│
├── 02-composition/ # 2. Building Chains
│ ├── 01-prompts/ # Template system
│ ├── 02-parsers/ # Structured outputs
│ ├── 03-llm-chain/ # Your first chain
│ ├── 04-piping/ # Composition patterns
│ └── 05-memory/ # Conversation state
│
├── 03-agency/ # 3. Tools & Agents
│ ├── 01-tools/ # Function definitions
│ ├── 02-tool-executor/ # Safe execution
│ ├── 03-simple-agent/ # Basic agent loop
│ ├── 04-react-agent/ # Reasoning + Acting
│ └── 05-structured-agent/ # JSON mode
│
└── 04-graphs/ # 4. State Machines
├── 01-state-basics/ # Nodes & edges
├── 02-channels/ # State management
├── 03-conditional-edges/ # Dynamic routing
├── 04-executor/ # Running workflows
├── 05-checkpointing/ # Persistence
└── 06-agent-graph/ # Agents as graphs
src/
├── core/ # Runnable, Messages, Context
├── llm/ # LlamaCppLLM wrapper
├── prompts/ # Template system
├── chains/ # LLMChain, SequentialChain
├── tools/ # BaseTool, built-in tools
├── agents/ # AgentExecutor, ReActAgent
├── memory/ # BufferMemory, WindowMemory
└── graph/ # StateGraph, CompiledGraph
为什么这很重要
理解胜过使用：当你了解框架内部如何工作时，你可以：
- 更快地调试问题
- 自信地定制行为
- 明智地做出架构决策
- 构建你自己的扩展
- 流畅地阅读框架源代码
学一次，处处用：你将学到的模式 (Runnable, 组合，状态机) 适用于：
- LangChain.js - 你将理解它们的抽象
- LangGraph.js - 你将掌握状态管理
- 任何智能体框架 - 相同的核心理念
- 你自己的项目 - 构建自定义解决方案
开始第二阶段
完成基础部分 (intro → react-agent) 后，开始教程：
# 从基础开始
cd tutorial/01-foundation/01-runnable
lesson.md # 阅读课程
node exercises/01-*.js # 完成练习
node solutions/01-*-solution.js # 检查你的工作
每节课包括：
- **概念解释**，为什么这很重要
- **代码演示**，如何构建它
- **练习**，实践实现
- **解决方案**，参考代码
- **现实世界示例**，实际用法
**时间投入**：约 8 周，每周 3-5 小时
### 你将获得什么
结束时，你将拥有：
1. 从零构建一个可用的 Agent（智能体）框架
2. 理解 LangChain/LangGraph 的内部工作原理
3. 掌握组合模式
4. 创建可复用组件（Tools、Chains、Agents）
5. 为复杂工作流实现状态机
6. 获得使用或扩展任何框架的信心
**接下来**：在生产环境中使用 LangChain.js，确切了解其底层运作。
---
## 关键要点
### 第一阶段（基础）结束后，你将理解：
1. **LLM（大型语言模型）是无状态的**：上下文必须显式管理
2. **系统提示塑造行为**：同一模型，不同角色
3. **函数调用赋予能动性**：工具将文本生成器转变为智能体
4. **记忆至关重要**：智能体需要在跨会话中记住信息
5. **推理模式很重要**：对于复杂任务，ReAct > 简单提示
6. **性能很重要**：并行处理、流式传输、Token 限制
7. **调试至关重要**：确切查看模型接收到的内容
### 第二阶段（框架教程）结束后，你将掌握：
1. **Runnable 模式（可运行接口）**：为什么框架中的所有内容都使用一个接口
2. **组合优于配置**：用简单部分构建复杂系统
3. **消息驱动架构**：框架如何组织对话
4. **链抽象**：无缝连接提示词、LLM 和解析器
5. **工具编排**：带超时和错误处理的执行
6. **智能体执行循环**：决策型智能体的机制
7. **状态机**：用图管理复杂工作流
8. **生产环境模式**：错误处理、重试、流式传输和调试
### 框架为你提供：
既然你已经理解了基础，像 LangChain、CrewAI 或 AutoGPT 这样的框架提供：
- 预构建的推理模式和智能体模板
- 丰富的工具库和集成
- 生产就绪的错误处理和重试
- 多智能体编排
- 可观测性和监控
- 社区扩展和插件
**你会更好地使用它们，因为你了解其底层运作。**
## 额外资源
- **node-llama-cpp**: [GitHub](https://github.com/withcatai/node-llama-cpp)
- **模型中心**: [Hugging Face](https://huggingface.co/models?library=gguf)
- **GGUF 格式**：用于本地推理的量化模型
## 贡献
这是一个学习资源。欢迎：
- 建议改进文档
- 添加更多示例模式
- 修复 Bug 或不清晰的解释
- 分享你构建的内容！
## 许可
教育资源 - 根据需要自由使用和修改以进行学习。
---
**用心 ❤️ 打造，献给想要真正理解 AI 智能体的人**
从 `intro/` 开始并逐步进行。每个示例都建立在之前的示例之上。阅读 `CODE.md` 和 `CONCEPT.md` 以获得完整理解。
快乐学习！
常见问题
相似工具推荐
stable-diffusion-webui
stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。 无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。
everything-claude-code
everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。 通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。 这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上
ComfyUI
ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。 这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。 无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。
NextChat
NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。 这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。 NextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。
ML-For-Beginners
ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。 无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。
ragflow
RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。 在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。 这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。