09 — 实战项目

这一章不是让你一次性做一个“大而全”的 Agent 平台，而是把课程里的知识按工程顺序串起来： 先写出能跑的最小循环，再接入检索和调研，最后再做多 Agent 编排、评估和可观测性。

项目清单

项目	目标	用到的章节	建议时机
实战项目	三个逐步递进的 Agent 项目	01 ~ 08	按章节推进

项目之间怎么递进

阶段	你在证明什么	不急着做什么
Minimal Agent	我能手写 tool loop，知道模型和代码各自负责什么	框架、复杂 UI、大量工具
Research Agent	我能让 Agent 按需检索、控制上下文、带出处回答	多 Agent、复杂权限、自动发布
Multi-Agent App	我能把多个 Agent 组织成可评估、可追踪的系统	过度抽象、全功能平台、无边界扩张

做项目时最重要的不是“功能堆满”，而是每一阶段都能回答三个问题：

1. 输入是什么，输出是什么。
2. Agent 哪一步做决策，代码哪一步做约束。
3. 出错、变贵、答错时，我能不能复盘。

建议做法

• 边学边做，别攒到最后。每学完一个知识块，就回来推进对应项目。
• 每个项目都从"能跑的最小版本"起步，再逐步加功能。
• 项目代码统一放在仓库根目录的 code/，本章节只记录目标、设计、验收和复盘。
• 做完复盘：哪里卡住了？回头补哪一章？把心得写进对应项目目录的 README。
• 每个项目都至少留一份“最小可运行版本”，别只保留最终版。
• 每次改动前后都跑一遍自己的小测试。
• 先用 mock 数据跑通控制流，再替换成真实 API。这样能把“Agent 逻辑问题”和“外部服务问题”分开。
• 所有密钥都放环境变量，不要写进代码或笔记。
• 每次加一个能力，就补一条测试任务和一条运行日志。

通用项目骨架

每个项目都可以按这个顺序推进：

1. 定义任务边界：这个 Agent 只解决哪类问题，不解决哪类问题。
2. 写最小版本：只有一个入口、少量工具、能跑通主链路。
3. 加日志：记录输入、工具调用、输出、token、耗时、错误。
4. 加测试任务：准备 5-10 条代表性输入，手动或脚本化跑一遍。
5. 加保护：最大轮数、工具参数校验、预算限制、危险操作确认。
6. 再优化：换模型、调 prompt、加缓存、加评估、加框架。

不要一上来就设计“通用 Agent 平台”。这类平台经常还没跑通第一个任务，就已经有十几个抽象层。

每个项目都要留下什么

建议每个项目目录里至少留下四类产物：

产物	用途
README.md	写清目标、运行方式、最小版本、加分项、复盘
main.py 或入口文件	能从命令行直接跑
evals/ 或测试样本	放 5-20 条代表性任务
logs/ 或示例日志	留一两次真实运行轨迹，方便复盘

哪怕只是学习项目，也要像一个小工程，而不是一段临时脚本。

三个项目的关系

项目	你会练到什么
Minimal Agent	tool loop、messages、错误处理、基础日志
Research Agent	RAG、规划、上下文管理、证据和出处
Multi-Agent App	编排、通信、冲突处理、评估、可观测性

前一个项目的成果应该能被后一个项目复用：

• Minimal Agent 的 tool loop，是 Research Agent 的底座。
• Research Agent 的检索和报告能力，是 Multi-Agent App 里的调研工人。
• 08 章的评估和可观测性，是最后把 demo 变成作品的关键。

最小版本和加分项怎么区分

很多项目做不完，不是因为难，而是因为一开始没划边界。

类型	应该包含	暂时不要包含
最小版本	主流程能跑、能看日志、能处理失败	UI、数据库后台、复杂权限
可用版本	有测试样本、有成本统计、有错误边界	多租户、自动调度、复杂部署
加分项	流式输出、评估报告、缓存优化、可视化 trace	与当前学习目标无关的功能

每做完一版，都给自己留一个能回退的稳定点。后面折腾坏了，也知道哪一版是能工作的。

推荐复盘方式

每个项目做完后，不只写“完成了什么”，更要写清楚：

• 哪一步最容易错。
• 哪个 prompt 或工具描述改动最有效。
• 哪条测试样本暴露了问题。
• 哪个地方成本最高。
• 如果重做，会先写哪一部分。

这些复盘会反过来帮你理解前面 01-08 章，不然很多知识点只会停在“我看过”。