很多人写的 Agent 在本地跑 demo 的时候一切完美：能调工具、能查资料、能一步步完成任务。但一上生产就原形毕露：模型输出乱码、死循环跑不停、知识库给错误答案、多 Agent 互相打架……最后只能沦为演示工具。
这篇文章总结了在生产环境落地 Agent 踩过的所有坑，以及工业界经过验证的解决方案。看完你会发现，Agent 开发的难点从来不是“能不能跑通”，而是“能不能稳定跑一万次不出错”。 
一、基础能力的工程化：这些细节决定了你的 Agent 能不能活过上线第一天
很多人觉得 Agent 的核心是大模型，只要模型够强，其他都是小事。但实际上，生产环境 90% 的问题都出在基础能力的工程化上。 
1.1 模型输出失败的全链路容错：不止是重试
下面是工业界标准的五层防御流程图，展示了从模型输出到最终兜底的完整容错链路：
#mermaid-svg-mHLQVRCoLT7FuocS{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-mHLQVRCoLT7FuocS .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-mHLQVRCoLT7FuocS .error-icon{fill:#552222;}#mermaid-svg-mHLQVRCoLT7FuocS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-mHLQVRCoLT7FuocS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-mHLQVRCoLT7FuocS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-mHLQVRCoLT7FuocS .marker.cross{stroke:#333333;}#mermaid-svg-mHLQVRCoLT7FuocS svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-mHLQVRCoLT7FuocS p{margin:0;}#mermaid-svg-mHLQVRCoLT7FuocS .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-mHLQVRCoLT7FuocS .cluster-label text{fill:#333;}#mermaid-svg-mHLQVRCoLT7FuocS .cluster-label span{color:#333;}#mermaid-svg-mHLQVRCoLT7FuocS .cluster-label span p{background-color:transparent;}#mermaid-svg-mHLQVRCoLT7FuocS .label text,#mermaid-svg-mHLQVRCoLT7FuocS span{fill:#333;color:#333;}#mermaid-svg-mHLQVRCoLT7FuocS .node rect,#mermaid-svg-mHLQVRCoLT7FuocS .node circle,#mermaid-svg-mHLQVRCoLT7FuocS .node ellipse,#mermaid-svg-mHLQVRCoLT7FuocS .node polygon,#mermaid-svg-mHLQVRCoLT7FuocS .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-mHLQVRCoLT7FuocS .rough-node .label text,#mermaid-svg-mHLQVRCoLT7FuocS .node .label text,#mermaid-svg-mHLQVRCoLT7FuocS .image-shape .label,#mermaid-svg-mHLQVRCoLT7FuocS .icon-shape .label{text-anchor:middle;}#mermaid-svg-mHLQVRCoLT7FuocS .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-mHLQVRCoLT7FuocS .rough-node .label,#mermaid-svg-mHLQVRCoLT7FuocS .node .label,#mermaid-svg-mHLQVRCoLT7FuocS .image-shape .label,#mermaid-svg-mHLQVRCoLT7FuocS .icon-shape .label{text-align:center;}#mermaid-svg-mHLQVRCoLT7FuocS .node.clickable{cursor:pointer;}#mermaid-svg-mHLQVRCoLT7FuocS .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-mHLQVRCoLT7FuocS .arrowheadPath{fill:#333333;}#mermaid-svg-mHLQVRCoLT7FuocS .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-mHLQVRCoLT7FuocS .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-mHLQVRCoLT7FuocS .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mHLQVRCoLT7FuocS .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-mHLQVRCoLT7FuocS .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mHLQVRCoLT7FuocS .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-mHLQVRCoLT7FuocS .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-mHLQVRCoLT7FuocS .cluster text{fill:#333;}#mermaid-svg-mHLQVRCoLT7FuocS .cluster span{color:#333;}#mermaid-svg-mHLQVRCoLT7FuocS div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-mHLQVRCoLT7FuocS .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-mHLQVRCoLT7FuocS rect.text{fill:none;stroke-width:0;}#mermaid-svg-mHLQVRCoLT7FuocS .icon-shape,#mermaid-svg-mHLQVRCoLT7FuocS .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mHLQVRCoLT7FuocS .icon-shape p,#mermaid-svg-mHLQVRCoLT7FuocS .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-mHLQVRCoLT7FuocS .icon-shape .label rect,#mermaid-svg-mHLQVRCoLT7FuocS .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mHLQVRCoLT7FuocS .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-mHLQVRCoLT7FuocS .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-mHLQVRCoLT7FuocS :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
校验通过
校验失败
是
否
是
验证通过
验证失败
否
模型输出
结构化校验层
执行业务逻辑
反馈修复重试
重试次数 ≤ 3?
降级策略: 规则引擎兜底
是否关键业务?
双模型交叉验证
最终兜底: 转人工
模型输出失败是 Agent 最常见的问题，没有之一。很多人遇到失败只会简单重试，但这远远不够。
首先，我们要把失败分成四类，每一类的处理方式都不一样：
- 格式失败：模型没有按照约定的 JSON 或结构化格式返回，比如多了前后缀、少了闭合括号
- 内容失败：模型输出了“我无法回答这个问题”或者无关内容，甚至直接幻觉编造
- 调用失败：API 超时、限流、服务端 5xx 错误等基础设施层面的问题
- 逻辑自洽失败：模型输出了一个行动计划，但前后步骤互相矛盾。比如第一步说“先查数据库”，第二步却直接“根据用户输入生成答案”，跳过了查询环节
工业界标准的容错方案是五层防御：
参考资料：
- Pydantic 官方文档：结构化输出校验最佳实践
- OpenAI 官方指南：如何处理函数调用错误
1.2 RAG 检索的工程化真相：向量数据库不是银弹
完整的 RAG 流程涉及多个环节，每个环节都有潜在的坑。下面是标准 RAG 流水线：
#mermaid-svg-VWfqphtuHEwNqrgE{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-VWfqphtuHEwNqrgE .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-VWfqphtuHEwNqrgE .error-icon{fill:#552222;}#mermaid-svg-VWfqphtuHEwNqrgE .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-VWfqphtuHEwNqrgE .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-VWfqphtuHEwNqrgE .marker{fill:#333333;stroke:#333333;}#mermaid-svg-VWfqphtuHEwNqrgE .marker.cross{stroke:#333333;}#mermaid-svg-VWfqphtuHEwNqrgE svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-VWfqphtuHEwNqrgE p{margin:0;}#mermaid-svg-VWfqphtuHEwNqrgE .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-VWfqphtuHEwNqrgE .cluster-label text{fill:#333;}#mermaid-svg-VWfqphtuHEwNqrgE .cluster-label span{color:#333;}#mermaid-svg-VWfqphtuHEwNqrgE .cluster-label span p{background-color:transparent;}#mermaid-svg-VWfqphtuHEwNqrgE .label text,#mermaid-svg-VWfqphtuHEwNqrgE span{fill:#333;color:#333;}#mermaid-svg-VWfqphtuHEwNqrgE .node rect,#mermaid-svg-VWfqphtuHEwNqrgE .node circle,#mermaid-svg-VWfqphtuHEwNqrgE .node ellipse,#mermaid-svg-VWfqphtuHEwNqrgE .node polygon,#mermaid-svg-VWfqphtuHEwNqrgE .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-VWfqphtuHEwNqrgE .rough-node .label text,#mermaid-svg-VWfqphtuHEwNqrgE .node .label text,#mermaid-svg-VWfqphtuHEwNqrgE .image-shape .label,#mermaid-svg-VWfqphtuHEwNqrgE .icon-shape .label{text-anchor:middle;}#mermaid-svg-VWfqphtuHEwNqrgE .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-VWfqphtuHEwNqrgE .rough-node .label,#mermaid-svg-VWfqphtuHEwNqrgE .node .label,#mermaid-svg-VWfqphtuHEwNqrgE .image-shape .label,#mermaid-svg-VWfqphtuHEwNqrgE .icon-shape .label{text-align:center;}#mermaid-svg-VWfqphtuHEwNqrgE .node.clickable{cursor:pointer;}#mermaid-svg-VWfqphtuHEwNqrgE .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-VWfqphtuHEwNqrgE .arrowheadPath{fill:#333333;}#mermaid-svg-VWfqphtuHEwNqrgE .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-VWfqphtuHEwNqrgE .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-VWfqphtuHEwNqrgE .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-VWfqphtuHEwNqrgE .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-VWfqphtuHEwNqrgE .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-VWfqphtuHEwNqrgE .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-VWfqphtuHEwNqrgE .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-VWfqphtuHEwNqrgE .cluster text{fill:#333;}#mermaid-svg-VWfqphtuHEwNqrgE .cluster span{color:#333;}#mermaid-svg-VWfqphtuHEwNqrgE div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-VWfqphtuHEwNqrgE .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-VWfqphtuHEwNqrgE rect.text{fill:none;stroke-width:0;}#mermaid-svg-VWfqphtuHEwNqrgE .icon-shape,#mermaid-svg-VWfqphtuHEwNqrgE .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-VWfqphtuHEwNqrgE .icon-shape p,#mermaid-svg-VWfqphtuHEwNqrgE .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-VWfqphtuHEwNqrgE .icon-shape .label rect,#mermaid-svg-VWfqphtuHEwNqrgE .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-VWfqphtuHEwNqrgE .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-VWfqphtuHEwNqrgE .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-VWfqphtuHEwNqrgE :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
文档解析
特殊内容预处理
文本分块
生成向量
混合检索
重排序
上下文注入
关键词检索
向量检索
RAG 是现在最火的技术，但很多人对它的理解停留在“把文档扔向量数据库里就行”。实际上，RAG 的每一个环节都有坑。
完整的 RAG 流程应该是： 文档解析 → 特殊内容预处理 → 文本分块 → 生成向量 → 混合检索 → 重排序 → 上下文注入
这里有几个最容易被忽略的细节：
- 表格和代码块不能硬切：普通的文本分块器会把表格和代码块切成碎片，导致检索不到。需要用专门的表格解析器和代码摘要提取工具
- 不要只用向量检索：一定要加上关键词检索做混合检索，很多时候精确匹配比相似性匹配更准确
- PostgreSQL + pgvector 可能比专用向量数据库更适合你：对于大多数中小项目，用 PostgreSQL 的 pgvector 扩展就能满足需求，省去维护两个数据库的麻烦。而且 PostgreSQL 的事务特性和行级锁，对于 Agent 的会话状态管理非常有用
RAG 效果也不能靠感觉，必须用可量化的指标来评估：
- Recall@K：前 K 个检索结果中包含相关文档的比例，K 一般取 5 或 10
- MRR：第一个相关文档的排名的倒数取平均，适合“只要一个正确答案”的场景
- NDCG：考虑排序位置和相关性等级，适合有分级标注的场景
参考资料：
- Pinecone：RAG 评估的完整指南
- PostgreSQL pgvector 官方文档
1.3 Agent 死循环与重复输出：如何从根源上治理
死循环是 ReAct 模式 Agent 的头号杀手。模型会反复调用同一个工具，或者输出完全一样的内容，直到把 Token 烧光。
死循环的检测方法：
- 设置最大迭代次数（一般 10 步足够），超过就强制终止
- 检测重复的 observation 内容，连续两次一样就判定死循环
- 流式输出时做滑动窗口实时检测，一旦发现连续几轮输出相似度过高，提前打断
从根源上解决死循环的方案：
- 在 prompt 中明确要求“每步必须推进状态，禁止重复相同动作”
- 在会话状态中记录历史动作，让模型知道“我已经做过这些了”
- 增加元认知步骤：每执行 3 步后，让模型自己判断“我是不是在原地打转？”如果是，主动换策略
参考资料：
- LangChain 官方文档：如何处理 Agent 死循环
1.4 工具可插拔架构：让你的 Agent 随时扩展新能力
下面是注册中心模式的工具架构设计，展示了工具如何被统一管理和动态调用：
#mermaid-svg-NdgEXC9nCWIKa2zg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-NdgEXC9nCWIKa2zg .error-icon{fill:#552222;}#mermaid-svg-NdgEXC9nCWIKa2zg .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-NdgEXC9nCWIKa2zg .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-NdgEXC9nCWIKa2zg .marker{fill:#333333;stroke:#333333;}#mermaid-svg-NdgEXC9nCWIKa2zg .marker.cross{stroke:#333333;}#mermaid-svg-NdgEXC9nCWIKa2zg svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-NdgEXC9nCWIKa2zg p{margin:0;}#mermaid-svg-NdgEXC9nCWIKa2zg .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster-label text{fill:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster-label span{color:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster-label span p{background-color:transparent;}#mermaid-svg-NdgEXC9nCWIKa2zg .label text,#mermaid-svg-NdgEXC9nCWIKa2zg span{fill:#333;color:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg .node rect,#mermaid-svg-NdgEXC9nCWIKa2zg .node circle,#mermaid-svg-NdgEXC9nCWIKa2zg .node ellipse,#mermaid-svg-NdgEXC9nCWIKa2zg .node polygon,#mermaid-svg-NdgEXC9nCWIKa2zg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-NdgEXC9nCWIKa2zg .rough-node .label text,#mermaid-svg-NdgEXC9nCWIKa2zg .node .label text,#mermaid-svg-NdgEXC9nCWIKa2zg .image-shape .label,#mermaid-svg-NdgEXC9nCWIKa2zg .icon-shape .label{text-anchor:middle;}#mermaid-svg-NdgEXC9nCWIKa2zg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-NdgEXC9nCWIKa2zg .rough-node .label,#mermaid-svg-NdgEXC9nCWIKa2zg .node .label,#mermaid-svg-NdgEXC9nCWIKa2zg .image-shape .label,#mermaid-svg-NdgEXC9nCWIKa2zg .icon-shape .label{text-align:center;}#mermaid-svg-NdgEXC9nCWIKa2zg .node.clickable{cursor:pointer;}#mermaid-svg-NdgEXC9nCWIKa2zg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-NdgEXC9nCWIKa2zg .arrowheadPath{fill:#333333;}#mermaid-svg-NdgEXC9nCWIKa2zg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-NdgEXC9nCWIKa2zg .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-NdgEXC9nCWIKa2zg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-NdgEXC9nCWIKa2zg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-NdgEXC9nCWIKa2zg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-NdgEXC9nCWIKa2zg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster text{fill:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg .cluster span{color:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-NdgEXC9nCWIKa2zg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-NdgEXC9nCWIKa2zg rect.text{fill:none;stroke-width:0;}#mermaid-svg-NdgEXC9nCWIKa2zg .icon-shape,#mermaid-svg-NdgEXC9nCWIKa2zg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-NdgEXC9nCWIKa2zg .icon-shape p,#mermaid-svg-NdgEXC9nCWIKa2zg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-NdgEXC9nCWIKa2zg .icon-shape .label rect,#mermaid-svg-NdgEXC9nCWIKa2zg .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-NdgEXC9nCWIKa2zg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-NdgEXC9nCWIKa2zg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-NdgEXC9nCWIKa2zg :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
热加载方案
工具实现
工具注册中心
意图匹配
查询
返回匹配工具
调用
调用
调用
动态注册
远程调用
工具管理器
注册表
工具Aname/desc/schema/execute
工具Bname/desc/schema/execute
工具Cname/desc/schema/execute
插件目录监听watchdog
独立工具服务gRPC
Agent
一个好的 Agent 架构，应该能在不修改核心代码的情况下，随时添加新工具。
工业界通用的设计是注册中心模式：
- 每个工具实现统一的接口：name、description、input_schema、execute 方法
- 启动时动态扫描并注册到工具管理器
- 用配置文件驱动工具列表，Agent 根据用户意图从注册表中匹配工具
如果需要支持工具的热加载（不重启服务），可以用两种方案：
- 插件目录监听：用 watchdog 监控插件目录，有新文件自动加载
- 独立工具服务：用 gRPC 调用独立的工具服务，工具服务可以独立升级
现在 MCP（模型上下文协议）已经成为了工具标准化的事实标准。它定义了统一的 tool schema 和通信协议，一个工具写好之后，所有主流 Agent 框架都能直接调用。
参考资料：
- MCP 官方文档：模型上下文协议
- Anthropic：MCP 协议设计理念
二、复杂项目的边界治理：解决 90% 生产问题的关键
当你的 Agent 从单任务 demo 变成复杂的多模块系统时，会遇到很多基础能力覆盖不到的问题。这些问题才是真正区分玩具和生产系统的关键。
2.1 多 Agent 决策冲突：谁来当最终的裁判
多 Agent 系统的决策冲突需要分层治理，下面是三层冲突解决机制的完整流程：
#mermaid-svg-8vVoTjK83ccKVOzL{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8vVoTjK83ccKVOzL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8vVoTjK83ccKVOzL .error-icon{fill:#552222;}#mermaid-svg-8vVoTjK83ccKVOzL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8vVoTjK83ccKVOzL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8vVoTjK83ccKVOzL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8vVoTjK83ccKVOzL .marker.cross{stroke:#333333;}#mermaid-svg-8vVoTjK83ccKVOzL svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8vVoTjK83ccKVOzL p{margin:0;}#mermaid-svg-8vVoTjK83ccKVOzL .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-8vVoTjK83ccKVOzL .cluster-label text{fill:#333;}#mermaid-svg-8vVoTjK83ccKVOzL .cluster-label span{color:#333;}#mermaid-svg-8vVoTjK83ccKVOzL .cluster-label span p{background-color:transparent;}#mermaid-svg-8vVoTjK83ccKVOzL .label text,#mermaid-svg-8vVoTjK83ccKVOzL span{fill:#333;color:#333;}#mermaid-svg-8vVoTjK83ccKVOzL .node rect,#mermaid-svg-8vVoTjK83ccKVOzL .node circle,#mermaid-svg-8vVoTjK83ccKVOzL .node ellipse,#mermaid-svg-8vVoTjK83ccKVOzL .node polygon,#mermaid-svg-8vVoTjK83ccKVOzL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-8vVoTjK83ccKVOzL .rough-node .label text,#mermaid-svg-8vVoTjK83ccKVOzL .node .label text,#mermaid-svg-8vVoTjK83ccKVOzL .image-shape .label,#mermaid-svg-8vVoTjK83ccKVOzL .icon-shape .label{text-anchor:middle;}#mermaid-svg-8vVoTjK83ccKVOzL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-8vVoTjK83ccKVOzL .rough-node .label,#mermaid-svg-8vVoTjK83ccKVOzL .node .label,#mermaid-svg-8vVoTjK83ccKVOzL .image-shape .label,#mermaid-svg-8vVoTjK83ccKVOzL .icon-shape .label{text-align:center;}#mermaid-svg-8vVoTjK83ccKVOzL .node.clickable{cursor:pointer;}#mermaid-svg-8vVoTjK83ccKVOzL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-8vVoTjK83ccKVOzL .arrowheadPath{fill:#333333;}#mermaid-svg-8vVoTjK83ccKVOzL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-8vVoTjK83ccKVOzL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-8vVoTjK83ccKVOzL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8vVoTjK83ccKVOzL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-8vVoTjK83ccKVOzL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8vVoTjK83ccKVOzL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-8vVoTjK83ccKVOzL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-8vVoTjK83ccKVOzL .cluster text{fill:#333;}#mermaid-svg-8vVoTjK83ccKVOzL .cluster span{color:#333;}#mermaid-svg-8vVoTjK83ccKVOzL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-8vVoTjK83ccKVOzL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-8vVoTjK83ccKVOzL rect.text{fill:none;stroke-width:0;}#mermaid-svg-8vVoTjK83ccKVOzL .icon-shape,#mermaid-svg-8vVoTjK83ccKVOzL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8vVoTjK83ccKVOzL .icon-shape p,#mermaid-svg-8vVoTjK83ccKVOzL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-8vVoTjK83ccKVOzL .icon-shape .label rect,#mermaid-svg-8vVoTjK83ccKVOzL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8vVoTjK83ccKVOzL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-8vVoTjK83ccKVOzL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-8vVoTjK83ccKVOzL :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
未违背
违背
匹配
不匹配
能判断
无法判断
需要
不需要
子 Agent 输出
共享上下文约束是否违背主 Agent 决策?
正常执行
冲突检测规则是否匹配已知冲突模式?
暂停执行标记冲突类型
仲裁 Agent能否判断谁对谁错?
执行仲裁结果
降级为人工确认
人工复核?
多 Agent 系统最大的问题就是决策冲突。比如一个负责设计的 Agent 说用 Redis 缓存，一个负责实现的 Agent 却直接用数据库查询，最后产出的代码完全不对。
解决冲突的三层方案：
记住一个原则：所有自动化决策都要有人类介入的出口。没有任何 AI 系统能做到 100% 正确，最终的兜底永远是人。
2.2 知识库治理：过期错误的知识比没有知识更可怕
这是一个坑。举例：规则库里有一条“禁止使用 async/await”，那是两年前的技术决策，后来已经废弃了。但 AI 依然严格遵守这条规则，生成的代码全是回调风格，被 Code Review 打回了无数次。
知识库治理的核心是建立完整的生命周期：
- 版本标记：每条规则带生效时间范围和版本号，AI 会检查规则是否适配当前代码库基线
- 优先级划分：明确区分“必须遵守的强制规则”和“仅供参考的经验建议”，规则的优先级永远高于 RAG 检索结果
- 反馈闭环：当开发者发现 AI 遵守了错误规则时，可以一键“报告规则错误”，触发审核流程
- 规则健康度评分：统计每条规则被 AI 遵循的次数和被人纠正的次数，得分过低的规则自动降级或删除
2.3 大型存量项目适配：如何让 AI 看懂几十万行代码
在一个几十万行的存量项目里，AI 最大的问题就是“看不懂全局”。它只能看到你给它的那几个文件，做出的决策往往是局部最优但全局错误。
我们的解决方案是：
2.4 代码生成的质量与安全：别让 AI 好心办坏事
AI 生成的代码看起来很完美，但实际上藏着很多坑。我们统计过，AI 生成代码的平均采纳率只有 50% 左右，剩下的问题主要分布在：
- 30%：逻辑正确但不符合业务隐含约束
- 20%：使用了已废弃的 API 或过时的写法
- 15%：性能问题（比如 N+1 查询、没有加索引）
- 15%：代码风格不一致
- 20%：完全错误的幻觉代码
为了控制代码生成的质量和安全，可以做两层防护：
参考资料：
- OpenAI 官方指南：提高代码生成质量的最佳实践
三、生产环境 Agent 落地的 3 条核心原则
最后，总结一下我认为最重要的三条原则，只要遵守这三条，就能避开 80% 的坑。
1. 容错优先：假设每一步都会出错
永远不要相信大模型的输出。假设模型会输出错误格式、会幻觉、会死循环、会调用错误的工具。在每一个环节都设计容错机制，多层防御。
2. 边界清晰：明确哪些事 AI 能做，哪些事必须人来做
不要试图让 AI 解决所有问题。对于高风险、高复杂度的场景，一定要有人工介入的环节。AI 的定位是辅助人类，而不是替代人类。 
3. 数据驱动：所有优化都要有可量化的指标支撑
不要仅凭感觉说“我的 Agent 效果很好”。一定要建立可量化的指标体系：成功率、留用率、响应时间、成本。所有的优化都要围绕这些指标展开。
Agent 技术发展到今天，已经不是一个概念了。但从 demo 到生产，还有很长的路要走。希望这篇文章能帮你少踩一些坑，让你的 Agent 真正跑起来。
