系列：AI Agent 工程实践
上一篇：第 19 篇《从 Demo 到生产环境——AI Agent 的工程 Checklist》
下一篇：第 21 篇《为什么 Demo 永远变不成生产系统》

---

开场：零件都在工具箱里，但你卡在了一个空目录前

你跟着这个系列从 01 写到了 19。

Rules 分层了，Memory 有了长期架构，Review 每天跑，Tool 用 MCP 接好了，状态、可观测、Benchmark 也都齐了。你确实搭起了一套自己的 AI Engineering OS——它不再是 PPT 上的五层图，而是你电脑里真实存在的原则和代码片段。

然后老板（或客户，或你自己的野心）扔过来一句话：

"给我们做个 Agent 系统吧。"

你打开编辑器，新建一个 agent-system/ 目录。光标闪着。

突然卡住了。

零件全在工具箱里，但你不知道它们该放进哪个抽屉、以什么顺序咬合。你意识到：前三阶段教的是"每个零件为什么长这样"，而真实的企业项目是"几十个文件、多人协作、要上线、要监控、要换模型、要控成本"——那是系统，不是零件的并集。

这篇是第三季（理念/组件/Runtime）到第四季（企业工程化）之间的过渡篇。它不教你任何新组件，只回答一个问题：为什么零件齐全了，系统还是做不出来？ 以及，把后面 15 篇（21–35）的认知地图先铺给你看。

---

问题背景：前三阶段给了"零件"，没给"装配图"

把 01–19 拆开看，它们其实在讲三类东西：

阶段	在讲什么	给你的"零件"
第一阶段 理念与架构	为什么要做 AI Engineering OS	五层架构心智模型
第二阶段 基础组件	Rules / Memory / Knowledge / Review	记忆、规则、知识、复盘四件套
第三阶段 Agent Runtime	Planner / Context / State / Tool / MCP	运行时、工具、协议、状态、可观测

这些"零件"有一个共同特征：它们都是独立概念，被刻意拆开讲。这是教学的需要——一次只解决一个"为什么这样设计"，你才记得住。

但企业项目不是按"概念"组织的，是按"目录"组织的。真实仓库里没有 memory_layer.py 和 tool_calling.py 平铺在一起让你挑——它们被塞进 runtime/、memory/、tools/ 这些文件夹，被 provider/、config/、infra/ 包围，被 api/、web/、monitor/ 包裹。

换句话说：你缺的不是知识，是"把知识翻译成目录结构"的能力。这正是工程化思维的第一课。

---

错误尝试：三个最容易掉进去的坑

错误尝试一：全塞进一个 chat.py

最自然的反应——"我之前跑通的 demo 就是 chat.py 几百行，复制过来加功能就行"。

agent-system/
└── chat.py        # 工具调用、Memory、Prompt、Provider 全在这

demo 阶段爽，加第三个功能就开始痛：改一处 Prompt 模板，Memory 的序列化逻辑跟着崩；想换模型，要在一千行里找出所有 OpenAI() 调用。最致命的是无法测试——你没法单独测"工具路由对不对"，因为工具和 UI 和记忆全缠在一起。

错误尝试二：照搬框架目录

另一个常见反应——"LangChain（或某框架）不是有项目模板吗，直接 create 一个，按它的目录填"。

问题在于：框架模板是为"用这个框架写 Agent"设计的，不是为"你的业务"设计的。你很快就会写出大量"为了适配框架而存在的胶水代码"，业务逻辑和框架强耦合。换框架 = 重写一大片；换模型 = 先过框架的适配层。当初选框架是为了快，最后却被框架绑架。

错误尝试三：每个 Agent 自己管一切

如果系统里有多个 Agent（主 Agent + 几个子 Agent），最省事的写法是"每个 Agent 各自持有一份 Memory、一份 Prompt、一份 Provider 配置"。

