AI Agent 工程化实战 #00：从“能聊”到“可交付”究竟要建设什么

不少 Agent 项目都能很快做出可对话的演示，但一旦进入多人协作、持续发布和线上运维阶段，隐藏的边界、依赖与失败处理问题便会集中暴露。要跨过从“能聊”到“可交付”的门槛，需要先明确成熟度标准，再把契约、分层、门禁和运行手册落实为可检查的工程产物。

AI Agent 工程化实战 #00：工程化到底在工程什么（本文） | 后续从契约、分层写到发布与协作

能跑通一次对话，不等于能交付一个 Agent。中间差的通常不是「再换一个更强的模型」，而是一套可检查的工程约束：边界写没写清、依赖有没有分层、失败能不能解释、上线前卡不卡得住、出事了知不知道先做什么。

本系列定位是施工手册：给可复制的契约、检查表、门禁与值班卡。不写某一仓库的模块游记，也不做概念百科。需要术语时只给一句人话定义，然后落到交付物。

读完本篇应能回答三件事：

1. 当前 Agent 卡在 L1 / L2 / L3 哪一层
2. 「工程化」具体要产出哪些文件，而不是一句口号
3. 后面 8 篇各自补哪一块缺口

---

1. 先把词钉死：这里的「工程化」指什么

软件工程里早就有契约、分层、发布、值班。Agent 工程化不是另起炉灶，而是把同一套纪律，施加在不确定输出和带副作用的工具调用上。

传统服务	Agent 额外难点
输入输出类型稳定	同输入也可能得到不同表述与路径
失败码相对可控	失败可能是幻觉、拒答、工具半成功、超时后重试导致重复副作用
变更主要是代码/配置	变更还包括 Prompt、工具清单、检索策略、模型路由
「正确」常可用断言	「正确」常要抽样、人审、场景集，不能只靠单测绿

因此，本系列把「工程化」收成一句可操作定义：

让 Agent 的边界、依赖、质量与变更，都留下可检查产物；任何人按产物能复现判断，而不是按感觉调参。

反过来说，下面这些不算工程化完成：

• 接了某个 Agent 框架
• 演示环境聊通了一次
• Prompt 里写了很多「你是专业助手」
• 加了 RAG / 多工具 / 多 Agent，但没有契约与门禁

能力可以堆；没有交付物的能力，只是更难维护的 Demo。

---

2. 问题：为什么多数项目死在「能聊」之后

2.1 五类结构性缺口

现象	表面动作	实质缺口	拖久了的后果
换个问法就崩	继续改 Prompt	无成功/失败/拒答语义	无法写测试，也无法对用户解释
功能越加越怕改	再拆一个「智能模块」	分层与依赖混乱	改检索影响编排，改模型影响权限
「感觉能上」	找几个人试聊	无发布前门禁	回滚时不知道回滚的是 Prompt 还是工具
线上出事只会看模型日志	加坚控大盘	无请求级关联与决策顺序	告警很多，动作没有
只有作者能改	口头交接	无契约与责任边界	人一走，系统立刻不可维护

这些缺口有共同特征：换框架补不上。框架解决的是调用编排的便捷性；缺口在「判断标准」和「变更纪律」。

2.2 三条常见弯路

弯路 A：能力堆叠当进度

RAG、多模态、多 Agent、记忆、工作流全上。演示更好看，但验收标准仍是「聊得顺不顺」。结果是表面积变大，故障面同步变大。

弯路 B：把不确定性全塞进 Prompt

业务规则、权限、拒答、格式、工具选择全靠一段系统提示词。短期灵活，长期不可测：改一个字影响整片行为，也没法做细粒度回滚。

弯路 C：用「再观察观察」代替门禁

没有固定用例集，就没有回归。每次发布都是新产品，旧问题以新措辞回来。

施工手册的立场很明确：先把 L2 的契约与分层立住，再谈能力扩张；L3 的门禁与手册没齐，不宣称「生产级」。

---

3. 工程约束：L1 / L2 / L3 完成度

用三层完成度代替「做完了吗」这种空问题。

L1 能聊  →  单次对话链路通，能出结果
L2 能用  →  约定场景下可重复；失败可解释；边界可测试
L3 能运维 →  可观测、可门禁、可灰度、可回滚、有人负责

L1 能聊（链路通）
        │
        ▼
L2 能用（契约 + 分层 + 可测）
        │
        ▼
L3 能运维（门禁 + 手册 + 责任）

※ 最常见误判：停在 L1，却口头宣称「已上线」

3.1 每层的验收标准（写进评审用）

层级	必须同时满足	缺一条就不算进入该层
L1	主路径能跑通；有最小日志	只能本地、不能给第二人复现
L2	有一页 Contract；成功/失败/拒答可举例；工具有超时与错误语义；核心场景可重复跑	仍靠「再试一次」判断好坏
L3	发布前有固定用例门禁；请求可串联排查；有降级/回滚步骤；有责任人	出问题只能重启或改 Prompt 碰运气

3.2 每层的典型反例

