Agent 项目阶梯与生产交付：从 ReAct Demo 到企业级系统
这篇覆盖 Python AI Agent 路线融合指南 的阶段四与阶段五：项目实战阶梯与生产交付。它对应外部 python-ai-agent 项目的阶段八（实战项目路线）与阶段七（工程化部署与运维）。
这页解决一个常见问题：写了很多 Demo，作品集却拿不出手。原因是 Demo 只证明"会调 API"，不证明"能交付"。下面五级项目按难度递进，每级都给出合格标准——达不到标准就停在这一级补，不要堆项目数量。
五级项目阶梯
| 级别 | 项目 | 核心能力 | 周期 |
|---|---|---|---|
| L1 | ReAct 智能问答 Agent | 工具调用、循环、终止条件 | 1 周 |
| L2 | 知识库 RAG Agent | 入库、检索、引用、拒答 | 2 周 |
| L3 | 多角色内容创作团队 | 多智能体分工、共享状态、仲裁 | 2 周 |
| L4 | 数据分析 Agent | Text2SQL、权限查询、结果解释 | 3 周 |
| L5 | 企业智能客服 Agent | 生产化：权限、持久化、监控、租户隔离 | 6-8 周 |
L1-L2 是入门必做，L3/L4 二选一深入，L5 是毕业设计。每一级都建议先读对应理论再动手：L1 对应 Agent 工程总览，L2 对应 RAG 入库链路，L3 对应 多 Agent 系统，L4 对应 Agent Text2SQL 工程实践，L5 对应本站企业知识库 Agentic RAG 全章。
L1：ReAct 智能问答 Agent
最小 Agent：一个 LLM + 两三个工具（如天气查询、计算器）+ ReAct 循环。
合格标准：
- 有明确的终止条件（最多 N 轮、模型给出最终答案）。
- 工具调用失败时，错误作为消息回给模型而不是直接崩溃。
- 有日志：每轮思考、每次工具调用、耗时。
- 有单元测试：mock 模型输出，验证循环路由正确。
踩坑预警：循环不设上限导致 token 爆炸；工具异常直接 raise 导致会话中断；没有日志导致无法解释模型为什么调错工具。
L2：知识库 RAG Agent
在 L1 上加检索：文档入库 → 向量化 → 检索 → 带引用作答。
合格标准：
- 入库链路可重跑：文档解析、分块、向量化、入库幂等。
- 答案带引用，引用能对齐到原文片段。
- 检索不到证据时明确拒答，而不是编造。
- 有一组 Bad-case 样例：召回失败、证据冲突、超纲问题的预期行为。
这个项目的工程细节（权限过滤时机、引用对齐、拒答策略）见 RAG 检索与重排、RAG 引用与拒答。
L3 或 L4：选一个深入
L3 多角色内容创作团队练多智能体：规划者、写作者、审核者分工，共享状态里传稿件，仲裁规则定"谁说了算"。合格标准：分工边界清晰、单 Agent 失败不影响整体、能解释为什么这个问题需要多 Agent。
L4 数据分析 Agent练 Text2SQL：自然语言 → SQL → 执行 → 结果解释。合格标准：只读权限的数据库账号；SQL 生成失败有重试与降级；表结构理解有测试集；敏感字段有权限过滤。工程细节见 Agent Text2SQL 工程实践。
选择标准：作品集里 L4（数据分析）比 L3（内容创作）更有工程说服力，因为它涉及权限、SQL 安全和结构化输出；L3 适合想突出多智能体编排的情况。两个都做不如把一个做到 L5 标准。
L5：企业智能客服 Agent（毕业设计）
把 L2 的 RAG 能力和 L4 的数据能力捏合成一个生产级系统：意图分流 → 知识问答 → 满足不了建工单/转人工 → 多租户后台。
生产化不是加功能，是堵住每个环节的不靠谱：
| 不靠谱 | 机制 |
|---|---|
| 服务重启状态丢失 | Checkpointer + Redis/Postgres 持久化 |
| 租户数据越权 | thread_id = 租户 + 会话；向量库元数据过滤；所有查询带租户条件 |
| 高危操作失控 | 角色权限分级 + 人工审批 |
| 故障无感知 | 成功率/失败率指标 + 告警 + trace_id 链路日志 |
| 改 prompt 引入回归 | 评测集 + Bad-case 队列 + 改动必跑评测 |
| 发布切断在途请求 | 优雅停机 |
| 部署不可复制 | Docker Compose 一键拉起应用 + worker + Redis + PG + 向量库 |
多租户隔离最容易漏的是检索和后台导出：应用层做了隔离，但向量检索没带租户过滤、后台导出没校验租户，B 租户就能看到 A 租户数据。隔离必须贯穿状态、检索、查询、导出全链路。
完成标准不是"页面能答对问题"，而是：权限过滤可验证、入库失败可重试、评测报告能说明召回/引用/拒答情况、一条命令能本地拉起全套依赖。
这个项目与本站 企业知识库 Agentic RAG 实战 是同一能力层级——L5 可以直接以本站项目的架构为蓝本，重点放在自己动手实现权限、评测和运维章节。
工程化部署贯穿每一级
部署不是最后一章，而是从 L1 就开始习惯：
- 配置：环境变量 + pydantic Settings，不硬编码 key。
- 服务化：FastAPI 包一层，提供健康检查端点（见 FastAPI 基础、FastAPI 进阶）。
- 容器化：Dockerfile + Compose，从 L1 起每级项目都能一条命令拉起。
- 观测：结构化日志从第一天就有，指标和告警在 L2+ 加入。
- 后台任务：入库、批量处理放 worker，不放请求进程（见 后台任务、消息队列）。
作品集表达
每个项目放三样东西，比代码本身更重要：
- README 一页：问题背景、架构图、核心取舍、如何运行。
- 一段演示：录屏或 GIF，展示一个正常流程 + 一个失败处理。
- 一份复盘：最难的问题是什么、怎么定位的、如果重做会改什么。
面试官判断工程能力靠的是复盘里"为什么这样设计"，不是功能列表。参考本站 Agentic RAG 项目求职复盘 的表达方式。
项目检查清单
每个项目交付前过一遍：
- [ ] 这个需求真的需要 Agent，还是 Prompt Chain / RAG 已够？
- [ ] 模型输出进入系统前经过结构化校验吗？
- [ ] 有副作用的工具，谁负责确认和回滚？
- [ ] 用户看到的每条事实能追到证据吗？
- [ ] 失败时，日志和评测能定位到具体环节吗？
- [ ] 一条命令能拉起完整环境吗？
- [ ] 有没有一组 Bad-case 和预期行为说明？
下一步
- 企业知识库 Agentic RAG 实战：项目目标与架构：L5 的完整实现参考。
- Agent 评测、Agent 安全、Agent 可观测性：L5 的三大加固方向。
- Agent 部署：部署细节。
来源与授权说明
本篇吸收并改写自 umlink/python-ai-agent 阶段八（实战项目路线）与阶段七（工程化部署与运维）的项目分级结构，已取得作者授权。原项目采用 MIT License。