1. 为什么五层架构比一堆新名词更适合解释今天的 Agent 产业前阵子帮一个团队做 Agent 项目的架构评审会议室白板上密密麻麻写了十几行字Skill、Harness、MCP、Evals、Memory、Router、Multi-Agent……写的人自己都笑了说这半年冒出来的新词比过去三年加起来还多。更麻烦的是同一个词在不同人口中意思完全不一样——有人说的Agent其实是一个写死的工作流有人说的 Skill 其实就是一次函数调用还有人把 Harness 当成框架的同义词。这种混乱在招人面试、架构评审、技术选型时都会真实地卡住进度你没法用一套对不齐的语言讨论一个系统该不该重构。所以我想用一个坐标系把这件事钉死把今天 Agent 的技术栈按五层架构拆开每一层负责什么、有哪些代表概念、最容易踩的坑在哪。架构理顺之后那些到处飘的名词会自己归位——你会发现它们不是竞争关系而是分布在不同的层上各管一段。这份图谱我按自己的项目经验整理也参考了社区里反复被讨论的那些高频问题尽量做到可以直接拿去对照自己手上的项目。1.1 从能跑通到能上线中间到底缺了什么绝大多数 Agent 项目的第一个版本都很顺。三五百行提示词两三个工具本地跑一遍效果惊艳团队群里一片这个能落地。然后到了真上线问题成批出现并发一上来超时率飙升、成本比预算高出好几倍、模型开始编造工具返回的数据、任务跑到第五步突然不知道自己为什么在这里、失败之后没有痕迹可以复盘。我印象最深的是一次周报总结 Agent 的翻车。本地测试时它表现完美上线后第一个周一早上同时涌入两百个任务结果三个问题同时爆发一是上下文里塞了整份季度数据单次调用 token 量是测试环境的八倍二是工具返回的错误信息是一整段堆栈模型读完之后开始自行发挥把失败当成成功汇报三是没有任何检查点任务跑一半中断之后只能从头再来。这三个问题没有一个是模型能力问题全部出在模型之外的工程层。这就是为什么换个更强的模型往往解决不了问题。模型能力是上限而上面这些坑决定的是下限。一个下限很低的系统换个再强的模型也只是把天花板抬高一点地板还在原地。1.2 五层的划分依据按责任边界而不是按产品形态市面上的分层图很多但大部分是按厂商产品切的看着热闹用起来对不上号。我更倾向于按责任边界来切每一层只回答一个问题并且出问题时症状明显不同。层级核心职责典型产出物出错时最先看到的症状第一层 模型与推理层理解意图、做规划、产出结构化结果提示模板、模型路由策略、推理预算配置答非所问、格式错乱、规划长度不够第二层 上下文与记忆层决定模型每一步看到什么记忆存储、压缩策略、检索逻辑前后矛盾、忘记约束、越到后面越跑偏第三层 工具与技能层与外部世界发生真实交互工具定义、参数校验、权限配置调用失败、参数传错、越权操作第四层 编排与协作层控制流程走向与多体协作状态机、路由节点、检查点死循环、卡死、任务半路终止第五层 交互与交付层面向用户的入口与反馈回路界面、流式输出、审计日志体验割裂、出问题无法追溯横着切完还要竖着切一刀Evals评测、安全、成本、可观测性这四个横切关注点不属于任何单层但每一层都必须接进去。很多项目失败不是因为某一层做错了而是这四个横切面一个都没做——系统跑起来像黑箱出事只能靠猜。2. 第一层模型与推理层——换更强的模型通常不是最优解2.1 推理层实际要解决的三个问题把模型层想成大脑但它其实同时干三件不同的事这三件事对模型能力的要求完全不同。第一件事是意图理解与消歧。用户说帮我把上季度没结的账清一下这句话里有至少四个歧义点上季度是自然季度还是财季、没结的是应收还是应付、清一下是核销还是催收、涉及哪些主体。人类同事会反问Agent 要么反问要么把歧义显式写进计划里。这一步的失败率通常被低估因为 Demo 时用户总是用最标准的方式描述需求。第二件事是长程规划。任务超过五步之后很多模型会丢失原始目标开始就近决策——只盯着眼前这一步把整体目标忘了。表现出来就是任务前半段很聪明后半段莫名其妙。解决方向一是把计划显式落盘写成待办清单持续注入上下文二是减少单次任务的步数上限把长任务切成几个短任务。第三件事是结构化输出。工具调用本质上要求模型输出符合约定的结构JSON Schema 约束、字段类型、必填项、枚举值一个都不能错。这一步的稳定性跟模型规模关系不大跟约束方式和校验层关系更大。2.2 选型取舍大模型管决策小模型管手脚我见过最常见的一种浪费就是用最强的模型做所有事情——包括意图分类、参数抽取、路由判断这些根本不需要它出场的活。合理的做法是按子任务拆开子任务建议档位核心理由意图分类、路由分发小模型或规则引擎类别有限、延迟敏感规则覆盖八成场景复杂任务规划强推理模型长链条一致性要求最高这里不能省工具参数生成中等模型 强 Schema 约束有校验层兜底容错空间大最终交付文本强生成模型或人工终审直接面向用户质量和语气都要撑住实测经验是把路由判断和参数生成下沉到小模型之后端到端成本能降到原来的四成左右任务成功率基本没变。但这个结论有一个前提——你得先有评测集。没有评测集的情况下任何降本都是在赌运气你根本不知道成功率有没有掉。提示推理预算reasoning effort 或 thinking budget是这一层最容易被忽略的旋钮。简单任务开高预算等于花钱买延迟复杂规划开低预算等于让模型裸奔。按子任务分别配置比全局调一个值靠谱得多。3. 第二层上下文与记忆层——决定 Agent 能不能连续干活3.1 上下文工程和记忆系统不是同一件事很多人把这两个概念混着用其实它们一个管组装一个管沉淀。上下文工程关心的是这一次调用模型眼前应该摆什么。它是一个实时决策问题——从系统提示、工具定义、历史消息、检索结果、任务状态里挑出最相关的那部分拼成一个不超过有效容量的输入。记忆系统关心的是什么东西值得长期留下下次还能用上。它是一个存储与召回问题涉及写入时机、去重、过期、检索排序。一个直观的类比上下文工程是你每天早上出门前决定往包里装什么记忆系统是你的储物柜。包是有限的柜子可以很大但柜子里的东西不会自动进包——你得有一套判断标准决定拿哪些。还有一个反直觉的事实上下文窗口的标称容量和有效容量是两回事。窗口开到一百万 token不代表塞满一百万还能保持质量。信息密度低的内容塞进去不只是浪费钱还会稀释真正重要的指令。业内经常提到的中间遗忘现象说的就是关键信息落在长上下文中段时被模型注意到的概率会明显下降。3.2 四类记忆的落地方式记忆类型存什么常见存储形态写入时机短期记忆当前会话的对话与中间结果会话缓冲、滑动窗口每轮对话自动追加情景记忆过去发生过什么、结果如何事件日志、带时间戳的记录任务结束或关键节点语义记忆稳定的事实、偏好、规则结构化表、向量库、知识图谱用户明确告知或多次确认后程序性记忆某类任务该怎么做技能文件、流程模板、示例集人工沉淀不建议自动写入这四类里最容易出问题的是语义记忆的自动写入。我踩过一次坑让 Agent 自动把对话中提取的用户偏好写进长期记忆结果它把用户的一句吐槽这个方案太慢了当成偏好存了下来之后所有相关建议都往这个方向偏。后来改成两级机制——自动提取只做候选写入前需要置信度判断或者人工确认误写率降下来一大截。程序性记忆是最被低估的一块。把做这类任务的标准步骤写成可复用的技能文件让 Agent 按需加载比每次靠提示词临场发挥稳定得多。这也是后面要讲的 Skill 概念的核心价值。3.3 上下文腐化的识别信号与处理动作上下文腐化context rot不是抽象概念它有非常具体的表现。我一般用这几个信号判断越到后面越跑偏任务开头表现正常第 N 步开始偏离原始目标且没有明显触发事件。改一句话后面全乱调整一个无关紧要的措辞导致下游行为大幅变化说明上下文里塞了太多互相干扰的信息。重复调用同一个工具模型忘了自己已经调用过说明中间结果没有被有效压缩或标注。约束被遗忘系统提示里明确写了金额单位统一用元跑到第七步开始出现万元。对应的处理动作按性价比排序先把系统提示里最重要的约束挪到末尾重复一遍再把冗长的历史消息做分段摘要只保留结论和关键数据然后检查工具定义是不是塞了太多用不上的工具描述把工具数量控制在十几到二十个以内超了就做工具检索或分组加载最后才是考虑换更长的窗口。注意压缩上下文的时候一定要把任务成功的关键状态单独拎出来做结构化保存——比如当前进度、已确认的事实、待办清单。这些不能交给摘要模型自由发挥必须自己控制字段。4. 第三层工具与技能层——Tool、Skill、Function Calling 的边界4.1 三个词的正确定位这三个概念被混用得最厉害其实它们处在不同层面Function Calling是模型侧的一项协议能力模型输出一个结构化的调用意图声明我要调用哪个函数、传什么参数仅此而已。它不负责真正执行。Tool是真实存在的可执行接口一个 HTTP 接口、一段脚本、一次数据库查询。它被调用之后返回结果结果再被塞回上下文交给模型。Skill是面向任务的能力封装包通常包含指令说明、脚本、参考文档、示例按需加载。一个 Skill 内部可能编排多个 Tool也可能什么都不调用只是一套做事的方法论。所以它们的关系是Skill 定义这类任务怎么做Tool 定义能操作什么Function Calling 是模型怎么表达要操作什么。理解了这个层次很多争论就自动消失了——比如Skill 和 Agent 的区别本质是粒度问题Skill 是被调用的能力单元Agent 是有目标、有循环、能自主决策的执行主体。4.2 渐进式披露与工具规模控制工具一多选择准确率就会掉。这不是模型笨是候选集变大了每次选择都在做多分类问题。我们做过一次统计工具数从 8 个涨到 30 个选择正确率明显下滑且错误集中在描述相近的工具之间。解决办法有三条。第一条是分组与命名收敛。把功能相近的工具做合并比如查询订单和查询订单详情合成一个带参数的工具而不是两个并列选项。第二条是渐进式披露。默认只给模型看技能目录和一句话描述模型判断需要某个技能时再加载完整内容。这一招对提示词长度的压缩效果非常明显也降低了无关信息干扰。第三条是工具检索。工具规模超过几十个之后先做一轮检索把候选缩到十个以内再让模型选择。实现上就是在工具描述上建索引按当前任务做召回。4.3 工具设计里最容易翻车的五个点翻车点表现修正做法工具描述写给人看模型的调用参数经常传错描述里明确写清什么场景调用、参数含义、返回什么错误信息原样返回模型把失败当成功或开始编造返回结构化错误错误类型、可读原因、建议动作缺少幂等设计重试导致重复下单、重复发送引入幂等键写操作必须可安全重试权限给得过大一个查询工具能改数据按最小权限拆分读写危险操作强制人工确认工具粒度太细完成一个任务要调十几次工具按任务动作而不是接口来切分工具最后一条特别值得说。很多团队直接把后端接口一比一暴露成工具结果 Agent 完成一件小事要串五六次调用步数暴涨、失败率叠加。更好的做法是按业务动作封装——比如为用户办理退款是一个工具内部自己去调三四个接口。工具少一点、粗一点通常比多而细更稳。5. 第四层编排与协作层——单 Agent 能解决就别上多 Agent5.1 三个基本编排骨架不管用哪个框架编排骨架基本就三种其他都是组合。链式是最简单的步骤固定顺序执行。固定流程的业务比如读文件→提取字段→写入表格用链式就够了可控性最高成本最低。这类系统我更愿意叫它Agentic Workflow而不是 Agent——它有明确路径没有自主决策。路由式是在入口加一个分发节点先判断这是什么类型的请求再走对应的子流程。这个分发节点就是常说的路由识别节点。它的设计要点有两个一是分类类别别太多超过七八类就容易混二是必须有一个兜底分支判不准的时候走到澄清或转人工而不是硬猜。路由节点的准确率是整条链路的地板这里错了后面全错。循环式才是真正意义上的 Agent模型自己决定下一步做什么直到任务完成或触发终止条件。它最灵活也最难控。两个必须做的工程动作一是设置硬性步数上限和超时二是明确终止条件包括成功终止和失败终止别让模型自己判断差不多了。5.2 多 Agent 的四种拓扑与适用边界多 Agent 协作听起来高级但我见过太多为了架构好看而上多 Agent、最后被复杂度拖死的项目。它的真实价值只在特定场景成立任务能清晰切分成相对独立的子领域且每个子领域需要不同的上下文和工具集。拓扑结构适合场景主要风险主管制一个主管 Agent 分派任务给下属任务边界清晰、需要统一收口主管上下文压力大容易成为瓶颈层级制主管下面还有子主管多级分发复杂项目、多阶段交付层级越深信息损耗越严重对等移交Agent 之间按需转移控制权客服、售前售后这类连续对话转移逻辑容易互相打转辩论制多个 Agent 给方案再裁决需要提高判断质量的关键决策成本成倍增加收益不一定覆盖我的一般建议是先做单 Agent 版本把评测集跑出来如果失败样本里明确有一类是上下文互相干扰导致或者需要互斥的权限体系再考虑拆分。拆之前先问一句能不能用同一个 Agent 加多个技能分组来解决答案通常是能。5.3 Harness 和 Agent 的区别这是我被问得最多的一个问题。Harness 是运行时外壳负责所有模型管不了但必须有人管的事主循环、工具执行、上下文裁剪、重试与超时、权限校验、错误恢复。Agent 是目标 一套 Harness 配置 一组工具与技能的组合。打个比方Harness 是发动机和变速箱Agent 是这台车配上目的地和驾驶员。同一个 Harness 可以跑出很多个不同用途的 Agent。理解了这一层换个框架这件事就没那么玄了——大多数框架提供的其实就是 Harness差异在于循环实现、上下文管理策略、以及生态集成度。还有一个相关的高频故障任务执行半路报错终止。这类问题的排查顺序我一般固定成四步先看是不是工具返回了非预期格式导致解析失败再看是不是上下文超限被截断然后看循环有没有终止条件缺失最后才怀疑模型本身。实测下来前三步能覆盖八成以上的半路终止。6. 第五层交互与交付层——用户看到的只是冰山一角6.1 四种交互形态的成本差异对话式是成本最低、落地最快的形态适合内部工具和知识问答。它的难点不在界面在流式输出和中间状态展示——一个跑三十秒的任务如果界面一动不动用户会以为卡死了。把正在检索正在调用某个工具正在生成这些状态暴露出来体验差别巨大。嵌入式是把 Agent 塞进用户已经在用的工具里比如编辑器、办公套件、工单系统。它的优势是用户不需要切换场景劣势是能力边界受宿主限制。桌面端和浏览器/计算机操作是另一档复杂度。它们要处理屏幕理解、坐标定位、页面变化、弹窗干扰。我做过的浏览器操作类任务稳定性的瓶颈几乎从来不是模型而是页面加载时序和元素定位。这种情况必须加重试、显式等待、失败截图否则线上就是随机失败。具身智能 Agent是感知—决策—执行的完整闭环涉及真实世界的空间与物理约束。它对实时性和安全冗余的要求比纯软件系统高一个量级落地节奏也慢得多。如果你在做软件类项目这部分了解一下概念就够了不需要作为架构参考。6.2 可观测性先把轨迹存下来这一层的工程重点不是界面是可追溯。我的经验是任何 Agent 项目上线前必须做到随便抽一个失败任务能在五分钟内还原它每一步看到了什么、调了什么、返回了什么。要做到这点需要记录的东西包括每轮的输入摘要与 token 消耗、每次工具调用的参数与返回值、每一步的耗时、最终结果、以及用户的后续反馈。这些数据攒起来就是最有价值的资产——失败样本直接回流到评测集比任何人工构造的测试用例都真实。提示轨迹记录要注意脱敏。工具参数里经常会带手机号、身份信息、内部数据落库之前做一层字段过滤别等出事了再补。7. 横切关注点Evals、安全与测试7.1 评测要分三层做缺一层都白搭第一层是单元级评测单个环节对不对。工具参数生成准确率、路由分类准确率、检索召回率。这一层跑得快、成本低适合放进每次提交的自动化流程。第二层是轨迹级评测不只看到没到终点还看走的路对不对。完成同一个任务A 用了三步、B 用了十二步、C 绕了个大圈还调用了不该调用的工具——成功率一样质量完全不同。轨迹评测就是把这些差异量出来。第三层是端到端评测真实任务的完成质量。这一层用人工评分或模型评分LLM-as-Judge都行但评测标准必须提前写清楚否则每次评出来的分数没有可比性。我踩过的最大一个坑是一开始只做端到端评测结果每次改动都要跑全量、等半天评测集还特别容易过拟合——团队成员不知不觉照着测试用例调提示词。后来加上单元级评测反馈速度从半天缩到几分钟迭代效率完全不同。7.2 安全威胁里最需要防的是什么Agent 安全和传统应用安全最大的区别在于它的输入是不可信的自然语言输出会触发真实操作。这带来两类核心风险。一类是提示注入。用户在输入里夹带指令试图让 Agent 忽略原有约束。间接注入更麻烦——恶意内容藏在被读取的文档、网页、邮件里Agent 读进来之后就照做了。防护思路上一是把外部内容明确标记为数据而不是指令在提示结构上做区分二是对高危操作加人工确认三是输出侧做敏感信息过滤。另一类是权限越界。Agent 拿到了超出任务需要的权限一旦判断失误就是真实损失。核心原则是最小权限加读写分离——只读任务绝不给写权限批量操作限定量级删除和支付类操作必须二次确认所有操作留审计日志。还有一类常被忽略的风险是成本失控。恶意或异常输入触发大量循环账单会很难看。给每个任务设 token 上限和步数上限是最简单也最有效的兜底。8. 40 概念避坑速查与学习路线8.1 高频混淆概念对照表概念容易混淆的点一句话定位Agent与工作流混用有目标、有循环、能自主决策的执行主体Agentic Workflow被当成 Agent路径预先确定的自动化流程可控性更高Harness被当成框架运行时外壳管循环、工具执行、上下文、权限Skill与 Tool 混用面向任务的能力包可包含多个工具和方法说明Tool与 Function Calling 混用真实可执行的接口Function Calling被当成执行模型输出的调用意图不负责执行MCP被当成框架工具与资源接入的标准化协议Context Engineering与提示工程混用决定每次调用模型看到什么Context Rot被当成窗口不足上下文变长后质量下降的现象RAG与记忆混用检索增强生成偏查资料记忆偏记住事短期记忆与上下文窗口等同当前会话内的工作集情景记忆与日志混用过去发生过什么及结果如何语义记忆与知识库混用稳定事实、偏好、规则程序性记忆常被忽略某类任务的标准做法Planning与提示词工程混用把目标拆成有序步骤ReAct被当成框架推理与行动交替的范式Reflection与重试混用对自身输出做批判并修正路由识别节点被当成可选决定请求走哪条链路的分发点状态机与工作流引擎混用显式管理状态与转移的编排方式Checkpoint被忽略中断后可恢复的进度快照HITL被当成兜底人工介入审批节点Multi-Agent被过度使用多执行体协作复杂度高Supervisor与路由混淆一种多 Agent 拓扑主管分派Handoff与调用混淆控制权的转移不是函数调用Guardrails与校验混用行为边界与拦截规则Sandbox被忽略隔离执行环境Prompt Injection与脏数据混用通过输入篡改 Agent 行为的攻击Evals被当成测试面向非确定性输出的系统化评测LLM-as-Judge被当成万能用模型评分需固定标准Trajectory Eval被忽略评测执行路径而不只是结果Observability与日志混用可追溯的完整执行链路Embodied Agent与软件 Agent 混用感知—决策—执行闭环的实体系统Browser Agent被当成简单依赖页面时序与定位稳定性难做Grounding与检索混用让输出有据可依Fine-tuning被优先考虑成本高先试提示、检索、工作流这张表我建议贴在团队文档里评审时对着看能省掉大量你说的和我说的不是一回事的争论。8.2 学习路线按层走别按名词走如果让我给一条学习路线我不会按先学框架 A 再学框架 B来排而是按层次走。第一步先搞明白模型层的基本能力边界提示结构、结构化输出、推理预算怎么调。这一步不用写复杂代码用最朴素的脚本调用就能体会。第二步动手做一个单 Agent 两三个工具的最小闭环。重点不是功能多而是把工具描述、错误返回、参数校验这三件事写扎实。这一步做完你会对模型有多容易被误导有直观感受。第三步加记忆和上下文管理。做一个需要跨会话记住事情的任务然后观察它是怎么忘、怎么错的。这一步的收获通常最大因为它暴露的是设计问题而不是编码问题。第四步上评测。给自己造二十条测试用例分单元级和端到端两层。到这里你才算真正能改进系统而不是靠感觉调。第五步才是编排和多 Agent。到这一步你会发现大部分需求根本用不到多 Agent路由加循环就够了。准备面试的话我观察下来被问得最集中的是四类Agent 和 Harness、Skill 的区别上下文超限怎么处理多 Agent 什么情况下才需要评测怎么做。这四个问题背后考的其实都是同一件事——你有没有真正把系统跑上线过、被坑过。最后分享一个我在多个项目里反复验证过的做法每次架构评审先不看代码只问三个问题——这个任务的成功标准是什么、失败样本存在哪、出问题怎么还原现场。这三个问题答不上来架构图画得再漂亮也是空中楼阁。反过来只要这三个问题答得清楚用不用多 Agent、选哪个框架都会变成不那么重要的细节。