层级	反例（看起来像完成，实际没有）
L1	只在作者机器、只对一个「标准问题」通
L2	有长文档，但没有可执行的成功/失败例子；工具失败时模型自己编理由
L3	有漂亮仪表盘，但没有「何时回滚 Prompt / 何时下线工具」的动作卡

3.3 三层之间的硬约束

1. L1 ≠ 交付。 演示通过只证明链路存在。
2. 进 L2 必须有契约。 契约是后续分层、工具准入、评估用例的共同尺子。
3. 进 L3 必须有门禁与手册。 没有发布检查与回滚步骤，最多算「多人可用的 L2」。
4. 允许长期停在 L2。 内部工具、低频场景可以不冲 L3；但不能把 L2 说成生产级。
5. 禁止跳级叙事。 没有 Contract 却大谈「生产可观测」，属于包装，不是工程。

3.4 三十分钟自检（当场定层）

按顺序问，走到哪条「否」就停在对应层之下：

1. 第二人按文档能否在 15 分钟内跑通主路径？否 → 未稳 L1
2. 能否写出 3 个成功例、3 个应失败/拒答例，并且实际表现一致？否 → 停在 L1
3. 工具超时/报错时，用户侧是否有稳定语义（而不是模型临场发挥）？否 → 未稳 L2
4. 发布前是否有一组固定用例，不过就禁止发布？否 → 停在 L2
5. 线上故障是否有「先看哪些字段 → 下一步动作」的卡片？否 → 未到 L3

把结果记在交付物清单上，比争论「算不算生产级」有用。

---

4. 做法：工程化要动刀的六块

六块对应本系列后续篇章。这里先给定义、缺了会怎样、最小产物、错误做法——够用来排期，细节留给专章。

4.1 契约（Contract）

定义： 把 Agent 当对外服务描述：适用场景、非目标、输入、输出、超时、拒答、错误语义、权限与人工介入点。

缺了会怎样： 产品、研发、测试对「什么叫好」各说各话；评估用例无从写起。

最小产物： 一页 Contract（建议不超过屏过多的空话，多写可判定的例子）。

错误做法： 写成宣传文案；或把全部规则塞进 Prompt，文档与真实行为脱节。

4.2 分层（Layering）

定义： 接入、编排、工具/知识、模型、观测与门禁，职责分开；依赖单向，禁止「智能一锅炖」。

缺了会怎样： 改温度参数影响权限判断；改检索策略拖垮会话状态；无法单独测试一层。

最小产物： 一张分层图 +「改需求动哪一层」决策表。

错误做法： 按公司组织架构硬拆微服务，但逻辑仍搅在一起；或为了「架构好看」过度拆分。

4.3 工具与外部能力接口化

定义： Tool / API / MCP 统一约定超时、幂等、错误码、权限、版本、下线；副作用可审计。

缺了会怎样： 重复调用造成重复下单/重复评论；工具半成功时状态机卡死；下线一个工具导致编排全面报错。

最小产物： Tool Spec 模板 + 准入/禁入清单。

错误做法： 把高危操作（删库、、广播）不加确认地暴露给模型；用「模型自己会小心」代替权限。

4.4 状态与记忆策略

定义： 会话态、任务态、长期记忆分生命周期；写入有门槛，读取有隔离，删除有规则。

缺了会怎样： 串台、隐私泄漏、过期事实被当成真理、上下文无限膨胀导致成本与幻觉双升。

最小产物： 一页记忆策略（记什么 / 不记什么 / 多久过期 / 谁能读）。

错误做法： 「能存就全存」；或上复杂记忆网络却说不清读写边界。

4.5 质量门禁（Eval Gate）

定义： 离线集、冒烟、抽样人审进入开发与发布流程；红线拦发布，灰线只告警。

缺了会怎样： 每次上线都是堵薄；「昨天还好」无法复现；回归靠运气。

最小产物： 最小用例集（哪怕先 20 条）+ 发布门禁规则。

错误做法： 只有自动打分、无人审样本；或门禁全是主观分，导致永远可以「特批通过」。

4.6 观测、发布与协作

定义： 请求级关联字段服务排查；Prompt/工具/编排/模型四类变更分开灰度与回滚；契约与事故有责任人。

缺了会怎样： 仪表盘很忙，决策很慢；回滚时改错对象；知识全在一个人脑子里。

最小产物： 观测字段约定、On-call 决策卡、变更检查表、RACI（谁负责契约/工具/门禁/事故）。

错误做法： 观测等于「把所有日志灌进平台」；发布等于「重启一下」。

→ 展开见 #06–#08

契约 ──► 分层 ──► 工具接口 ──┐
  │         │                ├──► 质量门禁 ──► 观测与发布 ──► 协作与所有权
  │         └──► 记忆策略 ───┘
  └──────────────────────────┘

依赖关系很直接：契约是尺子，分层是骨架，工具与记忆是皮肉，门禁是闸，观测发布与协作是日常能活下去的条件。

5. 不做什么：和另外两类内容划界

