ai-agents-from-scratch
手写AI Agent，彻底搞懂原理，告别黑盒。
项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整
数据来源：GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 4906
使用教程
环境要求
- Node.js 18 或更高版本
- 内存至少 8GB，建议 16GB
- 本地运行大模型所需的环境（项目基于 node-llama-cpp）
- 能访问终端并执行 node / npm 命令
安装与启动步骤
-
1获取项目代码
把教程仓库克隆到本地，README 未列出具体克隆命令，此处使用项目给出的 GitHub 地址。
git clone https://github.com/pguso/ai-agents-from-scratch.git cd ai-agents-from-scratch -
2安装依赖
在项目根目录执行 npm install，安装 README 安装章节列出的依赖（含 node-llama-cpp）。
npm install -
3运行入门示例
先跑最基础的 intro 示例，观察原始 LLM 调用过程，理解最底层的一次问答。
node intro/intro.js -
4运行简单 Agent
在理解裸调用后，运行 simple-agent，看 Agent 如何在 LLM 之外加上工具与流程。
node simple-agent/simple-agent.js -
5运行 ReAct Agent
最后运行 react-agent，观察 ReAct 模式如何组合推理与行动，形成完整 Agent 循环。
node react-agent/react-agent.js
如何确认成功
依次执行三条 node 命令均能在终端正常输出模型推理结果、无报错，即表示环境与示例运行成功。
常见问题
Q：需要安装 Python 吗？
A：不需要。这是 JavaScript 版教程，只需 Node.js 18+；README 提到另有一个独立的 Python 版仓库，需另行访问。
Q：必须用框架吗？
A：不需要。项目定位就是不用任何现成 Agent 框架，只依赖 node-llama-cpp 在本地跑大模型，从零手写 Agent。
Q：三个示例应该按什么顺序跑？
A：按 README 顺序：intro.js → simple-agent.js → react-agent.js，由裸 LLM 调用逐步过渡到 ReAct 架构。
Q：跑不动或内存不足怎么办？
A：README 要求至少 8GB 内存、推荐 16GB，本地大模型对内存敏感，建议先关闭占内存程序或换用更小的本地模型。
注意事项
- README 明确强调“Learn by building”，建议先跑代码再去看框架实现。
- 配套网站 https://agentsfromscratch.com 用于理解概念与学习路径，不替代本仓库代码。
- README 的 Prerequisites 中“Do”一行疑似被截断，实际额外前置条件请以仓库原文为准。
- 示例依赖本地大模型文件，首次运行可能需要额外下载模型权重，请留意终端提示与网络/磁盘占用。
核心亮点
- 从零实现，不依赖框架，能深入理解Agent底层机制
- 使用本地LLM，无API成本，便于实践和调试
- 覆盖函数调用、记忆、ReAct等关键模式，内容系统
不足之处
- 教程性质，非生产级框架，功能覆盖有限
- 文档/社区待观察
适用场景
- 学习AI Agent核心原理，作为进阶教程
- 为特定场景定制轻量级Agent，避免框架臃肿
- 教学演示，向团队或学生解释Agent工作方式
替代项目
LangChain、AutoGPT、BabyAGI
同类项目推荐
brigade
开源
让智能体用真实退出码和代码图谱自证工作，防止虚假交付。
Brigade Stack: run coding agents anywhere and keep one record of the work. Shared ta···
BambooAI
开源
用大白话问数据，LLM 在持久 Python 内核里自动跑代码出结果
AI-powered data analysis workbench built for transparency, reproducibility and user ···
Claude-Patent-Creator
开源
用AI自动写美国专利，检索+合规+附图一步到位
USPTO patent creation system with MCP server + Claude Code plugin. Hybrid RAG search···
pinchy
开源
自托管企业级 AI 智能体，离线可用，权限审计全掌控
Self-hosted AI agent platform built on OpenClaw. Enterprise-ready, offline-capable, ···
olcli
开源
终端里管理 Overleaf 项目，Git 同步 + AI 智能体接入
Overleaf CLI - pull, push, sync, compile LaTeX projects from your terminal. Git remo···
watch-skill
开源
把视频变成可搜索证据，让 AI 智能体自查自纠
Give AI agents eyes, ears, and verifiable results. Watch Skill turns video, audio an···
DocSentinel
开源
让 AI 智能体自动审阅安全文档，快速找出合规风险与修复方案
MCP server for AI agent for cybersecurity: automate assessment of documents, questio···
Flowise
开源
像搭积木一样拖出 AI 助手，不用写一行代码
Build AI Agents, Visually
metronix-memory
开源
给 AI 智能体装个不会忘事的本地记忆库
Self-hosted AI agent memory — MCP memory server with durable recall for agents