AI Agent 工程化实践：从套壳到可维护的系统
整理我在 AI Agent 项目中踩过的工程化坑，覆盖提示词治理、工具编排、上下文管理和评估闭环四条主线，以及为什么"接了工具调用"不等于"工程化完成"。
为什么“套壳”撑不住
很多人最初接触 AI Agent，都是从一段提示词加一个工具调用开始。这种结构在 demo 阶段很爽——几十行代码就能跑出一个能调用外部 API 的“智能体”，发到群里收获一片惊叹。但一旦进入真实业务，问题会迅速暴露：提示词散落在代码里、工具调用没有边界、上下文越滚越长、没有评估手段、改一处崩三处。
demo 阶段之所以爽，是因为它不需要维护。真实业务里，提示词每周都要调、工具每月都要加、上下文每轮都在涨、评估每次都要跑。这些需求在 demo 阶段根本不存在，所以套壳结构在 demo 里看着没问题，一到生产就崩。
真正的工程化，是要让 Agent 变成可读、可测、可回滚、可观测的系统，而不是一段魔法咒语。可读意味着提示词和工具声明都能被同事看懂；可测意味着每次改动都有用例集兜底；可回滚意味着出了问题能定位到具体版本；可观测意味着运行时能看清 Agent 在做什么、调了什么、花了多少。
我梳理出的四条主线
经过一年的踩坑，我把 AI Agent 工程化整理成四条主线。它们不是并列的，而是有先后依赖：提示词治理是基础，工具编排是骨架，上下文管理是血液，评估闭环是神经系统。缺任何一条，系统都会失衡。
提示词治理
提示词不是注释，是逻辑。我把它从代码里抽出来，按“角色 / 任务 / 约束 / 输出格式”分段管理，并版本化。这样每次调整都有据可查，也能跑回归用例。
具体做法是把每段提示词拆成四个字段：role（Agent 扮演什么角色）、task（这次要完成什么任务）、constraint（必须遵守的约束）、format（输出必须是什么格式）。每段提示词都有版本号，改动时新增版本而不是覆盖旧版本，这样回滚时只需要切版本号，不用从 git history 里翻。
工具编排
工具不是越多越好。我倾向于把工具按“读侧 / 写侧 / 检索侧”分层，并显式声明每个工具的入参、出参、副作用和失败回退。Agent 调用工具时走统一编排层，而不是各自为政。
读侧工具（查询、搜索、读取）是幂等的，可以随便重试；写侧工具（创建、更新、删除）有副作用，必须记录调用日志和回滚策略；检索侧工具（向量搜索、关键词搜索）返回的是候选集，需要 Agent 自己判断用哪个。统一编排层负责参数校验、权限检查、调用日志、失败回退，Agent 只管调用不操心这些。
上下文管理
上下文窗口不是免费的。我做了一件事：把“长期记忆”和“当次任务上下文”分开。长期记忆走向量检索按需注入，当次上下文用结构化消息栈管理，并在每轮结束时压缩。
长期记忆不是全量塞进上下文，而是按当前任务语义检索 top-k 条相关记忆注入；当次上下文用结构化消息栈（user/assistant/tool 三种角色分明），每轮结束时把已完成的工具调用结果压缩成摘要，只保留最近 N 轮原始消息。这样上下文窗口的占用是稳定的，不会随对话变长而爆炸。
评估闭环
没有评估的 Agent 就是玄学。我维护了一个用例集，每次改动都跑一遍，记录通过率、工具调用次数、平均轮数和成本。这四个指标比“感觉好不好”靠谱得多。
通过率告诉你“做对了没有”，工具调用次数告诉你“是不是调用过度”，平均轮数告诉你“是不是绕路太多”，成本告诉你“这次改动有没有把账单打爆”。四个指标一起看，才能判断一次改动是真正的优化还是只是碰巧过了用例集。
这一阶段我得到的结论
AI Agent 工程化的核心不是模型多强，而是约束做得有多清楚。约束清楚，Agent 就稳定；约束模糊，再强的模型也会乱跑。
这四条主线本质上都是在做约束：提示词治理约束的是 Agent 的行为边界，工具编排约束的是 Agent 的能力边界，上下文管理约束的是 Agent 的记忆边界，评估闭环约束的是 Agent 的质量边界。把这四层约束都做清楚，Agent 才能从“魔法咒语”变成“工程系统”。
后面我会继续把工具编排和评估闭环拆成独立的知识库文档，逐步沉淀成可复用的排查手册。如果你也在做类似方向，欢迎对照这四条主线建立自己的工程化框架。
| 维度 | 套壳 demo | 工程化系统 |
|---|---|---|
| 提示词管理 | 散落在代码注释 | 角色任务约束分段版本化 |
| 工具调用 | 各自为政无边界 | 统一编排层显式声明副作用 |
| 上下文窗口 | 越滚越长无回收 | 长期记忆与当次任务分离压缩 |
| 质量评估 | 凭感觉判断好坏 | 用例集跑通过率与成本 |
| 改动影响 | 改一处崩三处 | 约束清楚可回滚可观测 |
- 先做提示词治理：把提示词从代码里抽出来，按"角色 / 任务 / 约束 / 输出格式"分段管理并版本化，每次调整都有据可查。
- 再做工具编排：把工具按"读侧 / 写侧 / 检索侧"分层，显式声明每个工具的入参、出参、副作用和失败回退，统一走编排层调用。
- 接着做上下文管理：把长期记忆和当次任务上下文分开，长期记忆走向量检索按需注入，当次上下文用结构化消息栈管理并在每轮结束时压缩。
- 最后做评估闭环：维护用例集，每次改动都跑一遍，记录通过率、工具调用次数、平均轮数和成本四个指标。
AI Agent 工程化的核心不是模型多强，而是约束做得有多清楚。约束清楚，Agent 就稳定；约束模糊，再强的模型也会乱跑。