从零构建 AI Agent
用本地 LLM 从第一性原理逐步搭建同一个 Agent，无框架、无云 API、无隐藏逻辑。
- Star 数
- ★ 1.1k
- 最近更新
- 2 个月前
- License
- MIT
- 主语言
- Python
- FA 评分
- 32/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台
- 费用
- 免费，无需付费服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 想理解 Agent 循环、状态与工具调用机制，而不愿直接上手 LangChain 的后端开发者
- 不适合
- 想要开箱即用 Demo 或 SaaS 模板的团队
- 不希望手动下载 GGUF 模型到本地 models/ 目录的用户
- 需要生产级最佳实践与托管部署方案的项目
这个 Agent 能做什么，适合哪些场景？
agents-from-scratch 是一个本地优先的教学型仓库，通过 12 节课把同一个 Agent 从单次本地 LLM 调用逐步演化成具备记忆、规划、评估与遥测能力的完整实现。核心代码集中在 agent/agent.py 的 Agent 类，按课程逐层叠加能力；shared/ 存放 LLM 调用与提示词等复用工具，agent/ 下还有 memory.py、planner.py、state.py、tools.py、evals.py 和 telemetry.py 等模块。执行依赖本地 GGUF 模型，通过 Python 直接运行，不接入 OpenAI 或任何云 API，也不需要 API Key。仓库提供 complete_example.py 作为 12 节课各自独立的可执行示例，evals/golden_datasets.py 存放用于回归测试的黄金数据集。它的定位是教学与心智模型建立，而非生产框架。
仓库沿 12 节课顺序构建单一 Agent：01 文本进/文本出；02 通过 system prompt 设定角色；03 用 JSON 契约约束结构化输出；04 加入路由式决策逻辑；05 接入 tools.py 中的工具；06 形成 observe → decide → act 的 Agent 循环；07 引入短期与长期记忆（memory.py）；08 将规划作为数据而非思考过程（planner.py）；09 原子动作的安全执行；10 Atom of Thought 依赖图；11 用 evals.py 与 evals/golden_datasets.py 做回归评估；12 用 telemetry.py 输出结构化日志、延迟与追踪。运行 python complete_example.py 可分别看到每节课的独立演示，LLM 调用通过 shared/ 的工具层发送给本地 GGUF 模型。输出是文本、结构化 JSON、工具调用结果以及评估与遥测数据。
- 想理解 Agent 循环、状态与工具调用机制，而不愿直接上手 LangChain 的后端开发者
- 需要在完全离线或内网环境中演示 Agent 原理的教学者与培训团队
- 希望用本地 GGUF 模型做提示词与结构化输出实验的工程师
- 打算为已有 Python 项目补充评估（evals）和遥测（telemetry）思路的学习者
- 把 12 节课当作教材、按阶段讲解 Agent 架构的课程设计者
如何安装或部署这个 Agent？
按 README 的 Quick Start 执行三步：安装依赖、下载 GGUF 模型到 models/ 目录、运行示例。
pip install -r requirements.txt随后把一个 GGUF 格式模型文件放入仓库的 models/ 目录（README 未指定具体模型名称与下载来源，这是需要自行补齐的信息）。详细步骤见仓库中的 QUICKSTART.md。
如何使用这个 Agent？
首次运行可直接执行完整示例，它会分别演示 12 节课的概念。
python complete_example.py若要研读逐步演化的实现，从 agent/agent.py 的 Agent 类入手，配合 lessons/01_basic_llm_chat.md 至 lessons/12_telemetry.md 顺序阅读，README 明确建议不要跳课。评估部分使用 agent/evals.py 与 evals/golden_datasets.py 中的黄金数据集对照已知良好结果。
这个 Agent 有哪些优点和局限？
- 同一份 agent/agent.py 跨 12 节课持续演化，能看清每项能力是如何叠加出来的
- 完全本地运行，不需要 OpenAI 或云 API、无需 API Key，也避开限流
- 用 JSON 契约与显式约束代替提示词技巧，README 明确主张可靠来自结构而非措辞
- 配套 evals/golden_datasets.py 与 telemetry.py，覆盖回归测试与运行时可观测性
- MIT 许可，并附 complete_example.py 提供每节课的独立可执行样例
- 定位为教学而非生产，README 自述不提供最佳实践
- 需要自行准备 GGUF 模型文件，README 未给出具体模型与下载地址
- 非标准打包，只能通过克隆仓库并运行 Python 脚本来使用
- 不支持也不提供云端或托管模型路径，换用远程 API 需要自己改写 shared/ 层
- 仅提供 Python 版本（JavaScript 版本位于另一仓库）
这个 Agent 与同类方案有什么区别？
README 直接点名“just use LangChain”并明确排除使用框架，因此实际对比对象是 LangChain 一类 Agent 框架：本项目不抽象模型与工具、不提供生产级封装，只用本地 LLM 与显式 Python 代码展示循环、状态与约束。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| 从零构建 AI Agent 当前 | 32 · 缺口较多 | 命令行工具免费 | ★ 1.1k | 2 个月前 | Python | — |
| 从零构建 AI 智能体 | 28 · 缺口较多 | 命令行工具免费 | ★ 4.9k | 2 个月前 | JavaScript | — |
| GenAI Agents 综合教程库 | 25 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 25k | 2 天前 | Jupyter Notebook | OpenAI API |
| Late | 50 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 446 | 1 天前 | Go | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据仅显示本地优先、无云 API、无 API key 的声明，以及 requirements.txt 中单一依赖 llama-cpp-python；未见权限模型、工具执行确认、敏感数据处理或回滚机制的具体代码。least_privilege 与 external_effects 仅凭声明给 1；user_confirmation、sensitive_data_handling、rollback 无任何证据，记 0；dependency_security 仅有一个未固定版本的依赖，记 1；source_attribution 有 MIT 与致谢段落但无具体来源引用，记 1。
README 声称 12 课逐步构建同一 agent，结构描述自洽，但未提供代码文件内容佐证，self_consistency 记 1；依赖 llama-cpp-python 未固定版本，可用性依赖本地编译与 GGUF 模型下载，dependency_availability 记 1；未见任何错误处理或失败信息设计，failure_messages 记 0。
README 明确列出适用与不适用人群、课程学习路径与能力边界（非框架、非生产），audience_and_scenarios 与 capability_boundaries 各记 2；但触发/调用方式仅靠 python complete_example.py，trigger_precision 记 1；环境适配仅提及本地 GGUF 与 pip，未覆盖平台差异，environment_fit 记 1。
README 有清晰目录结构与关键文件说明，information_architecture 记 2；安装说明指向 QUICKSTART.md 但该文件未在证据中，install_notes 记 1；命名稳定性仅见描述，naming_stability 记 1；示例仅提及 complete_example.py 而无 FAQ，examples_and_faq 记 1；known_limitations 有“教育非生产”声明但无具体限制清单，记 1；LICENSE 完整 MIT，license 记 2；无版本号或 changelog，versioning_changelog 记 0；维护责任仅见贡献指南，无维护者承诺，maintenance_responsibility 记 1。
输出可用性依赖未展示的代码，output_usability 记 1；作为教学项目有边际价值但无对比证据，marginal_value 记 1；成本收益仅凭本地运行声明，无量化，cost_benefit 记 1。
README 的课程表与文件结构可追溯，但关键文件（agent/*.py、QUICKSTART.md）未在证据中，claim_traceability 记 1；跨源佐证仅有 README 与 LICENSE/requirements 的有限一致，cross_source_corroboration 记 1；事实与推断分离尚可（明确区分“是什么/不是什么”），fact_inference_separation 记 1。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 证据仅含 README、LICENSE 与 requirements.txt，核心代码与 QUICKSTART.md 缺失，无法验证实际行为。
- llama-cpp-python 未固定版本，存在依赖漂移与本地编译风险。
- 无用户确认、敏感数据处理或回滚机制的证据，不应视为生产可用。
- 发布者身份未经验证，维护责任与更新路径不明确。