结果是：Memory 在三个地方各存一份、彼此不一致；Prompt 改了一个忘了改另一个；模型调用散落各处，根本没法统一限流、统一记日志、统一算成本。多 Agent 没带来分工的好处，先带来了重复和混乱。

---

关键观察：分水岭不是"更多组件"，是"更清晰的边界 + 可替换的抽象"

三个错误尝试的共同根因，是同一件事：没有做关注点分离（Separation of Concerns）。

Demo 和 Production 的真正分水岭，不在你多会调模型，而在你能不能做到三条：

① 可替换（Swap）——换模型、换数据库、换工具，改动集中在一层，不扩散。
② 可观测（Trace）——每一个请求从进来到出去，哪一环慢了、贵了、错了，一眼能看。
③ 可演进（Evolve）——加一个功能、加一个 Agent，不塌方、不回归。

这三条靠的不是新零件，而是边界：每一层只干一件事，层与层之间只通过明确定义的接口说话。前三阶段你学的每个概念，到第四阶段都会变成"系统里的一层"——它们从"你脑子里的原则"落地成"目录里的一个文件夹"。

所以前三阶段不是白学，它们是每一层的设计依据。比如：

• 你学过"为什么 Rules 要分层"（02 篇）→ 第四阶段它变成 config/ 里 core/heavy 的加载策略；
• 你学过"Memory 长期架构"（03/10 篇）→ 它变成独立的 memory/ 服务，而不是 Agent 里的一个列表；
• 你学过"为什么 Multi-Agent 多数失败"（12 篇）→ 它变成 runtime/ 里 Planner 怎么编排子 Agent 的约束。

零件没变，变的是它们被组织的方式。

---

最终方案：第四阶段（21–35）认知地图

后面 15 篇，我们不再造新零件，而是把现有零件装配成一辆能上路的车。每一篇对应系统的一个横切面：

#	主题	它解决"可替换/可观测/可演进"里的哪条
21	为什么 Demo 永远变不成生产系统	总论：Demo vs Production 的本质差异
22	项目应该如何分层	可演进：目录结构即边界
23	Provider 抽象层设计	可替换：换模型零成本
24	Tool Registry	可替换 + 可演进：工具统一管理
25	Memory Service	可替换：记忆独立成服务
26	Prompt Management	可演进：Prompt 版本化、A-B
27	日志系统	可观测：没有日志就无法调试
28	可观测性	可观测：Trace / Span / Event
29	成本控制	可演进：成本可控才能长期跑
30	Agent 如何做测试	可演进：改动不回归
31	Agent 如何部署	可演进：从笔记本到服务器
32	Agent 如何上线	可演进：灰度 / A-B / 全量
33	Agent 如何监控	可观测：上线后才知道健康问题
34	企业 AI Agent 架构	总图：所有层拼到一起
35	我的 AI Engineering OS 最终架构	收口：把前三阶段 + 第四阶段串成一体

一张图看懂"组件 → 系统"

这张图和前三阶段的"五层架构"不是矛盾，而是同一套思想的放大版：把"Agent 层"拆开成 Gateway→Runtime→Tool/Provider，把"Memory/Knowledge"显式成独立服务，再补上 Demo 阶段绝对没有的 Logging / Observability / Monitor。

Demo 与 Production 的六维对照

维度	Demo（chat.py）	Production（分层系统）
目录结构	单文件几百行	app/api/agent/runtime/memory/providers/tools/... 分层
换模型	改几十处 OpenAI()	改 Provider 一层配置
测试	手动跑通一次	Unit / Prompt / Tool / Regression 分层
监控	翻控制台日志	Trace ID 串联 + Dashboard
协作	一个人改	多人按层分工，接口约定
演进	加功能就重构	加功能只动对应层

---

代码或配置示例：从单文件到分层的目录演化

Demo 阶段（你现在的起点）：

agent-system/
└── chat.py

过渡阶段（错误尝试一，加功能就开始痛）：

