1. 这张图谱为什么要分成五层1.1 从堆工具到看清层级的转折去年这个时候我跟几个做后端的同行聊 Agent大家的共识还是包一层提示词就能跑。到了今年再看手上的项目光是选型清单就排了三页纸编排框架、执行外壳、记忆方案、评测工具、技能注册中心每个词后面还拖着一串近义词。这张 2026 Agent 产业与技术全景图谱说白了就是在词比代码多的焦虑里逼出来的产物。真正让我下决心做结构化拆解的是一次很典型的翻车。团队里两个人分别负责两条业务线一个用技能来指代可复用的提示词模板另一个用技能来指代带参数的工具函数。评审会上我们讨论了四十分钟才发现双方说的根本不是同一个东西。那次之后我把市面上能见到的 Agent 相关术语全部拉了一张表按它在系统里承担什么职责重新归类最后收敛成五层架构。这张图能帮你做三件事选型时不再被厂商话术牵着走、排查故障时能快速定位到哪一层、面试或汇报时能把链路讲清楚。它适合刚入门的开发者、正在做技术选型的团队负责人也适合那些被各种名词绕晕的产品同学。1.2 五层划分的依据按变更频率切而不是按厂商切外行看 Agent 技术栈喜欢按公司切谁家模型、谁家框架、谁家向量库。这种切法在选型阶段就废了因为厂商会互相吞并今天做记忆的明天做编排你按厂商画出来的图半年就得重画一次。我最后选的是按变更频率切层越靠下的层越稳定越靠上的层换得越快。模型层可能一年才换代一次运行时外壳三个月就会有新的主流方案技能定义基本跟着业务走记忆策略取决于数据形态编排层则最容易因为一次需求变更就重写。这个切法的好处是当你发现某个技术方案看起来什么都能干的时候你能立刻判断它到底想往哪一层挤——而一个想同时占住三层的方案通常哪一层都做不深。另一条划分依据是故障归属。线上出问题的时候最怕的是不知道往哪查。按职责分层之后报错信息里出现的每一个词都能对应到具体某一层这一点在后面的排查章节会详细展开。1.3 先承认这张图解决不了什么我不太喜欢把架构图讲成万能药。这张五层图谱有三个明确的盲区提前说清楚比事后打补丁好。第一它不解决要不要做 Agent这个问题。有些需求用固定的流程编排反而更稳、更便宜硬上 Agent 只会让成本和不确定性一起上升。第二它不能替你做数值决策比如上下文窗口开多大、检索返回几条这些必须结合你的真实数据量去测。第三它描述的是当前这一年的主流形态明年可能有某一层被合并掉这很正常架构图本来就应该跟着产业走。2. 五层架构逐层拆解2.1 第一层模型与推理底座这一层是整个系统的发动机包含基础模型、推理服务、上下文窗口限制、工具调用协议支持能力以及最容易被忽视的输出稳定性。很多人选模型只看排行榜分数实际做 Agent 的时候分数高不等于好用因为 Agent 场景对模型的要求和单轮问答完全不同它需要模型在多轮里保持任务目标不变、需要它按结构化格式吐出参数、需要它在信息不足时主动提问而不是硬编。我在实际项目里总结出一个三看原则。看指令遵循给它三条互相冲突的约束看它会不会自行脑补看格式稳定性同一个工具定义连续调用二十次统计参数解析失败率超过百分之三就要考虑换方案或加一层校验看单位成本下的有效轮数不是看单次调用多少钱而是看完成一个真实任务总共烧掉多少。提示模型层不要过早锁定。把调用封装成一个薄适配层保留切换能力这件事的投入产出比在整个项目里排得上前三。2.2 第二层运行时与执行外壳Harness这一层是我认为最被低估的一层。Agent 和 Harness 的区别本质上就是司机和车的区别。Agent 是那个做决策的主体Harness 是承载它、约束它、给它提供工具和沙箱的那套运行环境。同样一个决策逻辑放在不同的外壳里表现可以差出好几倍。运行时外壳通常负责这些事循环控制什么时候继续、什么时候停、工具注册与调用、权限与沙箱隔离、超时与重试、日志与可观测性、以及上下文窗口的拼装。很多团队出问题就出在这里——把循环控制写在了业务代码里导致每加一个功能就要改一遍主流程。比较健康的做法是把主流程固定成一个思考、行动、观察的循环骨架业务差异全部通过工具和提示词注入。我个人的经验是外壳层的代码应该是整项目里最不愿意改的部分。如果你发现自己每周都在动循环逻辑那说明抽象层级错了业务细节漏到骨架里去了。2.3 第三层技能与工具层这一层解决的是Agent 能做什么。技能这个概念在不同语境下含义差别很大有时候它指一段可复用的提示词加知识包有时候它指一个带参数的可执行函数。我在图谱里把它统一成能力单元判断标准只有一个它是否有一个明确的输入契约和一个明确的输出契约。工具定义有三条硬规矩。名称要动宾结构search_order比order_query_helper好得多描述要写什么时候用而不是这是什么模型选工具靠的是场景匹配参数描述里要写清边界比如日期格式、枚举取值范围、必填与可选。我见过太多失败案例追到根上都是工具描述写得太含糊模型只能靠猜。2.4 第四层记忆与上下文层记忆是 Agent 从一次性工具变成长期助手的分水岭。这一层要处理的问题很具体什么信息值得存、存成什么形态、什么时候取出来、取出来多少条、冲突了怎么办。我一般把它拆成四类。会话内记忆是当前对话的滚动窗口处理方式最简单超了就摘要或滑窗裁掉。长期事实记忆是用户偏好、账号信息这类稳定内容适合结构化存储加精确查询。情景记忆是历史任务的过程记录用于上次类似的问题是怎么解决的通常向量检索。语义记忆是从大量文档里提炼出的知识偏 RAG 那一套。2.5 第五层编排与协作层走到这一层问题的性质变了不再是一个 Agent 怎么想,而是多个环节怎么配合。编排可以是确定性的流程分支、并行、循环也可以是概率性的由一个调度 Agent 决定下一步交给谁。这两者不是替代关系实际项目里最常见的是混合结构主干流程用确定性编排保证可控局部复杂环节交给调度决策。多 Agent 协作最容易踩的坑是通信开销。两个 Agent 来回对齐一次消耗的上下文可能比完成任务本身还多。我的一条经验法则是只有当子任务的上下文需求差异超过三倍或者需要不同的工具权限集合时才值得拆成多个 Agent。否则不如拆成同一 Agent 的不同技能。2.6 层间暗线四条容易被忽略的耦合关系分层是为了理解不是为了隔离。实际系统里有四条暗线必须盯着。第一条模型能力决定外壳复杂度。模型越弱外壳就越要用显式的状态机和校验逻辑来兜底模型强了外壳可以更薄。第二条技能数量决定记忆策略。工具有二十个以上的时候工具描述本身就会吃掉大量上下文这时候必须先做工具检索再做工具调用。第三条记忆质量决定编排粒度。记忆差的时候你不敢让 Agent 自主决定分支只能把流程写死。第四条编排结构反向影响模型选择。多 Agent 架构对单模型的能力要求反而更低因为每个角色只需要专注一件事。3. 40 概念避坑指南3.1 三组最要命的孪生词第一组是Agent 与 Harness。判别口诀Agent 是决策者Harness 是承载者。你在讨论它该不该自己决定下一步时说的是 Agent你在讨论它的循环、超时、沙箱怎么配时说的是 Harness。两者经常被放在同一句话里出售但它们是可替换的两个部件。第二组是Agent 与 Skill。判别口诀Agent 是主语Skill 是谓语。一个 Agent 可以挂载多个 Skill一个 Skill 也可以被多个 Agent 复用。Skill 本身不做决策它只负责被调用后可靠地返回结果。凡是声称Skill 能自主规划的说法本质上它已经是个 Agent 了。第三组是Agent 与 Workflow。判别口诀谁来定下一步。如果下一步由代码里的分支决定那是工作流如果下一步由模型根据当前状态生成那才是 Agent。这个区别直接决定了你的测试策略——工作流可以写单元测试Agent 必须做评测集。3.2 记忆与上下文相关概念这一块的名词密度最高。上下文窗口是硬限制说的是模型单次能看多少上下文长度是当前实际占用了多少上下文压缩是在超限前做的摘要或裁剪记忆检索是从外部存储里捞出相关内容再塞进窗口。很多人把记忆和上下文混着说结果在排查为什么它忘了刚才说的话的时候连该查存储还是查拼装逻辑都分不清。还有一个高频混淆是摘要和提炼。摘要保留原意的骨架用于压缩对话历史提炼是从多个来源里抽出结论并去重用于知识固化。前者的产物还是文本后者的产物更适合结构化成键值对。3.3 评测与测试相关概念Agent 的测试和传统软件测试不是一套方法论。传统测试追求确定性断言Agent 的输出天然带随机性所以必须用评测集加评分标准的方式。这里的关键词包括评测集一组带期望结果的输入、评分器自动或人工判分、轨迹记录中间每一步的思考和调用、回归基线每次改动后重跑同一批用例对比、以及失败样本归档。我特别想强调的是轨迹可观测性。只看最终答案对不对你永远不知道是模型选错了工具还是工具本身有 bug还是记忆检索捞错了东西。把每一步的输入输出完整落盘这是做 Agent 项目必须一开始就建的基建事后补的代价要高得多。3.4 概念速查表40 条下面这张表是我从实际评审记录里整理出来的每一条都对应过一次真实的沟通事故。概念一句话定位最容易和谁混判别口诀Agent能做决策的执行主体Harness、Workflow谁定下一步Harness承载 Agent 的运行外壳Agent、框架循环与沙箱归它Skill可复用的能力单元Tool、Agent不决策只执行Tool带参数的可调用接口Skill有输入输出契约Workflow代码写死的有向流程Agent分支不靠模型编排决定环节顺序的机制Workflow可以是概率性的调度 Agent负责分派的 Agent编排编排的一种实现子 Agent被分派执行的角色Skill有独立上下文上下文窗口单次可见的硬上限上下文长度上限 vs 占用上下文长度当前实际占用上下文窗口动态值上下文压缩超限前的摘要与裁剪记忆检索减量 vs 增量记忆检索从存储捞相关内容RAG记忆偏个人化会话记忆当前对话的滚动历史长期记忆会话结束即失效长期记忆跨会话保留的事实情景记忆是否结构化情景记忆历史任务的过程记录长期记忆存过程不存结论语义记忆提炼后的知识RAG 知识库谁提炼的向量检索按语义相似度召回关键词检索模糊 vs 精确混合检索向量加关键词加权向量检索多路召回融合重排序对召回结果二次排序检索精排阶段分块把长文切成检索单元压缩面向存储提示词模板可参数化的提示词Skill无执行能力系统提示词定义角色与硬约束用户提示词优先级更高工具描述告诉模型何时用工具工具名称场景导向参数模式工具入参的结构定义输出契约只描述输入输出契约工具返回的结构约定参数模式只描述输出函数调用模型输出结构化参数工具执行调用 vs 执行循环控制决定继续还是停止终止条件控制的是过程终止条件明确结束的判据循环控制控制的是终点最大轮数兜底的轮次上限终止条件硬保险轨迹每一步的思考与调用记录日志轨迹含决策可观测性能看到内部发生了什么日志更强调可回溯评测集带期望结果的输入集合测试用例允许模糊判分评分器给输出打分的组件人工评审可自动可人工评测维度从哪些角度看表现评分器维度先于评分回归基线改动前的成绩快照评测集用于对比幻觉编造不存在的信息误差是事实性错误越权调用调用了不该调用的工具参数错误权限问题沙箱限制执行环境的边界权限控制运行环境隔离幂等重复调用结果一致重试保证重试安全超时重试失败后的补偿机制幂等重试需幂等兜底人在回路关键节点人工确认全自动风险分级触发这张表建议直接贴到团队的文档首页。我见过太多项目前面两周的争论其实只要一张表就能省下来。4. 从零搭一个任务型 Agent 的实操路径4.1 需求收敛先写清不做清单我现在的习惯是先写不做清单再写需求。以帮运营同学整理周报数据这个任务为例不做清单里可能是不做跨库联表、不自动发送邮件、不处理需要二次授权的数据源。这份清单的价值在于它会直接决定你后面要不要上多 Agent、要不要做人工确认节点。任务边界清晰之后再盘点能力需要读哪几个数据源、需要做哪几类计算、需要生成什么形态的输出。这一步的产出应该是一张能力表每一条对应后面一个技能定义。凡是盘点不出来的能力说明需求还没聊透别急着写代码。4.2 上下文预算怎么算这是我踩坑最多的地方给一个可以直接套的算法。假设模型上下文窗口是 128K预留百分之二十作为输出空间可用输入是 102K。接下来做分配系统提示词和角色约束 2K、工具描述 4K按每个工具 200 到 400 token 估挂 12 个工具、记忆检索结果 6K、当前会话历史 20K、本轮任务输入和中间产物 30K剩下的 40K 留作缓冲和突发。这个分配的关键在于工具描述和记忆检索不能同时无限膨胀。工具超过 15 个的时候我会把工具分成常驻和候选两组先用一次轻量检索筛出候选再把候选的完整描述注入。这一步大概能省下百分之四十的上下文。注意预算算完之后一定要用真实数据跑一遍别信估算。同一个工具描述中文和英文的 token 消耗能差出三成。4.3 技能定义的参数设计技能定义我一般按这个模板写名称动宾结构、一句话用途、使用场景什么时候该用、禁用场景什么时候不该用、参数列表、返回结构、失败时的建议动作。其中禁用场景这一栏最容易被省略但它对降低误调用率的效果非常明显。举个人话版的例子一个查询订单的技能禁用场景里应该写用户询问的是物流进度而非订单状态时请使用物流查询技能。这一句话能让模型少走很多弯路。参数设计上尽量把枚举值写全避免让模型自由发挥。日期统一用 ISO 格式并注明时区金额注明币种ID 类字段注明前缀规则。返回结构里保留一个error_code字段让上层能做分支处理而不是靠解析自然语言报错。4.4 记忆写入与检索策略写入侧我遵循三写三不写。写用户明确表达的偏好、写任务的关键结论、写被纠正过的错误不写模型的中间推理、不写可随时重新获取的数据、不写含敏感信息的原文。这一条能挡掉大量存储膨胀和数据风险。检索侧建议先做两段式第一段用结构化条件过滤用户 ID、时间范围、类型第二段在过滤后的集合里做向量召回最后按相关度和新鲜度加权排序取前五到八条。取太多会挤占上下文取太少覆盖不足。我在一个项目里做过对比返回条数从 5 提到 15任务成功率只涨了不到百分之二但平均成本涨了近四成。4.5 编排回路与终止条件回路的骨架我固定成四步理解当前状态、决定是否调用工具、执行并观察结果、判断是否结束。这里最关键的是终止条件的写法必须有多重保险。第一重是任务完成判据由模型输出一个明确的结构化标记。第二重是最大轮数硬编码兜底比如 12 轮。第三重是预算上限累计 token 超过阈值直接中断并返回已有结果。第四重是重复检测连续两轮的工具调用参数完全一致就判定卡死。四重保险叠起来线上因死循环炸掉预算的情况基本就消失了。这四条不是理论是我在一次失控事故之后逐条加上去的。4.6 上线前的评测清单上线前我会跑一份固定清单单工具调用准确率、多工具串联成功率、参数格式合法率、无工具场景的拒绝率、超长输入的降级表现、以及十到二十条真实历史任务的端到端通过率。其中无工具场景的拒绝率特别值得单独测。很多 Agent 的问题是过度自信明明没有合适的工具它也要硬调一个结果就是错误数据流到下游。测这一项的方法很简单准备十道答案在知识里、不需要任何工具的问题看它会不会乱调。5. 常见故障与排查实录5.1 无法生成响应的排查顺序这个报错信息几乎没有任何信息量所以必须按固定顺序排查。我的顺序是先看请求体是否超限超限往往表现为这类通用报错再看工具描述里有没有格式非法导致的解析失败然后看是否有工具返回了超长内容把窗口撑爆最后才怀疑模型侧。一个很隐蔽的原因是工具返回结果没有截断。某个接口返回了完整的两百条记录光这一条就把上下文占满了后续请求直接失败。解决办法是在工具层强制加截断返回条数上限和字段白名单都写死不要让模型决定要多少。5.2 执行中断与安装回滚现场安装类问题在桌面端工具上尤其常见典型表现是装到一半回滚日志里只有一行退出码。这类问题九成出在环境依赖上磁盘空间、运行时版本、权限目录、以及被杀软拦截。排查顺序建议固定为——先看磁盘和内存余量再看运行时版本是否满足最低要求然后手动在命令行跑一次安装命令看完整输出最后检查安装目录是否有残留导致重复写入失败。残留目录这一条我吃过两次亏。第一次失败之后目录里留了半截文件第二次安装直接在建目录阶段就退出了清干净之后一次过。5.3 死循环与预算失控死循环的典型特征是轮数在涨、token 在涨、但任务状态没有变化。识别方法是在每轮结束时对当前状态做一个哈希连续两轮哈希相同就报警。除了前面说的四重保险还有一个更根本的解法让工具返回更有区分度的信息。很多死循环的本质是工具每次返回的都是同一句话模型得不到新信息只能反复重试。在工具返回里加上时间戳、剩余条数、或者明确的无更多结果标记往往能直接解决问题。5.4 工具调用失败的分层定位按五层架构来定位会快很多。如果模型压根没输出工具调用问题在外壳的提示词拼装或者模型层如果输出了调用但参数不合法问题在技能定义的参数模式如果参数合法但执行报错问题在工具实现或权限如果执行成功但结果没被采纳问题在记忆层或者编排层的状态判断。我一般会先把失败样本的完整轨迹打出来看断在哪一环再往对应层去查。这个方法的效率比从头读代码高很多尤其在接手别人项目的时候。5.5 排查速查表现象最可能的层优先检查项通用报错无细节外壳层请求体大小、工具返回截断不调用任何工具外壳层 / 模型层系统提示词、工具描述场景参数格式错误技能层参数模式与枚举值执行超时技能层下游接口、超时配置重复调用同一工具编排层重复检测、工具返回区分度忘记前文信息记忆层检索条件、写入策略选了错误的工具技能层工具命名与禁用场景输出格式不稳定模型层格式约束、示例注入中途停止不回结果编排层终止条件、异常捕获成本异常升高编排层 / 记忆层轮数、检索返回条数6. 学习路线与面试准备6.1 分阶段学习路线我把入门路径分成四段每段都有明确的产出物没有产出物就不算学完。第一段跑通最小可用的单工具 Agent。目标是能读懂循环骨架的每一行代码产出是一个能查天气或者查数据库的小工具。这一段不要碰框架手写一遍收获最大。第二段做记忆和检索。目标是理解写入策略和检索策略如何影响最终表现产出是一个带长期记忆的助手能记住用户在前几次对话里说过的话。第三段做评测。目标是能为一组任务写出评测集和评分器产出是一份可重复运行的评测报告。这一段是分水岭会做评测的人和不做评测的人半年后的水平差距非常明显。第四段做编排和多角色协作。目标是能判断什么场景值得拆 Agent、什么场景拆了反而更糟产出是一个混合编排的完整项目。6.2 面试高频题的答法这类岗位的面试题套路化的背法很容易被追问穿。我感觉比较稳的答法是先讲取舍再讲实现。被问到 Agent 和框架的关系时不要只答定义直接讲你曾经因为框架封得太深而排查困难的经历以及后来怎么把关键环节自己接管。被问到记忆方案时讲清楚你为什么选结构化加向量的混合方式以及返回条数是在哪个数据量下测出来的。被问到多 Agent 时讲清楚你的拆分依据和通信成本怎么控制。凡是能用一次真实事故收尾的答案可信度都会高一个档次。反过来只会背名词的答案追问两层就空了。6.3 后续可以往哪扩如果这五层你已经跑通了往下的延展方向大致有三个。一是往深做评测把评分器从规则升级成模型判分加人工抽检的组合把回归做成持续集成的一环。二是往宽做协作研究多个角色之间的上下文怎么隔离、冲突怎么仲裁、共享记忆怎么去重。三是往实做落地把 Agent 接到真实业务系统里处理权限、审计、幂等这些脏活。我个人在做这类项目的体会是真正拉开差距的从来不是用了哪个框架而是你有没有把哪一层出了问题这件事变成一种本能。我现在的习惯是每接一个新问题先在纸上画出五层标出可疑的那一层再去翻代码。这个动作花不了两分钟但能省掉大量的盲目排查。另外再分享一个小技巧把每次线上事故的排查结论写进一张表注明现象、定位到的层、根因和修复方式攒到二十条之后你会发现新问题的答案基本都在里面了。