内容类型	解决什么	本系列态度
项目实战故事	「某个系统怎么落地的」	可作匿名正反例，不作主线
概念深入	「Agent / RAG / 记忆原理是什么」	只保留一句定义，不展开成专章
工程化施工	「怎样才算可交付、可演进」	本系列主线

刻意不做的清单：

• 按 RAG / 多模态 / 多 Agent 编排开「能力专章」
• 某一具体仓库的包名导览
• 保证效果、对比薪资、攻击其他方案

能力模块不是不重要，而是没有契约与门禁时，先开能力专章会强化弯路 A。

---

6. 带走物一：工程化交付物清单（可直接进 Wiki）

6.1 总表

ID	交付物	最低要求	对应层	如何快速验收
D1	Agent Contract	含场景、非目标、成功/失败/拒答例	L2	测试能否只凭此页写用例
D2	分层说明	各层职责 + 依赖方向	L2	随机提一个需求，能指到层
D3	Tool Spec / 准入清单	超时、错误、权限、是否幂等	L2	任意工具能找到 Spec
D4	记忆策略	写入门槛、过期、隔离、删除	L2	举得出「不该记」的例子
D5	Eval Gate	固定用例 + 红线/灰线	L3	不过门禁时发布通道可阻断
D6	观测字段约定	requestId/trace、用户、工具、模型、错误码	L3	抽一条失败请求能串起来
D7	On-call 决策卡	重试→降级→熔断→回滚 的顺序与条件	L3	新人能按卡做前两步
D8	变更发布检查表	Prompt/工具/编排/模型分类	L3	最近一次发布能归类
D9	文档与责任最小集	Contract / Runbook / Changelog + 责任人	L3	事故时 5 分钟内找到负责人

6.2 建议落地顺序（避免平行空转）

第 1 周：D1 Contract（先写例子，再写空话）
第 2 周：D2 分层 + D3 现有工具补 Spec
第 3 周：D4 记忆策略（没有长期记忆就显式写「不做」）
第 4 周：D5 最小门禁（先 20 条真例，再谈自动化）
然后：D6 → D7 → D8 → D9

「显式写不做」也是交付物。比口头「以后再说」干净。

6.3 清单使用规则

1. 缺 D1，不扩能力。 新工具、新检索、新 Agent 节点一律排队。
2. D5 未建立前，不宣称 L3。
3. 每次发布更新 Changelog，并勾选 D8。 发完再补文档，等于没门禁。
4. 清单可以裁剪，不能伪造。 裁掉的项标注「本期不做 + 原因」。

---

7. 带走物二：系列地图与阅读路径

编号	完整标题	要解决的问题	核心带走物
#00	AI Agent 工程化实战 #00：工程化到底在工程什么	工程化是什么、卡在哪一层	本文：清单 + 地图
#01	AI Agent 工程化实战 #01：边界先行——Agent 的产品契约	好坏无法判定	Contract 模板
#02	AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅	改一处炸一片	分层检查表 / 动哪层决策表
#03	AI Agent 工程化实战 #03：工具与外部能力——接口化	副作用与半成功	Tool Spec + 准入清单
#04	AI Agent 工程化实战 #04：状态与记忆——工程视角	串台、膨胀、过期事实	记忆策略一页纸
#05	AI Agent 工程化实战 #05：质量门禁——嵌进流水线	发布靠感觉	最小 Eval Gate
#06	AI Agent 工程化实战 #06：可观测与运行手册	出事无动作	On-call 决策卡
#07	AI Agent 工程化实战 #07：发布与演进——版本、灰度、回滚	变更搅在一起	变更分类 + 发布检查表
#08	AI Agent 工程化实战 #08：协作与所有权	知识在单人脑子里	RACI + 成熟度 L0→L3

推荐路径

• 从零开始：#00 → #01 → #02，再按缺口选读
• 已有可用 Demo：用 §3.4 定层 → 缺啥读啥，不必按编号硬读完
• 准备对外承诺稳定性：#05 → #06 → #07 优先，契约 (#01) 仍不能缺

---

8. 下一篇预告

AI Agent 工程化实战 #01：边界先行——Agent 的产品契约

把成功、失败、拒答、超时、人工介入写成一页可测试的 Contract。没有这一页，分层、工具、门禁都缺少共同尺子。

---

系列导航

编号	完整标题	状态
#00	AI Agent 工程化实战 #00：工程化到底在工程什么	本文
#01	AI Agent 工程化实战 #01：边界先行——Agent 的产品契约	下一篇
#02	AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅	待更
#03	AI Agent 工程化实战 #03：工具与外部能力——接口化	待更
#04	AI Agent 工程化实战 #04：状态与记忆——工程视角	待更
#05	AI Agent 工程化实战 #05：质量门禁——嵌进流水线	待更
#06	AI Agent 工程化实战 #06：可观测与运行手册	待更
#07	AI Agent 工程化实战 #07：发布与演进——版本、灰度、回滚	待更
#08	AI Agent 工程化实战 #08：协作与所有权	待更