ai-agents-from-scratch

手写AI Agent，彻底搞懂原理，告别黑盒。

这是一个通过从零手写AI Agent来揭示其内部原理的开源教程项目。它不依赖任何现成的Agent框架，而是用JavaScript和本地大模型，一步步实现函数调用、记忆管理和ReAct模式等核心机制。项目旨在消除AI Agent的“黑盒”感，让开发者通过亲手构建，真正理解Agent的工作流程和设计思想。它提供了清晰的代码示例和逐步讲解，适合希望深入底层、掌握Agent原理的开发者学习。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 4799

维护状态维护中

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队pguso

所属国家

官网地址

GitHubhttps://github.com/pguso/ai-agents-from-scratch

定价模式free

价格说明开源项目，MIT许可证，完全免费，可自行部署使用。

访问状态

是否开源是

开源协议MIT

主要语言JavaScript

技术栈/模型ai-agents,educational,function-calling,llm,llm-agent,node-llama-cpp,react-agent,tutorial

GitHub 星标★ 4799

30天Star增速

HF 下载量

上线时间2025-10-23 00:00:00

最近更新2026-09-22 00:00:00

维护状态维护中

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数4

使用教程

难度：进阶约 15 分钟部署方式：本地安装 5 步

环境要求

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

项目介绍

ai-agents-from-scratch 是智能体领域的开源项目，由 pguso 开发，2025 年首次发布。

在全站 13,014 个收录项目中，它的 GitHub 星标数（4,799）位列前 9%，在智能体分类的 2,499 个项目里位列前 10%。

近 41 天，它的 GitHub 星标从 4,518 增加到 4,799，净增 281。

项目仍在小幅维护中，最近一次代码更新于 2026-09-22。MIT许可证，完全免费，可自行部署使用。

它主要面向的使用场景是：学习AIAgent核心原理，作为进阶教程。同类可对比的替代方案包括 LangChain、AutoGPT、BabyAGI。

上一篇：zep

下一篇：ha-mcp