agent-system/
├── chat.py          # 主循环
├── memory.py        # 记忆，和 chat.py 强耦合
├── tools.py         # 工具，和 chat.py 强耦合
└── config.py        # Prompt 模板也塞在这

Production 阶段（第四阶段 22 篇会展开，这里先看骨架）：

agent-system/
├── app/             # 应用入口
├── api/             # 对外接口
├── agent/           # Agent 编排
├── runtime/         # Planner / Context / State
├── memory/          # Memory Service
├── providers/       # Provider 抽象层
├── tools/           # Tool Registry
├── models/          # 数据模型
├── config/          # 配置（含 Prompt Registry）
└── infra/           # 部署 / 监控基础设施

注意：从"过渡"到"Production"，不是代码量变多，而是依赖方向变清晰——runtime/ 依赖 providers/ 的接口，而不是反过来；tools/ 通过 Registry 暴露，而不是被 chat.py 直接 import。这正是 22、23、24 三篇要细讲的。

---

设计权衡：这篇为什么"不解决具体问题"

写过渡篇有个天然矛盾：读者想要干货，但过渡篇本身不教新组件。

我的判断是值得写，而且必须写在前头，理由有三：

1. 避免一进第四阶段就被目录结构劝退。 21 篇直接甩你一张分层目录，没有这篇铺垫，你不会理解"为什么非得这么分"，只会觉得"又是在套模板"。
2. 呼应反过度工程的原则。 我必须诚实地说：小项目、单人、自己玩，根本不需要全套。你用 chat.py + 一个 .env 就够了。第四阶段的价值，只在"你要做企业级、要多人协作、要长期维护"时才真正显现。所以这篇先帮你判断"你现在需不需要进第四阶段"。
3. 前三阶段是地基，这篇是封顶仪式。 它明确告诉你：你已经会造零件了。接下来 15 篇，是造整车。

反过来，不选"跳过过渡直接写 21"的理由：那会让读者带着"组件思维"进入系统篇，把每一篇当成孤立的新知识点，而不是"整车的一个部件"——这正是多数人学完一堆概念仍写不出项目的原因。

---

总结

• ✅ 前三阶段（01–19）给你的是零件：架构心智、基础组件、Runtime 能力。
• ✅ 零件齐全 ≠ 系统能跑。缺的是把知识翻译成目录结构的工程化思维——关注点分离。
• ✅ Demo 与 Production 的分水岭是三条：可替换、可观测、可演进。靠边界，不靠新零件。
• ✅ 第四阶段（21–35）不造新零件，只把现有零件装配成企业系统：分层 → Provider 抽象 → Tool Registry → Memory Service → Prompt 管理 → 日志/可观测 → 成本 → 测试 → 部署 → 上线 → 监控 → 企业架构 → 最终串联。
• ✅ 小项目不必全套；当你要做企业级、要协作、要长期维护时，第四阶段才值回票价。

你已经会造零件了。下一篇，我们从"为什么 Demo 永远变不成生产系统"开始，造整车。

---

参考资料（带用途说明）

• 本系列 01–19 篇：前三阶段的全部工程决策，是第四阶段每一层的设计依据（本文多处回链）。
• 《12-Factor Agents》（人类学家 Chroma 团队）：理解"把 Agent 拆成可替换步骤"的关注点分离思想，对应本文"关键观察"。
• OpenTelemetry 官方文档：第四阶段 28 篇可观测性的标准术语来源（Trace / Span / Event），对应本文架构图。
• 本系列（19）生产 Checklist：本文"问题背景"里"零件齐全但系统空白"的对照基线——十项全过只是 Demo 关门，系统开门另算。

---

本文是 [AI Agent 工程实践] 系列的第 20 篇（第三季→第四季 过渡篇）。

系列导航

上一篇：第 19 篇《从 Demo 到生产环境——AI Agent 的工程 Checklist》
下一篇：第 21 篇《为什么 Demo 永远变不成生产系统》