手把手带你从零搭一个 AI Agent｜本地运行，不花一分钱

今天推荐一个 GitHub 上的宝藏项目——AI Agents from Scratch，用本地大模型从第一性原理构建 AI Agent。不需要 API Key，不需要花钱，不需要 GPU，8GB 内存的笔记本就能跑。

为什么推荐这个项目？

市面上大部分 Agent 教程都是"调 API + 套框架"，你跟着跑通了，但不知道底层在干嘛。这个项目不一样：

• 从零开始：不用 LangChain、不用 AutoGen，纯手写
• 本地运行：用 node-llama-cpp 加载 GGUF 模型，完全离线
• 10 个递进式 Lesson：从"调用一次 LLM"到"写出完整 ReAct Agent"
• 每个 Lesson 都有原理文档（CONCEPT.md）+ 代码实现（CODE.md）

学完之后你再去用 LangChain / LangGraph，会发现"原来框架就是帮我封装了这些东西"。

环境准备（5 分钟）

1. 安装 Node.js

确保 Node.js 版本 ≥ 18：

node -v   # 需要 v18+

2. 克隆项目并安装依赖

git clone https://github.com/pguso/ai-agents-from-scratch.git
cd ai-agents-from-scratch
npm install

3. 下载模型

项目使用 GGUF 格式的本地模型。推荐 Qwen2.5-7B-Instruct（约 4.7GB），8GB 内存就能跑：

mkdir models
# 从 Hugging Face 下载（需要梯子）或国内镜像
# 把 .gguf 文件放到 models/ 目录下

国内用户可以去 hf-mirror.com 搜索 "Qwen2.5-7B-Instruct-GGUF" 下载 Q4_K_M 量化版本。

学习路线：4 个关键 Lesson

项目有 10 个 Lesson，但核心是下面 4 个。跟着做完，你就理解了 Agent 的本质。

Lesson 1：Hello LLM（examples/01_intro）

目标：加载本地模型，发送第一条消息。

这一步的意义是让你理解：Agent 的底层就是在跟一个 LLM 对话，所有的"智能"都建立在这个基础上。

跑起来之后你会看到模型的回复一个字一个字地流式输出，这就是最原始的 LLM 交互。

Lesson 2：Function Calling（examples/07_simple-agent）

目标：让 LLM 学会调用外部工具——这是 Agent 的核心能力。

核心概念：普通的 LLM 只能生成文字。但如果你告诉它"你有这些工具可以用"，它就能判断什么时候该用工具、用哪个工具、传什么参数。

代码关键部分——定义一个工具：

const multiply = defineChatSessionFunction({
  name: "multiply",
  description: "Multiplies two numbers",
  parameters: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    }
  },
  callback: async (a, b) => {
    const result = a * b;
    return result.toString();
  }
});

就这么简单——给工具一个名字、一段描述、定义参数类型、写好执行逻辑。LLM 会根据 description 自动判断什么时候该调用它。

这就是所有 Agent 框架的底层原理。LangChain 的 Tool、OpenAI 的 Function Calling、Claude 的 Tool Use，本质上都是在做这件事。

Lesson 3：ReAct Agent（examples/09_react-agent）⭐ 最重要

目标：搭一个完整的 ReAct Agent——当前最主流的 Agent 架构。

ReAct = Reasoning + Acting，Agent 的工作循环是：

思考（Thought）→ 行动（Action）→ 观察（Observation）→ 思考 → 行动 → ... → 最终答案

系统提示词——告诉 LLM 按这个模式工作：

const systemPrompt = `你是一个数学助手，使用 ReAct 方法。
你必须严格按照以下模式：

Thought: [分析需要什么计算]
Action: [调用一个工具]
Observation: [等待结果]
Thought: [分析结果，决定下一步]
...
Thought: [已获得所有信息]
Answer: [最终答案，停止]`;

核心循环——Agent 的"大脑"：

async function reactAgent(userPrompt, maxIterations = 10) {
    let iteration = 0;
    
    while (iteration < maxIterations) {
        iteration++;
        
        const response = await session.prompt(
            iteration === 1 ? userPrompt : "Continue your reasoning.",
            { functions, maxTokens: 300 }
        );
        
        // 检测到 "Answer:" 就停止循环
        if (response.toLowerCase().includes("answer:")) {
            return response;
        }
    }
}

实际运行效果（问它"一家店周一卖15件、周二卖20件、周三卖10件，每件8元，求日均销量和总收入"）：

--- Iteration 1 ---
Thought: 我需要先算每天的收入
Action: multiply(15, 8)
Observation: 120

--- Iteration 2 ---
Thought: 周一收入120，现在算周二
Action: multiply(20, 8)
Observation: 160

--- Iteration 3 ---
Thought: 周二160，算周三
Action: multiply(10, 8)
Observation: 80

--- Iteration 4 ---
Thought: 三天收入 120+160+80，求总和
Action: add(120, 160)  →  280
Action: add(280, 80)   →  360

--- Iteration 5 ---
Thought: 总收入360，日均销量 = (15+20+10)/3
Action: add(15, 20) → 35
Action: add(35, 10) → 45
Action: divide(45, 3) → 15

Answer: 日均销量15件，总收入$360

关键理解：Agent 不是一次性给出答案，而是一步步推理、一步步调用工具、一步步验证。这就是为什么它能解决复杂问题——把大问题拆成小步骤。

Lesson 4：Memory Agent（examples/08_simple-agent-with-memory）

目标：给 Agent 加上记忆，让它记住之前的对话。

没有 Memory 的 Agent 每次对话都是"失忆"的。加上 Memory 后，它能记住你之前说过什么、做过什么，实现连续对话。

这就是 ChatGPT 能记住上下文的原理——把历史对话存起来，每次请求都带上。

学完之后能做什么？

理解了 Function Calling + ReAct + Memory 这三个核心概念后，你可以：

1. 看懂任何 Agent 框架的源码——LangChain、AutoGen、CrewAI 都是在这三个概念上做封装
2. 写进简历——"从零实现了基于 ReAct 架构的 AI Agent，支持工具调用和持久化记忆"
3. 扩展成自己的项目——把计算器工具换成天气 API、数据库查询、网页搜索，就是一个实用的 Agent

扩展方向（面试加分项）

总结：Agent 的本质就三件事——调用工具（Function Calling）、循环推理（ReAct）、记住上下文（Memory）。这个项目用最少的代码把这三件事讲透了。

项目地址：github.com/pguso/ai-agents-from-scratch

clone 下来，今晚就能跑起来。 ![alt]