1. 先想清楚一件事：Prompt 写得好，不等于系统做得好
聊到 AI / Agent 系统架构，我想先从很多团队都会踩的一个认知误区说起。过去两年我见过不少项目组，前脚刚用 Prompt Engineering 调出一个表现不错的原型，后脚就急着把它包装成"Agent 系统"推向生产环境。结果呢？ Demo 阶段跑得风生水起，一旦进入多用户、长流程、真实业务数据的场景，问题层层冒出来：上下文越堆越乱、工具调用偶尔失灵、同一个问题换个说法结果就翻车、费用账单更是像坐过山车。
问题出在哪？不是 Prompt 写得不够好，而是大家把"单次对话质量"和"系统级可靠性"混为一谈了。
Prompt 解决的核心问题是：在给定一次输入输出的窗口内，让模型尽可能理解你的意图并给出合适的回答。它的优化对象是"单轮交互质量"。但一个真正可用的 Agent 系统，要面对的是连续多轮的任务推进、外部工具的状态协调、业务规则的硬约束、以及长时间运行下的成本和风险控制。这些已经不是"把话说明白"能覆盖的范围，而是典型的系统工程问题。
打个比方。Prompt 写得好，相当于你招了一个聪明的新人，你能把任务交代得清清楚楚。但你要建的 Agent 系统，相当于围绕这个新人搭建一整套协作机制：给他配什么工具、有什么权限、跟其他角色怎么对接、出错以后怎么追责修正、干到一半卡住了找谁决策。同一个聪明人，放在不同机制里，产出可以是天壤之别。于是就有了这个标题：从 Prompt 到系统工程。这中间的每一步，都有很多架构层面的取舍和设计要点，我把自己的实践经验拆开讲一讲。
2. 拆开 Agent 系统：五个必须想清楚的核心层
一个 Agent 系统从功能模块上看，通常绕不开模型层、编排层、工具层、记忆层、安全层。很多项目初期只盯着模型层选型，把后面四个全当成"以后再说"，结果后期返工成本极高。我习惯的做法是一开始就建立一个分层思考框架，哪怕细节还没定，至少每个层都要有人认领、有明确的问题清单。
2.1 模型层：选型不是越大越好，是匹配度优先
模型层是 Agent 系统的推理引擎，但"选最强模型"在工程上往往是错的。真正要考虑的是任务的复杂度分布和成本结构。
以一个客服场景举例：80% 的请求是"订单查询""退换货政策说明"这类标准化问题，真正需要深度推理的只有那 20%。如果一律上最贵的大参数模型，单次调用成本可能是轻量模型的 5 到 10 倍，延迟还会高出不少。更合理的架构是给系统接一个路由层，先由轻量模型做意图识别和问题分类，再决定哪些请求需要交给更强大的模型处理。这种做法业内叫"级联架构"或"混合路由"，本质是把钱花在刀刃上。
此外还有个容易忽略的点：模型能力边界不是静态的。同一个模型，在长上下文场景下的表现可能远不如短上下文时稳定。我实测过不少模型，上下文堆到接近上限时，模型对中段信息的"记忆力"会明显衰减，延迟和成本也跟着涨。所以在模型层就要规划好"上下文压缩策略"，而不是把一切希望寄托在扩展上下文窗口上。
2.2 编排层：决定系统是"工具人"还是"指挥官"
编排层管的是任务怎么拆分、步骤怎么衔接、决策权怎么分配。这个层级的架构选择，直接影响系统的行为模式和可维护性。
单 Agent 架构适合目标明确、步骤相对固定的任务。假设你做一个"会议纪要整理助手"，工作流基本是：录音转文字、抽取议题、生成待办事项、输出格式化成邮件。每个环节都可以由同一个 Agent 顺序执行，不需要复杂的角色间通信。这种设计的好处是链路短、调试直接、幻觉空间小，对大多数工具型应用来说已经足够。
但这个世界的另一面是链路长了之后会"贪多嚼不烂"。一个 Agent 同时负责理解用户意图、调用多个工具、维护多轮记忆、又要做结果校验，它的上下文和注意力会被严重稀释。多 Agent 架构就是把一个大而全的角色拆成几个有明确分工的小角色，比如一个"规划者"负责拆任务，几个"执行者"分别负责查资料、读代码、写文案，再来一个"审阅者"负责把关。角色分开了，Prompt 可以写得更聚焦，也更容易对单个角色做针对性调优。
我见过不少团队在单 Agent 还没跑通的情况下就硬上多 Agent，结果角色与角色之间互相等结果、上下文反复传递，代价成倍涨。经验是先让单 Agent 把流程串起来，监控一下瓶颈究竟出在哪一步，如果确实发现一个 Prompt 里塞了太多职责导致表现不稳定，再考虑拆分。多 Agent 是手段不是目的，任何架构决策都应该基于可测量的收益。
2.3 工具层：把"会说话"变成"会做事"的关键一跳
工具层是 Agent 系统区别于普通问答应用的核心。没有工具的 Agent 只是聊天机器人，有了工具的 Agent 才有手有脚。
设计工具层时有几个容易翻车的细节。第一是工具的描述要写到"让模型一看就懂怎么用"的程度，描述含糊可能导致模型乱调用。第二是工具的输入输出最好做一层标准化封装，避免模型与底层系统强耦合。第三是工具调用的失败路径必须设计好，模型调工具失败了之后是重试、换工具还是求助人工，这个决策逻辑必须在编排层写清楚。
具体描述和质量控制，我放到下一章讲实操时展开。这里只强调一个原则：工具层是 Agent 系统的"手"，但这双手能不能干好活，取决于你的编排层给它下的指令是否清晰，指令清晰的基础则是工具接口本身设计得是否规整。
2.4 记忆层：短记忆管上下文，长记忆管个性化
没有记忆的 Agent 是"金鱼"，聊完就忘。但在系统里设计记忆，比很多人想象的要复杂。
我在项目里一般把记忆分成两层：短期记忆和长期记忆。短期记忆就是当前会话的上下文，它直接决定模型"现在"能否理解对话脉络。短期记忆的管理核心是"动态裁剪"，不能让上下文无限堆积，否则成本和性能都会雪崩。常用的做法是做摘要——当会话太长时，先把前面的内容压缩成一段摘要，再继续往后聊。还有一种方式是滑动窗口，只保留最近 N 轮对话，更早的内容丢弃。摘要方案更聪明但可能丢细节，滑动窗口简单但可能切断关键信息，实践中往往会两者结合。
长期记忆对应的是跨会话的信息沉淀，比如用户的偏好、历史订单、项目背景。这部分早期我建议不要存自由文本，而是先结构化，例如存在数据库里字段化。当模型需要的时候再去检索，而不是一股脑全塞进上下文。这里又会牵扯出检索质量的问题，一块展开讲。
2.5 安全层：上线前不做这几件事，迟早会出事
安全层最容易被原型阶段忽略，却是生产环境里最要命的短板。
至少三件事必须做：一是权限隔离，Agent 能调用的工具权限，必须跟用户本身的权限一致，否则会出现越权操作的风险；二是输入校验，用户输入的内容不能直接作为指令拼接进工具调用逻辑里，必须做一层过滤和参数校验；三是审计日志，Agent 做了哪些动作、调用了哪些工具、结果是什么，全部留痕。这不仅是合规问题，更是排查线上问题的救命线索。
3. 从零搭建一个 Demo：完整落地路径拆解
理论讲完，上一段实操。我拿一个很典型的需求来走全程：企业内部知识库问答助手。目标是从一个只有 Prompt 的聊天界面，演进成一个有检索能力、有用户记忆、有权限控制的小型 Agent 系统。
3.1 先拆需求，别急着写 Prompt
很多人拿到这个需求就开始写提示词，我觉得顺序反了。第一步是拆解功能需求和约束条件。
我问自己四个问题：用户每天大概会问什么类型的问题？哪些问题需要调用文档数据库，哪些问题只需要模型常识？回答错了会有什么后果？用户对响应延迟的容忍度是多少？
拆完以后，把问题的类型清单一列，发现真正的需求是"准确检索 + 可控生成"，而不是"让模型自由发挥"。这个结论直接决定了后续的技术选型：需要一套检索组件，而不是只靠模型生成。
3.2 搭建最小链路：检索增强生成
然后是最小闭环。内部知识库的场景，先做一个最简单的检索增强生成链路：用户提问 → 在知识库里检索相关文档片段 → 把片段拼到 Prompt 里 → 模型基于片段回答。
这一步有个关键参数：检索回 Top K 条。K 太小，可能漏掉关键信息；K 太大，无关片段反而干扰模型。我一般从 K=4 开始调，然后观察回答质量，结合实际问答测试集来回调整。这里引入一个很实用的经验：不要单纯看"相关性"，还要看"信息冗余度"。如果回回来的片段内容高度重复，其实只需要保留一条，剩下名额可以给其他不同角度的信息，这样能在有限上下文里看到更多方面。
这个阶段跑通后，一个"能回答问题"的聊天机器人就出来了。但离"系统"还很远，因为检索质量可能不稳定，也没有用户和权限概念。
3.3 加上工具层：给 Agent 装上"手"
接下来的演进，是把搜索和查询变成可调用的工具，而不是靠写死在 Prompt 里的逻辑。这一步的关键是标准化的函数调用接口。
我习惯把所有工具定义成统一的函数签名：名称、功能描述、参数列表、输出格式。以"搜索文档"为例，功能描述要写清楚适合什么场景、不适合什么场景，参数要标明"关键词"和"过滤条件"，返回结果的结构也要固定。
工具定义好后，再在编排逻辑里加一个"工具路由"的环节：模型先判断是否需要调用工具、调用哪个工具、传什么参数。这个过程其实是一个结构化输出，需要把模型的输出约束为 JSON 格式来做。
这一步做完以后，整个系统的能力边界就变了：不再是"模型知道什么就答什么"，而是"模型知道怎么找到答案就答什么"。不过能力边界扩大也意味着失误半径变大，所以下一步必须把评估机制建起来。
3.4 加入记忆能力：从"工具人"到"有记忆的助手"
给这个助手加上跨会话的长期记忆时，我没有做复杂的向量记忆库，而是先用了一个非常朴素的方式：在数据库里建了一张用户偏好表，记录用户的部门、常用业务线、喜欢简洁还是详细回答等标签。
这样做的理由很简单——在数据量小时，结构化的标签检索比向量相似度检索的准确性高得多，而且逻辑透明，调试容易。等数据量增长到一定规模，再引入向量检索来补充语义层面的匹配。
短期记忆的维护方式则是靠上下文裁剪加摘要。我设定了一个阈值：当会话轮次超过 8 轮，就把前几轮的关键信息浓缩成一段摘要，替换掉原始消息，确保上下文窗口里有足够空间容纳新的交互。
3.5 设计兜底策略：回答不了怎么办
系统做出来以后一定会遇到模型不知道的问题。我的建议是给 Agent 一个明确的"认怂"行为：当检索结果明显不相关、或模型对多个矛盾信息无法判断时，要求它明确回答"这个问题需要进一步确认"，并行地触发人工客服转接。
这个设计看着简单，但特别重要。因为它本质上是在给系统设置"行为边界"，减少模型一本正经地给你编答案。我见到太多系统老板汇报时滔滔不绝，但你问一个超出边界的问题，它就给你编一个头头是道的答案，这种错误的后果往往比"不知道"要严重得多。
3.6 上线初期的灰度策略
灰度策略也是从原型到系统的必经一步。不要一上来就把系统开放给全员，先在内部小范围跑两周。灰度期间要收集两类数据：一类是用户真实问题记录，另一类是回答的反馈数据（顶/踩）。这两类数据决定了后续优化方向——你会很直观地发现最常被问的问题是什么、回答最容易被用户否定的场景是什么。
我自己经常在灰度期发现"计划外需求"。比如这个知识库助手，原本以为用户只会搜索标准文档，实际跑起来发现还有大量"问流程、问接口规范"的需求，这又牵引出新的工具接入。
4. 常见问题与排查经验实录
最后把几个实战中高频踩坑的场景和排查思路整理一下，都是些常规文档里不会写的东西。
4.1 模型"幻觉"集中在什么时候爆发
模型的幻觉不是一个均匀分布的现象，它有明显的"高发地带"：当检索到的文档片段互相矛盾、或者文档信息隐匿在表格和长文件里、或者用户问题中夹带了未被索引的专有名词时，模型特别容易自行补全一个看似合理的答案。
排查的方向通常先看引用来源。让系统回答时附带上参考文档及其片段，一旦发现模型输出里没有支持它的"证据链"，那基本就是幻觉。解决办法不是单纯地加一句"没有依据不要乱说"，而是调整检索逻辑，确保喂给模型的上下文里确实包含了能支撑正确回答的信息。
4.2 上下文"越用越衰"问题
不少系统在使用一段时间后，回答质量出现显著下滑，这个现象在实践中非常普遍。我跟过的团队里有几个案例，在线效果大跳水，查半天发现根因各不相同。
有一种情况是短期记忆堆积导致的，会话太长，模型已经在上下文中"迷路"了。优化方式就是做摘要裁剪。另一种情况是检索到了重复信息挤掉了关键信息，这跟 Top K 选择和去重策略有关。第三种情况是工具调用过程中的历史消息也被一股脑留在了上下文里，这些过程性内容（比如 JSON 调用记录）不仅没有提供有效信息，还严重干扰了模型对对话脉络的理解。
解决第三种情况有个技巧：记忆系统不要存储"原始流水账"，而要存储"经过提炼的对话状态"。每次工具调用结束后，把结果摘要成一句话再存入记忆，而不是把完整的工具响应原样塞进上下文。
4.3 工具"调用了但没用"怎么办
模型正确地调用了工具，也返回了正确结果，但最终回答依然出错。这种事简直就是工程噩梦，我排了不少次，总结出三个主要方向：
首先，模型把工具返回信息理解错了。可能是返回结构太复杂，模型在解析时出了问题。对策是把工具返回的内容做预处理，先压缩成干净的自然语言摘要，再交给模型。这也是前面提到的"工具层标准化"的一个实际好处。其次，模型只用了返回信息的一部分，忽略了其他关键字段。这个通常要靠 Prompt 里的输出要求约束它"必须基于完整结果作答"。最后，工具返回本身的时效性问题，比如信息已经过期，模型又无从判断。对策是在工具返回里附带数据更新时间戳，并在 Prompt 里要求模型对过期信息作出免责说明。
4.4 多 Agent 系统效率反而下降
多 Agent 系统并不是一定能提升效率。我试过用两个 Agent 分工，一个写代码一个查文档，结果经常互相等：写代码的 Agent 等文档结果，查文档的 Agent 又不确定该查什么，最后整个链路比单 Agent 慢了几倍。
后来排查发现，问题出在"任务传递"环节——两个 Agent 之间的对话内容没有结构化，信息散落在自然语言里，彼此理解经常走偏。重新设计之后，把 Agent 之间的通信改成固定格式的任务单：目标、输入、约束、输出格式，情况立刻好了很多。
这个经验给到一个判断标准：如果你的 Agent 之间传递的信息高度结构化，就拆分；如果大量依赖模糊的自然语言来协作，那就不拆，先聚焦单 Agent 的流程优化。
注意：记住一个最基本的经验——Agent 系统的复杂度增长远比你想象中快。每多一个工具、多一层记忆、多一个角色，都要给系统留出足够的调试窗口和灰度期，系统性、渐进式地演进，往往比一步到位稳得多。
4.5 成本失控的成本归属，到底该怎么算
成本失控也是个典型问题，尤其是在生产环境里。最隐蔽的坑是"重试链"导致的成本翻倍。模型调用失败一次，Agent 会自动重试，每次重试都会重新发送前面的上下文。如果一个环节失败率高，重试链会把成本放大到让账单触目惊心的程度。对策是设置重试上限，以及在重试时考虑精简上下文，不要让失败的请求反复用相同的大上下文消耗资源。
5. 关于"人机协同"的最后一公里的经验
把技术框架聊完，最后说一个我自己的体会。Agent 系统做出来之后，团队里经常出现两种极端：一种是把系统说得神乎其神，什么都能干；另一种是觉得系统太蠢，什么都不敢让它干。这两种心态其实都偏离了"系统工程"本来的含义。
真正的系统工程，是在人类操作者和 Agent 系统之间找到一条清晰的分界线：哪些环节适合自动化、哪些环节必须留给人来决策，这条线要画得明明白白。画线的依据，不是"技术上能不能实现"，而是"出错了能不能兜底、代价有多大"。
我在实际项目中，最深的感受就是这个系统的边界是"试"出来的，不是"设计"出来的。先在低风险场景里放开让它跑，把你以为的系统边界验证一遍，再根据反馈逐步调整那条线。这条边界稳定之后，这个 Agent 系统才真正从一个 Demo 变成了一个可用、可控、可维护的工程系统。
