学 Agent 开发总是卡在理论？来，跟着这个开源项目从零写一个。
背景：学 Agent 的尴尬断层
最近在做一个事，想从零开始带大家写一个产品级的 Coding Agent。
起因是我发现，学 Agent 开发有一个很尴尬的断层------
看概念？ReAct、记忆机制、上下文工程......这些看完都懂了，但一到真实项目里就不知道怎么把它们组装成一个能跑的系统。
看开源项目？代码量太大，文件几百个，新手根本找不到入口在哪。
所以我换了个方式，做了一个实战连载项目：Zero2Agent。
Zero2Agent 有什么不同？
市面上的 Agent 学习资源大多两极分化------要么只讲概念，要么直接丢一个庞大的开源仓库。Zero2Agent 想做的是中间那座桥。
| 常见问题 | Zero2Agent 的做法 |
|---|---|
| 纯概念，看完不会动手 | 侧重工程实践：每一步都有真实代码和架构考量，从细节理解 Agent 的运作原理 |
| 项目太大，无从下手 | 小步迭代开发：像追剧一样跟着 Story 每周练一点，把庞大系统拆解为可执行的小目标 |
| Demo 级别，不够真实 | 产品级标准：融入真实业务中的实战经验，深入产品级的实践细节 |
一句话总结：这是一门带你一起做的实践课程。
路线图：我们将如何展开？
整个项目按 Epic → Story 的方式组织，目前规划了 5 个 Epic：
Story 1：让 Agent 跑起核心循环
目前第一节已更新，目标很明确------实现最经典的 ReAct Loop。
聊天 vs Agent：本质差异在哪？
传统的 AI 对话是一问一答的开环 ；而 Agent 的核心，是一个自主运行的闭环。
在第一课中，我们用最精简的代码，实现最经典的 ReAct（Reasoning and Acting）模式，让 AI 学会：
观察环境 → 思考决策 → 调用工具执行 → 观察结果 → 继续决策 → ...... → 结束先做"只读闭环"
如果一开始就把写文件、执行命令、安全审批全塞进来，你会面对太多变量，反而看不清 Agent 最核心的工作机制。
只做只读闭环，能让我们把注意力集中在三件事上：
- 循环怎么跑起来？
- 工具怎么接入循环？
- 拿到的工具结果为什么还要回传给模型？
我们精选了两个刚好互补的工具，搭建"先看目录 → 再读文件 → 继续决策"的工作流：
| 工具 | 作用 |
|---|---|
list_directory |
获取文件树。没有它，Agent 只能盲猜路径 |
read_file |
查看文件内容。没有它，Agent 看不到具体细节 |
揭开黑盒：Agent Loop 与 Tool Use
Agent Loop ------ Agent 不是魔法，它的本质是一个用代码写出的 while 循环。模型不再返回一次性回答，而是返回结构化的 stop_reason。只有当返回 end_turn 时循环才结束；如果是 tool_use，则触发宿主的工具执行逻辑，并进入下一轮。
调用 LLM → stop_reason 分支 → 执行工具并写回 → ↻Tool Use ------ 这是让 LLM 从"只能说"变成"能做事"的桥梁。我们使用强类型的 JSON Schema 来定义工具。模型通过标准的 tool_calls 吐出需要调用的函数名和参数，宿主执行后再通过 tool_result 将物理世界的观测注入回上下文中。
这正是 Claude Code / Codex / Cursor 等 Coding Agent 的基石。
丰俭由人：选择你的学习深度
无论是 Story 1 还是后续更复杂的架构，本系列都提供完整的代码仓库和实操指引。你可以根据自己的时间精力选择"食用"方式：
| 深度 | 时间 | 适合 |
|---|---|---|
| 浅度浏览 | ~20 分钟 | 阅读图文讲解和核心代码片段，快速补充认知 |
| 实践跟练 | 1~2 小时 | Clone 仓库，切到对应 Tag，根据文档自己动手实现核心模块 |
| 深度学习 | 更多时间 | 阅读 Story 中的深度拓展内容，了解更多工程细节和产品实践 |
完全开源
本系列的所有代码、技术文档、知识总结和每一步迭代的变更记录，都同步开源在 GitHub 上。
你可以拉取代码在本地跟练实践，也可以在 GitHub 上直接阅读。
👉 GitHub 仓库：alienzhou/zero2agent
实践课程正在持续迭代中。第一课已上线，从最经典的 ReAct Loop 开始。
欢迎 Star 仓库追更，有问题评论区聊 🙌