从零构建 AI Agent

这是一个面向本地优先的 AI Agent 入门指南。

本仓库通过从单个本地 LLM 调用开始，一步步构建一个完整的 Agent，带你了解 AI Agent 的底层工作原理。

没有框架。没有云端 API。没有隐藏的推理过程。没有魔法。

相关项目

从零构建 AI 产品 (AI Product from Scratch)

学习使用本地 LLM 开发 AI 产品的基础知识。通过 10 个综合课程和可视化图表，涵盖 Prompt Engineering、结构化输出、多步推理、API 设计和前端集成。

使用 JavaScript 从零构建 AI Agent

核心理念

Agent 并非拥有个性的主体，它们本质上是循环、状态和约束的集合。

如果某些操作看起来像“魔法”，请直接打开文件查看源码——本仓库中没有任何隐藏的逻辑。

你将学到什么

本仓库通过 12 节课程，构建一个持续进化的 Agent：

课程	新增功能	链接
01	文本输入 / 文本输出	lessons/01_basic_llm_chat.md
02	角色与行为（System Prompts）	lessons/02_system_prompt.md
03	结构化输出（JSON 合约）	lessons/03_structured_output.md
04	决策（路由逻辑）	lessons/04_decision_making.md
05	工具（外部能力）	lessons/05_tools.md
06	Agent 循环（观察 → 决策 → 执行）	lessons/06_agent_loop.md
07	记忆（短期与长期）	lessons/07_memory.md
08	规划（作为数据而非思想）	lessons/08_planning.md
09	原子化操作（安全执行）	lessons/09_atomic_actions.md
10	AoT - 思维原子（依赖图）	lessons/10_atom_of_thought.md
11	评估（回归测试）	lessons/11_evals.md
12	遥测（运行时可观测性）	lessons/12_telemetry.md

目标受众

适合人群：

• 会写代码但对 Agent 构建感到迷茫的开发者
• 厌倦了“直接用 LangChain 就好”的人
• 希望使用本地模型进行学习的人
• 想要理解底层运行机制的工程师
• 寻找清晰思维模型的教育者

不适合人群：

• 寻找最快演示方案的人
• 想要 SaaS 启动套件的人
• 认为 Agent 会“思考”的人
• 想要隐藏思维链（Chain-of-thought）逻辑的人

快速开始

详细设置说明，请参考 QUICKSTART.md

简而言之：

1. 安装依赖：pip install -r requirements.txt
2. 下载一个 GGUF 模型到 models/ 文件夹
3. 运行：python complete_example.py

注意： complete_example.py 文件包含了演示所有 12 节课程的可执行代码。你可以将其作为参考，查看这些概念是如何整合在一起的。

仓库结构

ai-agents-from-scratch/
├─ README.md              # 本文档
├─ philosophy.md          # 仓库存在的原因
├─ QUICKSTART.md          # 详细设置指南
├─ complete_example.py    # 所有 12 节课程的演示
├─ requirements.txt       # Python 依赖
│
├─ models/                # 在此存放 GGUF 模型
├─ shared/                # 可重用的工具（LLM、Prompts、工具函数）
├─ agent/                 # 进化的 Agent 实现
│  ├─ agent.py            # 主 Agent 类
│  ├─ memory.py           # 记忆系统
│  ├─ planner.py          # 规划与原子化操作
│  ├─ state.py            # Agent 状态管理
│  ├─ tools.py            # 工具定义
│  ├─ evals.py            # 评估框架（第 11 课）
│  └─ telemetry.py        # 遥测系统（第 12 课）
├─ evals/                 # 测试用的黄金数据集
│  └─ golden_datasets.py  # 已知的测试用例
└─ lessons/               # 逐步解释文档（01-12）

关键文件说明

agent/agent.py - 本仓库的核心

• 包含在 12 节课中不断进化的 Agent 类。
• 每节课都会为同一个类添加新的方法和功能。
• 这是你学习和修改的主要对象。

complete_example.py - 学习参考

• 包含 12 个独立的函数，每个函数对应一节课程。
• 每个函数都在独立的环境下演示了该课程的概念。