如果你最近在技术社区里泡着大概会有一种很割裂的感觉一边有人问“harness 和 agent 到底什么区别”另一边有人发“agent 开发 30 天速成路线”同一个词有人指的是一个能自己开浏览器干活的数字员工有人指的是 JVM 里做字节码增强的那个 java agent。再叠加一批以代号、动物名命名的客户端产品以及“开通会员解锁更多 agent 调用次数”这种纯广告文案搜索结果基本就没法看了。这篇东西我按Agent 五层架构的思路把 2026 年这一波 Agent 产业与技术的关键概念重新捋一遍顺带把 40 多个高频词逐个拆开讲清楚哪里最容易踩坑。适合三类人刚准备入门 Agent 开发的新手、被各种框架名词绕晕的中级工程师、以及需要给团队做技术选型和面试筛选的负责人。全文不讲玄学只讲每一层该干什么、常见误解在哪、以及能直接抄的落地节奏。1. 热搜词里的 Agent为什么越看越乱1.1 我观察到的三类“词污染”把最近这批热搜词摊开看混乱其实不是随机的主要来自三个方向。第一类是营销文案混进技术词比如“开通某编辑器会员解锁更多 agent 调用次数”这种句子本质是订阅广告它把“调用额度”包装成了“Agent 能力”新手很容易误以为 Agent 是一种要充值才能解锁的功能。第二类是产品名替代了概念名一批客户端产品都叫某某 agent导致很多人以为 Agent 必须装在桌面上、必须有图形界面实际上它可能只是服务端一个循环调用模型的进程。第三类是同形不同义的碰撞这个最坑java agent是 JVM 层面的字节码增强技术出现时间比这波 AI 浪潮早得多和 AI Agent 除了名字重合以外毫无关系agent browser有人认为是一种浏览器产品有人指的是“让 Agent 操作浏览器”这项能力讨论时不在一个频道上。还有一类更隐蔽的把执行报错当成概念问题。热搜里那种“agent execution terminated due to error”“agent couldnt generate a response, please try again”以及某个工具“安装中途回滚”这些都是工程侧问题不是技术路线问题。但新手看到这类关键词会误以为“Agent 就是不稳定、跑不通”于是还没开始就先怯了。说句实在话这类报错九成以上出在编排层的重试与兜底逻辑上跟模型本身关系不大后面第 4 章我会专门讲怎么定位。提示当你在搜索结果里同时看到“架构”和“安装失败”两种内容时先判断你要解决的是认知问题还是工程问题。这两类问题的排查路径完全不同混着查只会浪费一整天。1.2 用五层架构统一认知一张嘴就能讲清楚的骨架我习惯把整个 Agent 系统自上而下切成五层从用户能感知到的往下走第五层应用与交互层用户看到什么、怎么和 Agent 对话或协作、第四层记忆与知识层Agent 记得什么、能检索到什么、第三层能力与工具层Agent 能动手做什么也就是 tool、skill 这类东西、第二层编排与运行时层谁来决定下一步做什么也就是 harness、路由、循环控制、第一层模型与推理层最底下的模型包括对话模型、向量模型、重排模型等。此外还有两条横线贯穿全部五层安全与评测可观测。这个切法的好处是任何一个新词进来你都能在三秒内定位它属于哪一层进而判断它和你的项目有没有关系。比如“agent 记忆”属于第四层“路由识别节点”属于第二层“agent 安全”是横线“agent 面试”压根不属于任何一层它是人才市场的事。至于“agent 八股”那是这套骨架被压缩成的面试背诵版。定位清楚了你再看各种框架的文档就能一眼看出它是在哪一层做文章而不是被一堆新名词牵着走。1.3 为什么这个时间点必须重排一次前两年大家还在纠结“Agent 能不能干活”讨论的焦点是模型够不够聪明。到了现在模型侧的进步已经明显外溢到工程侧同一个模型换个编排方式任务完成率差出二三十个百分点是常事。也就是说上限由模型决定实际表现由 harness 决定。这就解释了为什么热搜里“工业级 agent harness”“agent harness 长上下文 cot 的范式”这类词开始冒头——大家在实践中发现光换模型没用得把编排这一层做扎实。另一个变化是能力的标准化。工具怎么暴露给 Agent从各家自己定一套逐渐收敛到协议化的思路MCP 这类接口标准让“同一个能力接入多个 Agent”变得可行多 Agent 之间怎么互相认识、怎么互相调用也开始有 A2A 这类协议以及 Agent Card 这样的描述机制。标准一出现产业分工就会重排有人专做模型有人专做运行时有人专做能力包。你不重排认知就会一直站在错误的层里跟人吵架。2. 五层架构逐层拆解每层该干什么、不该干什么2.1 第一层模型与推理层决定上限的那一层这一层是纯模型相关的东西但很多新手把它想得太简单以为“选个最强的对话模型就完了”。实际上一个完整 Agent 系统里通常同时跑着四类模型角色推理/对话模型负责规划和生成**向量模型embedding**把文本变成用于检索的向量重排模型rerank给初步召回的候选做精排还有一类小模型专门干分类和抽取这类“脏活”比如判断用户这句话属于哪个意图、从一段文本里抠出结构化字段。这四类角色分工明确用一个顶配大模型全包成本会难看得让你怀疑人生。要理解这一层几个参数必须搞明白。上下文窗口是模型单次能看到的最大 token 数量它不是“记忆”只是“眼前能看到的东西”超了就必须裁剪或摘要。KV Cache是推理侧对已计算结果的一种复用它直接决定多轮对话和长上下文场景的延迟与成本长会话越到后面越贵就是这个原因。温度控制采样的随机性做规划类任务时调低更合适做头脑风暴类任务可以调高。还有一个容易被忽略的推理预算。带着思维链的模型在思考上花多少 token是可以约束的思考太多会拖慢并推高成本太少又容易漏步骤。实操心得我一般的做法是先在真实任务上做一次“模型角色盘点”把每个环节的输入输出写清楚再逐个环节选模型。凡是“输入确定、输出格式固定”的环节一律优先考虑小模型或规则省下来的预算留给真正需要推理的节点。这个动作做完整体成本经常能砍掉一半以上。2.2 第二层编排与运行时层harness 是真正的分水岭如果只能选一层来投入精力我选这一层。harness 可以理解为“模型权重之外的一切骨架”主循环怎么转、什么时候该停、状态怎么存、工具怎么调度、报错怎么重试、上下文怎么裁剪、权限怎么收口。它和 Agent 的关系不是并列的而是容器与内容的关系——Agent 是那个“会做决定的角色”harness 是让这个角色能持续运转的场地、规则和后勤。所以有人问“harness 和 agent 区别”我会说你把 Agent 想象成一个临时请来的专家harness 就是他进厂时要签的作业规程、领到的工牌权限和旁边盯着的安全员。这一层最核心的决策是确定性与自主性怎么配比。纯工作流Workflow是固定路径节点和分支都写死好处是可预测、好评测、成本可控坏处是遇到没预想到的情况就卡住。纯自主 Agent 是让它自己想下一步灵活但容易跑偏、难评测、烧钱。我的经验是主流程用工作流把“决策点”留给 Agent。比如一个客服系统意图识别、知识检索、回复生成这几个节点是固定的但“要不要转人工”“要不要追加上一轮的订单信息”这类判断交给 Agent 做。这样既保住了可控性又拿到了灵活性。另一个关键设计是错误恢复。热搜里那些“执行中断”“安装回滚”“生成失败请重试”本质上都是这一层没做好。合格的 harness 至少要处理三种失败模型返回空或者格式不对、工具调用超时或报错、以及外部状态已经改变导致重试不安全。前两种靠重试加格式校验兜住第三种必须靠幂等设计——同一个操作重复执行不会产生副作用。这一步不做你迟早会遇到“Agent 重复下单两次”这种事故。2.3 第三层能力与工具层skill、tool、MCP 的边界这一层是新手最爱造轮子、也最容易失控的地方。我先把三个词的边界定清楚tool 是原子的函数调用比如“查询天气”“执行一段 SQL”粒度最小、职责单一skill 是打包好的能力单元通常包含提示词、脚本、示例、输入输出校验和失败处理是“能完成一类任务”的封装比如“生成一份周报”可能内部调了三个 toolMCP 是一类接口标准解决的是“能力怎么以统一方式暴露和被调用”的问题让同一份能力能被不同 Agent 复用而不用每家重写一遍适配层。所以“skill 和 agent 的区别”和“skill 和 agent 的区别”这类问题答案不在一个维度上Agent 是决策主体skill 是它能调用的一种能力包。很多人把 skill 当成 Agent是因为某些平台把两者放在同一个界面里展示视觉上扁平了概念上其实有严格的上下级关系。反过来说如果你把一个需要多步判断的任务硬塞进一个 tool 里写出来就是一堆 if-else维护起来极其痛苦而如果你把每个原子操作都包装成独立 Agent系统会被通信开销拖死。粒度失控是这一层最大的坑。注意工具描述description的写法比工具本身更影响成败。模型选哪个工具几乎完全依赖描述文本。我见过最离谱的案例是十几个工具的描述全是“用于处理数据”模型只能随机挑。描述里至少要写清楚这个工具做什么、什么时候该用、什么情况下不要用、入参的含义和取值范围。2.4 第四层记忆与知识层上下文工程的主战场Agent 的“记忆”不是一个东西至少分四类。短期记忆就是当前会话的上下文窗口会话一关就没了工作记忆是任务执行过程中的中间状态比如当前计划、已完成的步骤、临时结论通常存在结构化的状态对象里长期记忆是跨会话保留的信息比如用户偏好、历史结论程序性记忆是你沉淀下来的提示词模板、skill 和流程经验它让 Agent“越来越会干活”而不是“越来越了解你”。这四类混在一起谈讨论必然跑偏。和记忆贴得最近的是 RAG检索增强生成。这里我要说一句可能不太讨喜的话RAG 的效果瓶颈几乎从来不在模型而在检索质量。文档怎么切分、切多大、要不要保留标题层级、embedding 模型用哪个、要不要做混合检索关键词加向量、要不要上重排这些决定了召回的候选中到底有没有正确答案。答案都不在候选里后面的生成模型再强也只能编。新手常见的错误是先把大模型换成更贵的版本结果毫无改善因为病历根本不在医生手上。这一层还有个绕不开的话题是“长上下文能不能替代 RAG”。我的答案是部分替代不能全部替代。当资料量不大、且每次任务都需要看全文时直接把内容塞进上下文确实更简单、更准但当资料是几十万份文档、需要跨文档找证据时检索依然是必需的而且成本差距会大到无法忽视。更现实的方案是混合先用检索缩小范围再把高相关片段放长上下文里做深度推理也就是热搜里提到的“长上下文 思维链”那套组合。2.5 第五层应用与交互层多 Agent 协作与协议登场用户能感知的一切都在这一层对话界面、任务面板、审批流、以及多 Agent 之间怎么配合。多 Agent 的拓扑结构我归成四类主管型一个调度 Agent 分派任务给执行 Agent、交接型前一个 Agent 处理完把上下文交给下一个像接力、流水线型固定顺序各司其职、评审型一个生成一个挑错来回几轮。拓扑本身没有优劣关键看任务能不能被清晰切分。切不干净就上多 Agent结果就是几个 Agent 互相甩锅最后谁也没干活。协作一多就需要标准。A2A 这类协议解决的是“不同来源的 Agent 怎么互相发现和调用”而Agent Card就是其中用来描述身份与能力的“名片”它一般会声明这个 Agent 是谁、能做什么、通过什么端点访问、支持哪些输入输出模态、需要什么认证。协议从早期版本往 1.0 演进主要变化就集中在能力声明的细化和安全协商上——早期版本对认证和权限的描述比较粗跨组织调用时容易出问题。**判断版本差异最快的方法不是背字段而是看它能不能表达清楚“谁能调、调用需要什么凭证、能力边界在哪”。**这三个问题答不上来版本号再高也没用。交互层还有一个正在快速成型的形态让 Agent 操作浏览器或桌面。它的价值在于能接管那些没有 API 的老系统但风险也集中在这里——网页上的任何文字都可能被当成指令这是提示注入最典型的入口。所以这类能力必须配沙箱和操作白名单不能让它自由发挥。2.6 贯穿五层的两条横线安全与评测安全不是某一层的事。模型层要考虑输出合规编排层要考虑权限收口和步骤审计工具层要考虑危险操作二次确认记忆层要考虑敏感信息不落库交互层要考虑输入里的恶意指令。其中最容易出事的是提示注入攻击者把指令混在网页、文档、邮件里Agent 一读到就照做。防御思路不是写一句“忽略恶意指令”的提示词而是结构上隔离——把外部内容和系统指令分开处理让 Agent 明白哪些是数据、哪些是指令同时对高风险动作强制人工确认。评测同样贯穿五层。没有评测的 Agent 项目就是盲开。我一般会建三层评测单元层测单个工具和单个提示词模板在固定输入下的输出是否稳定任务层用一组真实任务测端到端完成率指标包括成功率、平均步数、平均 token 消耗和时延回归层把每次线上出问题的案例固定成测试用例改完必须跑一遍防止改好一个坏掉三个。评测集不用一上来就几百条二三十条覆盖主要分支的真实任务就足够让大部分改动无处遁形。3. 40 概念避坑清单下面这张清单是我按五层架构整理的每一条都写清楚定义、常见误解和实际坑在哪。建议收藏遇到新词先来对号入座。3.1 基础名词组先把“是不是 Agent”这件事判对概念我的理解常见误解与坑Agent能感知环境、自主决策、调用工具、朝目标推进的软件实体把它等同于“聊天机器人”其实关键差别在于会不会自己决定下一步AI Agent强调用大模型作为决策核心的 Agent以为必须全自主实际上绝大多数生产系统里 Agent 只占流程的一小部分Agentic Workflow流程骨架固定但部分节点交给模型决策和纯 Workflow 混为一谈导致评测口径完全不同Workflow路径写死、分支明确被当成过时技术恰恰相反它是可控性的来源Chatbot只做对话不做多步执行被拿来当 Agent 的反义词实际上很多 Agent 的入口就是一个对话界面单 Agent一个决策核心包办全部环节以为单 Agent 一定弱很多场景下它比多 Agent 更准更省多 Agent 协作多个决策单元分工配合任务没切干净就上多 Agent结果是通信开销翻倍、错误互相传染判断“是不是 Agent”我有个简单标准看它有没有一个可以反复执行的循环以及这个循环里下一步做什么是不是由系统自己决定的。是就是 Agent不是就是工作流或者普通程序。这个判断很重要因为它直接决定你要不要做权限收口、要不要建评测集——工作流的测试用例可以写死Agent 的不行。3.2 编排与运行时分词组面试最爱问的一组概念我的理解常见误解与坑Harness模型之外的全部运行时骨架被当成某个具体框架的名字其实它是一种角色谁都能做编排Orchestration决定任务怎么拆、节点怎么连、状态怎么流转只关注画流程图忽略了错误恢复和状态持久化路由识别节点判断当前输入该走哪条分支的环节直接丢给大模型分类延迟和成本都高小模型或规则往往更合适规划Plan-and-Execute先出计划再逐步执行计划一次生成后从不修正执行偏了也不知道回头ReAct边推理边行动观察结果再决定下一步当成万能范式实际上对步骤多的任务容易迷路反思Reflection让模型检查自己的输出并改进无脑加反思结果模型反复推翻已正确的答案成本翻倍Handoff把任务和上下文交给另一个执行者交接时上下文丢失或传全量前者导致重来后者导致超预算Subagent主 Agent 派生出的子执行单元以为派出去的越多越快实际上并行度太高手动排查几乎不可能幂等同一操作重复执行不产生额外副作用只在读操作上做写操作忘了重试就出现重复下单兜底模型没给出可用输出时的备用路径只做重试不做降级模型持续异常时整个流程直接崩这一组里我最想强调的是兜底设计。热搜里那些“生成失败请重试”“执行中断”的抱怨绝大多数是因为系统只有一条路径模型返回 → 解析 → 执行。模型返回空、返回格式不对、返回了不存在的工具名任何一环出问题整个任务就断。合格的写法是三层兜底格式修复试着从输出里抽出结构化内容、有限重试换提示词再试一次最多两次、降级路径走规则或转人工。这三步加起来代码量不大但能把可用性往上抬一个台阶。3.3 能力与工具组别再把 skill 当 Agent概念我的理解常见误解与坑Tool原子函数调用职责单一一个工具干十件事参数列表长得没人会调Skill封装好的能力包含提示词、脚本、校验和 Agent 混为一谈实际上 skill 是被调用方Function Calling模型输出结构化调用请求的机制以为它会自己执行实际执行永远在你自己的代码里MCP能力的标准化暴露与调用接口以为接上就万事大吉忽略了权限和审计工具描述告诉模型这个工具是什么、何时用写得含糊模型只能瞎猜选错工具是最高频故障浏览器操作让 Agent 操作网页完成任务把它当默认方案其实有 API 就别用浏览器贵且脆计算机操作更广义的桌面与系统级操作能力不设沙箱直接放权误删误改风险极高能力白名单明确允许 Agent 使用的工具集合图省事给全量权限出一次事故就够喝一壶注意工具数量不是越多越好。我的经验是单个 Agent 暴露的工具控制在十二个以内再多就分组成 skill 或者拆成子 Agent。工具太多会让模型的选择准确率明显下降而且排查问题时你根本不知道是哪一步选错了。3.4 记忆与知识组概念最容易互相打架的一组概念我的理解常见误解与坑短期记忆当前会话的上下文当成长期记忆用会话一断全丢工作记忆任务执行中的中间状态不落盘进程一重启计划全没了长期记忆跨会话保留的信息什么都往里存噪声越来越大反而拖累效果程序性记忆沉淀下来的技能与经验只沉淀提示词不记录失败案例同样的坑反复踩上下文窗口单次能看到的 token 上限等同于记忆其实只是“眼前可见”长上下文窗口特别大的模型能力以为可以替代检索资料量一大成本和延迟都不可接受RAG先检索再生成效果差就换模型其实应该先看切分和召回切分Chunking把文档切成可检索片段按固定字数硬切句子和表格被拦腰截断混合检索关键词与向量结合只用向量遇到专有名词和编号就召回不到重排Rerank对召回结果做精细排序跳过这一步直接生成前面几十条候选里正确答案排在末尾Embedding文本转向量的模型和对话模型混着选忽略了它是独立的一类模型LLM 与 Embedding 区别一个生成、一个表示面试高频题答不上来通常会暴露对链路理解不完整向量库存向量并做相似度检索上来就搭集群其实几万条数据用轻量方案完全够上下文裁剪超窗口时保留哪些内容简单按时间截断把系统指令和当前任务目标裁掉了这一组里最值得多说一句的是切分。我见过太多项目在切分上偷懒按固定字符数硬切结果一个完整的表格被切成三段检索引擎只召回中间那段模型看到的是一张没有表头的表格输出自然离谱。我的做法是优先按语义结构切标题、段落、列表项为边界保留一定的重叠同时把文档标题路径附加到每个片段前面让片段自带上下文。这一步做对检索效果往往比换更贵的模型提升还大。3.5 协作与协议组名字新但不是全都得用概念我的理解常见误解与坑A2A 协议不同 Agent 之间互相发现与调用自家系统内部通信也上这套纯属增加复杂度Agent Card描述 Agent 身份与能力的名片字段填得很随意跨团队调用时权限和模态对不上协议版本差异早期版本到 1.0 的能力细化只对版本号不看能力声明和安全协商部分是否够用主管型拓扑一个调度者分派任务调度者成了单点它一挂全挂交接型拓扑上下文像接力棒一样传递交接时不做摘要越传越长最后爆窗口评审型拓扑生成与挑错来回迭代没有终止条件两个 Agent 无限对线人机协同关键节点由人确认要么全自动要么全人工没设计中间档多 Agent 我的态度一直比较保守能用单 Agent 加清晰工具解决的不要上多 Agent。多 Agent 的真实价值在于角色冲突的场景比如一个负责产出、一个负责挑错这种对抗性结构确实能提升质量。但如果只是任务步骤多那用工作流拆节点就够了硬拆成多个 Agent 只会让调试难度指数上升——你连问题出在哪个 Agent 上都要花半天。3.6 工程治理组决定能不能上生产的一组概念我的理解常见误解与坑可观测性记录每一步的输入输出与耗时只打日志不做结构化出问题靠肉眼翻Trace 回放把一次执行完整重现不存中间状态问题无法复现评测集一组带预期结果的真实任务全是简单样例上线后复杂场景全崩黄金集稳定不变的基准测试数据被拿去调参后又当评测用等于自己骗自己提示注入外部内容里夹带指令靠提示词防御应该靠结构化隔离沙箱隔离执行环境只在生产开开发环境随便跑习惯养歪最小权限只给完成当前任务所需的权限图方便给全量凭证一次注入就是事故人工确认高风险动作前拦截所有动作都确认用户直接弃用成本监控跟踪 token 与调用费用只看总量不按会话拆找不到烧钱的环节灰度发布小流量验证后再全量直接全量上线出问题只能回滚这一组里我最想提醒的是黄金集的使用纪律。很多团队把评测数据拿去调提示词调完再用同一批数据测指标好看得不得了一上线全线崩。正确做法是评测数据分两份一份可以随便用来看效果的开发集一份锁起来只在发布前跑一遍的验收集。这份验收集每次发布都跑指标掉超过阈值就不许发。这个纪律听起来很笨但它能挡掉绝大部分“改好一个坏掉三个”的情况。3.7 最容易同名踩坑的一组java agent是 JVM 的字节码增强技术用于探针、监控、热更新这类场景和 AI Agent 没有任何关系搜资料时一定要带上限定词否则会得到完全无关的结果。具身智能 agent指的是有物理载体、能感知和作用于真实世界的智能体它的核心难点在感知与控制和大模型 Agent 的技术栈重合度有限别把两者当成同一件事来规划学习路线。pi agent、hermes agent、orca agent这类名字属于产品命名不同产品的架构差异可能很大判断它们的价值要看底层是哪套运行时、支持哪些能力接入方式而不是看名字。还有一类是客户端与服务端之分桌面端产品只是外壳真正的编排逻辑可能在云端这直接决定了你的数据流向和合规边界选型时必须问清楚。上面这张清单加起来超过四十条概念覆盖了从基础名词到工程治理的主要盲区。我的建议是不要背而是把它们贴到五层架构上去理解一个词落在哪一层它的价值、风险和维护方式就基本确定了。4. 从零上手Agent 开发的学习路线与实操节奏4.1 阶段一把单 Agent 跑通别急着上框架入门阶段最忌讳的就是一上来挑最复杂的框架。我的建议是用最朴素的方式写一遍一个主循环、三到五个工具、一个简单的提示词模板、一份结构化的运行日志。目标不是做出惊艳的东西而是亲手体会到三件事模型是怎么决定调用哪个工具的、工具返回结果是怎么被塞回上下文的、循环什么时候该停。这三件事搞明白了后面换任何框架都是换皮。这个阶段的具体任务是做一个“能查资料并给出带出处结论”的小助手。你需要准备一份几百字到几千字的本地资料做一次最简单的检索让 Agent 先检索再回答回答里要标出引用的是哪一段。这个练习的价值在于它同时踩到了检索、工具调用和格式约束三个点。写完你会发现最让人头疼的不是模型而是“模型有时候不按格式输出”这就是你第一次真正理解 harness 为什么重要。我建议这一步自己写格式化校验和一次重试逻辑不要用框架的封装亲手写一遍才知道坑在哪。4.2 阶段二把工具和记忆做扎实练的是工程手感单 Agent 跑通之后把精力放在两件事上工具描述的质量和记忆的分层。工具有了明确描述之后模型选错的概率会明显下降你可以做一个小实验同一批任务用模糊描述和详细描述各跑一遍把选错工具的次数记下来对比。这个实验做一次你以后写描述就再也不会敷衍了。记忆这块先实现工作记忆的持久化把任务状态写到一个可以恢复的地方进程重启后能接着跑。这一步做完你就解决了前面提到的“执行中断就得从头再来”的问题。还有一个必须练的能力是上下文裁剪。做法很直接给上下文设一个预算超出时按优先级保留——系统指令最优先当前任务目标其次最近的几轮交互再次最早的交互做摘要压缩。写一个简单的裁剪函数跑一批多轮对话看效果你会发现有些任务在裁剪后反而变好了因为噪声少了。这个反直觉的发现是很多人从新手进阶到熟练的分水岭。4.3 阶段三多 Agent 与生产化考的是判断力到了这一阶段重点不再是“能不能跑”而是“该不该这样跑”。我建议先做一次成本与延迟的基线测量同一个任务单 Agent 方案和多 Agent 方案各跑二十次记录成功率、平均步数、平均耗时和费用。数据摆出来之后很多争论会自然消失。多数情况下你会发现简单任务上单 Agent 全面占优只有在需要角色对抗的复杂任务上多 Agent 才有优势。这个结论比任何人的经验之谈都可靠。生产化要补的是另外几块可观测性每一步的输入、输出、耗时、token 消耗都要落库最好能一键回放、权限收口工具按角色分组高风险工具走确认流程、灰度与回滚新提示词和新逻辑先在小流量上验证、成本预警按会话维度监控异常会话自动告警。这几样东西都不难做难的是坚持做。我见过不少项目在演示阶段光鲜亮丽一上真实流量就各种超支和事故追根到底就是这几块欠账。4.4 常见故障速查表与踩坑心得现象大概率原因处理方式Agent 一直不结束反复调用同一个工具缺少终止条件或状态没有更新加步数上限和状态去重检查工具返回是否被正确写入状态模型输出空或者提示重试输出被截断或格式校验过严放宽校验、提高输出长度上限、加一次格式修复重试执行中途报错后无法恢复状态没落盘每步结束持久化状态恢复时从断点继续选错工具工具描述含糊或数量过多重写描述工具分组到十二个以内检索不到关键信息切分粗暴或缺少混合检索按语义切分、保留标题路径、补关键词检索和重排回答编造事实提示词鼓励“尽量回答”明确要求找不到就说找不到并强制输出引用来源成本突然飙升上下文无限增长加裁剪预算按会话监控 token任务交接后重复劳动交接时上下文丢失交接时传摘要而非全量明确已完成项上线后效果比测试差很多评测集过于简单补真实复杂样例建立验收集高风险操作误执行无确认流程危险动作二次确认沙箱内先演练我的踩坑心得Agent 项目里最贵的不是模型调用费而是排查问题的时间。所以从第一天起就把每一步的输入输出、耗时和 token 消耗结构化记录下来。哪怕只是一个落库的 JSON也比事后靠回忆猜测省下几十个小时。我吃过这个亏一个线上问题查了两天最后发现只是工具返回的一个字段名拼错了。5. 面试考点与团队落地八股背后的真实问题5.1 高频问题的“标准答案”之外现在 Agent 方向的面试题高度集中在几组对比上Agent 和 Workflow 的边界、harness 和 agent 的关系、skill 和 tool 的区别、LLM 和 Embedding 的分工、长上下文能不能替代检索、多 Agent 什么时候该用、怎么防提示注入。这些题目本质上考的不是记忆力而是你有没有真的动手做过。比如“怎么防提示注入”背一句“在提示词里要求忽略恶意指令”基本就废了面试官想听的是结构隔离、权限收口和人工确认这三个层次。再比如“长上下文能不能替代 RAG”答“能”或者“不能”都不完整能说清楚“小资料量可以、大规模文档不行、混合方案最现实”才算过关。如果我要出题我会给一个具体的失败案例让人现场分析一个 Agent 在测试环境表现很好上线后成功率掉了一半可能是哪些原因这题几乎能把五层架构全考一遍——模型层可能是数据分布不同编排层可能是重试策略在真实延迟下失效工具层可能是某个接口在高并发下限流记忆层可能是上下文裁剪把关键信息裁掉了交互层可能是真实用户的表达更口语化。能按层次系统排查的人和只会说“换个模型试试”的人差距一眼就看出来了。5.2 团队选型与推进节奏团队落地我最反对的做法是“先选框架再找场景”。正确的顺序是先找一个边界清晰、结果可验证、失败代价可控的场景做完再谈平台化。什么叫边界清晰就是这个任务有明确的输入和明确的成功标准比如“从一批工单里提取结构化字段并归类”而不是“帮我提升团队效率”。什么叫失败代价可控就是它出错的时候不会造成资金损失或数据泄露能兜得住。这两条都满足项目成功率会高很多。选型时我会重点看四件事编排层能不能自己控制循环、重试、状态是否透明可改能力接入是不是标准化新增一个工具的成本有多高可观测和评测是不是内建有没有 trace 和数据集管理权限和审计能不能收口高风险动作能不能拦住并留痕。至于模型选谁反而是最后才定的因为模型可以换前面这四件事换起来伤筋动骨。团队节奏上我的建议是第一个月只做单 Agent 加三五个工具第二个月补记忆和评测第三个月再考虑灰度上真实流量多 Agent 放到最后除非有明确证据说明单 Agent 撑不住。最后再分享一个小技巧给 Agent 项目建一份“故障日志”每次线上出问题就往里记一条写清楚现象、原因、修复方式和复现用例。三个月后你回头看会发现大部分问题都是重复的几类而这份日志就是你团队最值钱的资产——它比任何框架文档都更贴合你们自己的业务。Agent 这个东西热闹的概念一大半会过时但排查问题的经验不会。
Agent五层架构与高频词避坑：harness、MCP与多Agent指南
如果你最近在技术社区里泡着大概会有一种很割裂的感觉一边有人问“harness 和 agent 到底什么区别”另一边有人发“agent 开发 30 天速成路线”同一个词有人指的是一个能自己开浏览器干活的数字员工有人指的是 JVM 里做字节码增强的那个 java agent。再叠加一批以代号、动物名命名的客户端产品以及“开通会员解锁更多 agent 调用次数”这种纯广告文案搜索结果基本就没法看了。这篇东西我按Agent 五层架构的思路把 2026 年这一波 Agent 产业与技术的关键概念重新捋一遍顺带把 40 多个高频词逐个拆开讲清楚哪里最容易踩坑。适合三类人刚准备入门 Agent 开发的新手、被各种框架名词绕晕的中级工程师、以及需要给团队做技术选型和面试筛选的负责人。全文不讲玄学只讲每一层该干什么、常见误解在哪、以及能直接抄的落地节奏。1. 热搜词里的 Agent为什么越看越乱1.1 我观察到的三类“词污染”把最近这批热搜词摊开看混乱其实不是随机的主要来自三个方向。第一类是营销文案混进技术词比如“开通某编辑器会员解锁更多 agent 调用次数”这种句子本质是订阅广告它把“调用额度”包装成了“Agent 能力”新手很容易误以为 Agent 是一种要充值才能解锁的功能。第二类是产品名替代了概念名一批客户端产品都叫某某 agent导致很多人以为 Agent 必须装在桌面上、必须有图形界面实际上它可能只是服务端一个循环调用模型的进程。第三类是同形不同义的碰撞这个最坑java agent是 JVM 层面的字节码增强技术出现时间比这波 AI 浪潮早得多和 AI Agent 除了名字重合以外毫无关系agent browser有人认为是一种浏览器产品有人指的是“让 Agent 操作浏览器”这项能力讨论时不在一个频道上。还有一类更隐蔽的把执行报错当成概念问题。热搜里那种“agent execution terminated due to error”“agent couldnt generate a response, please try again”以及某个工具“安装中途回滚”这些都是工程侧问题不是技术路线问题。但新手看到这类关键词会误以为“Agent 就是不稳定、跑不通”于是还没开始就先怯了。说句实在话这类报错九成以上出在编排层的重试与兜底逻辑上跟模型本身关系不大后面第 4 章我会专门讲怎么定位。提示当你在搜索结果里同时看到“架构”和“安装失败”两种内容时先判断你要解决的是认知问题还是工程问题。这两类问题的排查路径完全不同混着查只会浪费一整天。1.2 用五层架构统一认知一张嘴就能讲清楚的骨架我习惯把整个 Agent 系统自上而下切成五层从用户能感知到的往下走第五层应用与交互层用户看到什么、怎么和 Agent 对话或协作、第四层记忆与知识层Agent 记得什么、能检索到什么、第三层能力与工具层Agent 能动手做什么也就是 tool、skill 这类东西、第二层编排与运行时层谁来决定下一步做什么也就是 harness、路由、循环控制、第一层模型与推理层最底下的模型包括对话模型、向量模型、重排模型等。此外还有两条横线贯穿全部五层安全与评测可观测。这个切法的好处是任何一个新词进来你都能在三秒内定位它属于哪一层进而判断它和你的项目有没有关系。比如“agent 记忆”属于第四层“路由识别节点”属于第二层“agent 安全”是横线“agent 面试”压根不属于任何一层它是人才市场的事。至于“agent 八股”那是这套骨架被压缩成的面试背诵版。定位清楚了你再看各种框架的文档就能一眼看出它是在哪一层做文章而不是被一堆新名词牵着走。1.3 为什么这个时间点必须重排一次前两年大家还在纠结“Agent 能不能干活”讨论的焦点是模型够不够聪明。到了现在模型侧的进步已经明显外溢到工程侧同一个模型换个编排方式任务完成率差出二三十个百分点是常事。也就是说上限由模型决定实际表现由 harness 决定。这就解释了为什么热搜里“工业级 agent harness”“agent harness 长上下文 cot 的范式”这类词开始冒头——大家在实践中发现光换模型没用得把编排这一层做扎实。另一个变化是能力的标准化。工具怎么暴露给 Agent从各家自己定一套逐渐收敛到协议化的思路MCP 这类接口标准让“同一个能力接入多个 Agent”变得可行多 Agent 之间怎么互相认识、怎么互相调用也开始有 A2A 这类协议以及 Agent Card 这样的描述机制。标准一出现产业分工就会重排有人专做模型有人专做运行时有人专做能力包。你不重排认知就会一直站在错误的层里跟人吵架。2. 五层架构逐层拆解每层该干什么、不该干什么2.1 第一层模型与推理层决定上限的那一层这一层是纯模型相关的东西但很多新手把它想得太简单以为“选个最强的对话模型就完了”。实际上一个完整 Agent 系统里通常同时跑着四类模型角色推理/对话模型负责规划和生成**向量模型embedding**把文本变成用于检索的向量重排模型rerank给初步召回的候选做精排还有一类小模型专门干分类和抽取这类“脏活”比如判断用户这句话属于哪个意图、从一段文本里抠出结构化字段。这四类角色分工明确用一个顶配大模型全包成本会难看得让你怀疑人生。要理解这一层几个参数必须搞明白。上下文窗口是模型单次能看到的最大 token 数量它不是“记忆”只是“眼前能看到的东西”超了就必须裁剪或摘要。KV Cache是推理侧对已计算结果的一种复用它直接决定多轮对话和长上下文场景的延迟与成本长会话越到后面越贵就是这个原因。温度控制采样的随机性做规划类任务时调低更合适做头脑风暴类任务可以调高。还有一个容易被忽略的推理预算。带着思维链的模型在思考上花多少 token是可以约束的思考太多会拖慢并推高成本太少又容易漏步骤。实操心得我一般的做法是先在真实任务上做一次“模型角色盘点”把每个环节的输入输出写清楚再逐个环节选模型。凡是“输入确定、输出格式固定”的环节一律优先考虑小模型或规则省下来的预算留给真正需要推理的节点。这个动作做完整体成本经常能砍掉一半以上。2.2 第二层编排与运行时层harness 是真正的分水岭如果只能选一层来投入精力我选这一层。harness 可以理解为“模型权重之外的一切骨架”主循环怎么转、什么时候该停、状态怎么存、工具怎么调度、报错怎么重试、上下文怎么裁剪、权限怎么收口。它和 Agent 的关系不是并列的而是容器与内容的关系——Agent 是那个“会做决定的角色”harness 是让这个角色能持续运转的场地、规则和后勤。所以有人问“harness 和 agent 区别”我会说你把 Agent 想象成一个临时请来的专家harness 就是他进厂时要签的作业规程、领到的工牌权限和旁边盯着的安全员。这一层最核心的决策是确定性与自主性怎么配比。纯工作流Workflow是固定路径节点和分支都写死好处是可预测、好评测、成本可控坏处是遇到没预想到的情况就卡住。纯自主 Agent 是让它自己想下一步灵活但容易跑偏、难评测、烧钱。我的经验是主流程用工作流把“决策点”留给 Agent。比如一个客服系统意图识别、知识检索、回复生成这几个节点是固定的但“要不要转人工”“要不要追加上一轮的订单信息”这类判断交给 Agent 做。这样既保住了可控性又拿到了灵活性。另一个关键设计是错误恢复。热搜里那些“执行中断”“安装回滚”“生成失败请重试”本质上都是这一层没做好。合格的 harness 至少要处理三种失败模型返回空或者格式不对、工具调用超时或报错、以及外部状态已经改变导致重试不安全。前两种靠重试加格式校验兜住第三种必须靠幂等设计——同一个操作重复执行不会产生副作用。这一步不做你迟早会遇到“Agent 重复下单两次”这种事故。2.3 第三层能力与工具层skill、tool、MCP 的边界这一层是新手最爱造轮子、也最容易失控的地方。我先把三个词的边界定清楚tool 是原子的函数调用比如“查询天气”“执行一段 SQL”粒度最小、职责单一skill 是打包好的能力单元通常包含提示词、脚本、示例、输入输出校验和失败处理是“能完成一类任务”的封装比如“生成一份周报”可能内部调了三个 toolMCP 是一类接口标准解决的是“能力怎么以统一方式暴露和被调用”的问题让同一份能力能被不同 Agent 复用而不用每家重写一遍适配层。所以“skill 和 agent 的区别”和“skill 和 agent 的区别”这类问题答案不在一个维度上Agent 是决策主体skill 是它能调用的一种能力包。很多人把 skill 当成 Agent是因为某些平台把两者放在同一个界面里展示视觉上扁平了概念上其实有严格的上下级关系。反过来说如果你把一个需要多步判断的任务硬塞进一个 tool 里写出来就是一堆 if-else维护起来极其痛苦而如果你把每个原子操作都包装成独立 Agent系统会被通信开销拖死。粒度失控是这一层最大的坑。注意工具描述description的写法比工具本身更影响成败。模型选哪个工具几乎完全依赖描述文本。我见过最离谱的案例是十几个工具的描述全是“用于处理数据”模型只能随机挑。描述里至少要写清楚这个工具做什么、什么时候该用、什么情况下不要用、入参的含义和取值范围。2.4 第四层记忆与知识层上下文工程的主战场Agent 的“记忆”不是一个东西至少分四类。短期记忆就是当前会话的上下文窗口会话一关就没了工作记忆是任务执行过程中的中间状态比如当前计划、已完成的步骤、临时结论通常存在结构化的状态对象里长期记忆是跨会话保留的信息比如用户偏好、历史结论程序性记忆是你沉淀下来的提示词模板、skill 和流程经验它让 Agent“越来越会干活”而不是“越来越了解你”。这四类混在一起谈讨论必然跑偏。和记忆贴得最近的是 RAG检索增强生成。这里我要说一句可能不太讨喜的话RAG 的效果瓶颈几乎从来不在模型而在检索质量。文档怎么切分、切多大、要不要保留标题层级、embedding 模型用哪个、要不要做混合检索关键词加向量、要不要上重排这些决定了召回的候选中到底有没有正确答案。答案都不在候选里后面的生成模型再强也只能编。新手常见的错误是先把大模型换成更贵的版本结果毫无改善因为病历根本不在医生手上。这一层还有个绕不开的话题是“长上下文能不能替代 RAG”。我的答案是部分替代不能全部替代。当资料量不大、且每次任务都需要看全文时直接把内容塞进上下文确实更简单、更准但当资料是几十万份文档、需要跨文档找证据时检索依然是必需的而且成本差距会大到无法忽视。更现实的方案是混合先用检索缩小范围再把高相关片段放长上下文里做深度推理也就是热搜里提到的“长上下文 思维链”那套组合。2.5 第五层应用与交互层多 Agent 协作与协议登场用户能感知的一切都在这一层对话界面、任务面板、审批流、以及多 Agent 之间怎么配合。多 Agent 的拓扑结构我归成四类主管型一个调度 Agent 分派任务给执行 Agent、交接型前一个 Agent 处理完把上下文交给下一个像接力、流水线型固定顺序各司其职、评审型一个生成一个挑错来回几轮。拓扑本身没有优劣关键看任务能不能被清晰切分。切不干净就上多 Agent结果就是几个 Agent 互相甩锅最后谁也没干活。协作一多就需要标准。A2A 这类协议解决的是“不同来源的 Agent 怎么互相发现和调用”而Agent Card就是其中用来描述身份与能力的“名片”它一般会声明这个 Agent 是谁、能做什么、通过什么端点访问、支持哪些输入输出模态、需要什么认证。协议从早期版本往 1.0 演进主要变化就集中在能力声明的细化和安全协商上——早期版本对认证和权限的描述比较粗跨组织调用时容易出问题。**判断版本差异最快的方法不是背字段而是看它能不能表达清楚“谁能调、调用需要什么凭证、能力边界在哪”。**这三个问题答不上来版本号再高也没用。交互层还有一个正在快速成型的形态让 Agent 操作浏览器或桌面。它的价值在于能接管那些没有 API 的老系统但风险也集中在这里——网页上的任何文字都可能被当成指令这是提示注入最典型的入口。所以这类能力必须配沙箱和操作白名单不能让它自由发挥。2.6 贯穿五层的两条横线安全与评测安全不是某一层的事。模型层要考虑输出合规编排层要考虑权限收口和步骤审计工具层要考虑危险操作二次确认记忆层要考虑敏感信息不落库交互层要考虑输入里的恶意指令。其中最容易出事的是提示注入攻击者把指令混在网页、文档、邮件里Agent 一读到就照做。防御思路不是写一句“忽略恶意指令”的提示词而是结构上隔离——把外部内容和系统指令分开处理让 Agent 明白哪些是数据、哪些是指令同时对高风险动作强制人工确认。评测同样贯穿五层。没有评测的 Agent 项目就是盲开。我一般会建三层评测单元层测单个工具和单个提示词模板在固定输入下的输出是否稳定任务层用一组真实任务测端到端完成率指标包括成功率、平均步数、平均 token 消耗和时延回归层把每次线上出问题的案例固定成测试用例改完必须跑一遍防止改好一个坏掉三个。评测集不用一上来就几百条二三十条覆盖主要分支的真实任务就足够让大部分改动无处遁形。3. 40 概念避坑清单下面这张清单是我按五层架构整理的每一条都写清楚定义、常见误解和实际坑在哪。建议收藏遇到新词先来对号入座。3.1 基础名词组先把“是不是 Agent”这件事判对概念我的理解常见误解与坑Agent能感知环境、自主决策、调用工具、朝目标推进的软件实体把它等同于“聊天机器人”其实关键差别在于会不会自己决定下一步AI Agent强调用大模型作为决策核心的 Agent以为必须全自主实际上绝大多数生产系统里 Agent 只占流程的一小部分Agentic Workflow流程骨架固定但部分节点交给模型决策和纯 Workflow 混为一谈导致评测口径完全不同Workflow路径写死、分支明确被当成过时技术恰恰相反它是可控性的来源Chatbot只做对话不做多步执行被拿来当 Agent 的反义词实际上很多 Agent 的入口就是一个对话界面单 Agent一个决策核心包办全部环节以为单 Agent 一定弱很多场景下它比多 Agent 更准更省多 Agent 协作多个决策单元分工配合任务没切干净就上多 Agent结果是通信开销翻倍、错误互相传染判断“是不是 Agent”我有个简单标准看它有没有一个可以反复执行的循环以及这个循环里下一步做什么是不是由系统自己决定的。是就是 Agent不是就是工作流或者普通程序。这个判断很重要因为它直接决定你要不要做权限收口、要不要建评测集——工作流的测试用例可以写死Agent 的不行。3.2 编排与运行时分词组面试最爱问的一组概念我的理解常见误解与坑Harness模型之外的全部运行时骨架被当成某个具体框架的名字其实它是一种角色谁都能做编排Orchestration决定任务怎么拆、节点怎么连、状态怎么流转只关注画流程图忽略了错误恢复和状态持久化路由识别节点判断当前输入该走哪条分支的环节直接丢给大模型分类延迟和成本都高小模型或规则往往更合适规划Plan-and-Execute先出计划再逐步执行计划一次生成后从不修正执行偏了也不知道回头ReAct边推理边行动观察结果再决定下一步当成万能范式实际上对步骤多的任务容易迷路反思Reflection让模型检查自己的输出并改进无脑加反思结果模型反复推翻已正确的答案成本翻倍Handoff把任务和上下文交给另一个执行者交接时上下文丢失或传全量前者导致重来后者导致超预算Subagent主 Agent 派生出的子执行单元以为派出去的越多越快实际上并行度太高手动排查几乎不可能幂等同一操作重复执行不产生额外副作用只在读操作上做写操作忘了重试就出现重复下单兜底模型没给出可用输出时的备用路径只做重试不做降级模型持续异常时整个流程直接崩这一组里我最想强调的是兜底设计。热搜里那些“生成失败请重试”“执行中断”的抱怨绝大多数是因为系统只有一条路径模型返回 → 解析 → 执行。模型返回空、返回格式不对、返回了不存在的工具名任何一环出问题整个任务就断。合格的写法是三层兜底格式修复试着从输出里抽出结构化内容、有限重试换提示词再试一次最多两次、降级路径走规则或转人工。这三步加起来代码量不大但能把可用性往上抬一个台阶。3.3 能力与工具组别再把 skill 当 Agent概念我的理解常见误解与坑Tool原子函数调用职责单一一个工具干十件事参数列表长得没人会调Skill封装好的能力包含提示词、脚本、校验和 Agent 混为一谈实际上 skill 是被调用方Function Calling模型输出结构化调用请求的机制以为它会自己执行实际执行永远在你自己的代码里MCP能力的标准化暴露与调用接口以为接上就万事大吉忽略了权限和审计工具描述告诉模型这个工具是什么、何时用写得含糊模型只能瞎猜选错工具是最高频故障浏览器操作让 Agent 操作网页完成任务把它当默认方案其实有 API 就别用浏览器贵且脆计算机操作更广义的桌面与系统级操作能力不设沙箱直接放权误删误改风险极高能力白名单明确允许 Agent 使用的工具集合图省事给全量权限出一次事故就够喝一壶注意工具数量不是越多越好。我的经验是单个 Agent 暴露的工具控制在十二个以内再多就分组成 skill 或者拆成子 Agent。工具太多会让模型的选择准确率明显下降而且排查问题时你根本不知道是哪一步选错了。3.4 记忆与知识组概念最容易互相打架的一组概念我的理解常见误解与坑短期记忆当前会话的上下文当成长期记忆用会话一断全丢工作记忆任务执行中的中间状态不落盘进程一重启计划全没了长期记忆跨会话保留的信息什么都往里存噪声越来越大反而拖累效果程序性记忆沉淀下来的技能与经验只沉淀提示词不记录失败案例同样的坑反复踩上下文窗口单次能看到的 token 上限等同于记忆其实只是“眼前可见”长上下文窗口特别大的模型能力以为可以替代检索资料量一大成本和延迟都不可接受RAG先检索再生成效果差就换模型其实应该先看切分和召回切分Chunking把文档切成可检索片段按固定字数硬切句子和表格被拦腰截断混合检索关键词与向量结合只用向量遇到专有名词和编号就召回不到重排Rerank对召回结果做精细排序跳过这一步直接生成前面几十条候选里正确答案排在末尾Embedding文本转向量的模型和对话模型混着选忽略了它是独立的一类模型LLM 与 Embedding 区别一个生成、一个表示面试高频题答不上来通常会暴露对链路理解不完整向量库存向量并做相似度检索上来就搭集群其实几万条数据用轻量方案完全够上下文裁剪超窗口时保留哪些内容简单按时间截断把系统指令和当前任务目标裁掉了这一组里最值得多说一句的是切分。我见过太多项目在切分上偷懒按固定字符数硬切结果一个完整的表格被切成三段检索引擎只召回中间那段模型看到的是一张没有表头的表格输出自然离谱。我的做法是优先按语义结构切标题、段落、列表项为边界保留一定的重叠同时把文档标题路径附加到每个片段前面让片段自带上下文。这一步做对检索效果往往比换更贵的模型提升还大。3.5 协作与协议组名字新但不是全都得用概念我的理解常见误解与坑A2A 协议不同 Agent 之间互相发现与调用自家系统内部通信也上这套纯属增加复杂度Agent Card描述 Agent 身份与能力的名片字段填得很随意跨团队调用时权限和模态对不上协议版本差异早期版本到 1.0 的能力细化只对版本号不看能力声明和安全协商部分是否够用主管型拓扑一个调度者分派任务调度者成了单点它一挂全挂交接型拓扑上下文像接力棒一样传递交接时不做摘要越传越长最后爆窗口评审型拓扑生成与挑错来回迭代没有终止条件两个 Agent 无限对线人机协同关键节点由人确认要么全自动要么全人工没设计中间档多 Agent 我的态度一直比较保守能用单 Agent 加清晰工具解决的不要上多 Agent。多 Agent 的真实价值在于角色冲突的场景比如一个负责产出、一个负责挑错这种对抗性结构确实能提升质量。但如果只是任务步骤多那用工作流拆节点就够了硬拆成多个 Agent 只会让调试难度指数上升——你连问题出在哪个 Agent 上都要花半天。3.6 工程治理组决定能不能上生产的一组概念我的理解常见误解与坑可观测性记录每一步的输入输出与耗时只打日志不做结构化出问题靠肉眼翻Trace 回放把一次执行完整重现不存中间状态问题无法复现评测集一组带预期结果的真实任务全是简单样例上线后复杂场景全崩黄金集稳定不变的基准测试数据被拿去调参后又当评测用等于自己骗自己提示注入外部内容里夹带指令靠提示词防御应该靠结构化隔离沙箱隔离执行环境只在生产开开发环境随便跑习惯养歪最小权限只给完成当前任务所需的权限图方便给全量凭证一次注入就是事故人工确认高风险动作前拦截所有动作都确认用户直接弃用成本监控跟踪 token 与调用费用只看总量不按会话拆找不到烧钱的环节灰度发布小流量验证后再全量直接全量上线出问题只能回滚这一组里我最想提醒的是黄金集的使用纪律。很多团队把评测数据拿去调提示词调完再用同一批数据测指标好看得不得了一上线全线崩。正确做法是评测数据分两份一份可以随便用来看效果的开发集一份锁起来只在发布前跑一遍的验收集。这份验收集每次发布都跑指标掉超过阈值就不许发。这个纪律听起来很笨但它能挡掉绝大部分“改好一个坏掉三个”的情况。3.7 最容易同名踩坑的一组java agent是 JVM 的字节码增强技术用于探针、监控、热更新这类场景和 AI Agent 没有任何关系搜资料时一定要带上限定词否则会得到完全无关的结果。具身智能 agent指的是有物理载体、能感知和作用于真实世界的智能体它的核心难点在感知与控制和大模型 Agent 的技术栈重合度有限别把两者当成同一件事来规划学习路线。pi agent、hermes agent、orca agent这类名字属于产品命名不同产品的架构差异可能很大判断它们的价值要看底层是哪套运行时、支持哪些能力接入方式而不是看名字。还有一类是客户端与服务端之分桌面端产品只是外壳真正的编排逻辑可能在云端这直接决定了你的数据流向和合规边界选型时必须问清楚。上面这张清单加起来超过四十条概念覆盖了从基础名词到工程治理的主要盲区。我的建议是不要背而是把它们贴到五层架构上去理解一个词落在哪一层它的价值、风险和维护方式就基本确定了。4. 从零上手Agent 开发的学习路线与实操节奏4.1 阶段一把单 Agent 跑通别急着上框架入门阶段最忌讳的就是一上来挑最复杂的框架。我的建议是用最朴素的方式写一遍一个主循环、三到五个工具、一个简单的提示词模板、一份结构化的运行日志。目标不是做出惊艳的东西而是亲手体会到三件事模型是怎么决定调用哪个工具的、工具返回结果是怎么被塞回上下文的、循环什么时候该停。这三件事搞明白了后面换任何框架都是换皮。这个阶段的具体任务是做一个“能查资料并给出带出处结论”的小助手。你需要准备一份几百字到几千字的本地资料做一次最简单的检索让 Agent 先检索再回答回答里要标出引用的是哪一段。这个练习的价值在于它同时踩到了检索、工具调用和格式约束三个点。写完你会发现最让人头疼的不是模型而是“模型有时候不按格式输出”这就是你第一次真正理解 harness 为什么重要。我建议这一步自己写格式化校验和一次重试逻辑不要用框架的封装亲手写一遍才知道坑在哪。4.2 阶段二把工具和记忆做扎实练的是工程手感单 Agent 跑通之后把精力放在两件事上工具描述的质量和记忆的分层。工具有了明确描述之后模型选错的概率会明显下降你可以做一个小实验同一批任务用模糊描述和详细描述各跑一遍把选错工具的次数记下来对比。这个实验做一次你以后写描述就再也不会敷衍了。记忆这块先实现工作记忆的持久化把任务状态写到一个可以恢复的地方进程重启后能接着跑。这一步做完你就解决了前面提到的“执行中断就得从头再来”的问题。还有一个必须练的能力是上下文裁剪。做法很直接给上下文设一个预算超出时按优先级保留——系统指令最优先当前任务目标其次最近的几轮交互再次最早的交互做摘要压缩。写一个简单的裁剪函数跑一批多轮对话看效果你会发现有些任务在裁剪后反而变好了因为噪声少了。这个反直觉的发现是很多人从新手进阶到熟练的分水岭。4.3 阶段三多 Agent 与生产化考的是判断力到了这一阶段重点不再是“能不能跑”而是“该不该这样跑”。我建议先做一次成本与延迟的基线测量同一个任务单 Agent 方案和多 Agent 方案各跑二十次记录成功率、平均步数、平均耗时和费用。数据摆出来之后很多争论会自然消失。多数情况下你会发现简单任务上单 Agent 全面占优只有在需要角色对抗的复杂任务上多 Agent 才有优势。这个结论比任何人的经验之谈都可靠。生产化要补的是另外几块可观测性每一步的输入、输出、耗时、token 消耗都要落库最好能一键回放、权限收口工具按角色分组高风险工具走确认流程、灰度与回滚新提示词和新逻辑先在小流量上验证、成本预警按会话维度监控异常会话自动告警。这几样东西都不难做难的是坚持做。我见过不少项目在演示阶段光鲜亮丽一上真实流量就各种超支和事故追根到底就是这几块欠账。4.4 常见故障速查表与踩坑心得现象大概率原因处理方式Agent 一直不结束反复调用同一个工具缺少终止条件或状态没有更新加步数上限和状态去重检查工具返回是否被正确写入状态模型输出空或者提示重试输出被截断或格式校验过严放宽校验、提高输出长度上限、加一次格式修复重试执行中途报错后无法恢复状态没落盘每步结束持久化状态恢复时从断点继续选错工具工具描述含糊或数量过多重写描述工具分组到十二个以内检索不到关键信息切分粗暴或缺少混合检索按语义切分、保留标题路径、补关键词检索和重排回答编造事实提示词鼓励“尽量回答”明确要求找不到就说找不到并强制输出引用来源成本突然飙升上下文无限增长加裁剪预算按会话监控 token任务交接后重复劳动交接时上下文丢失交接时传摘要而非全量明确已完成项上线后效果比测试差很多评测集过于简单补真实复杂样例建立验收集高风险操作误执行无确认流程危险动作二次确认沙箱内先演练我的踩坑心得Agent 项目里最贵的不是模型调用费而是排查问题的时间。所以从第一天起就把每一步的输入输出、耗时和 token 消耗结构化记录下来。哪怕只是一个落库的 JSON也比事后靠回忆猜测省下几十个小时。我吃过这个亏一个线上问题查了两天最后发现只是工具返回的一个字段名拼错了。5. 面试考点与团队落地八股背后的真实问题5.1 高频问题的“标准答案”之外现在 Agent 方向的面试题高度集中在几组对比上Agent 和 Workflow 的边界、harness 和 agent 的关系、skill 和 tool 的区别、LLM 和 Embedding 的分工、长上下文能不能替代检索、多 Agent 什么时候该用、怎么防提示注入。这些题目本质上考的不是记忆力而是你有没有真的动手做过。比如“怎么防提示注入”背一句“在提示词里要求忽略恶意指令”基本就废了面试官想听的是结构隔离、权限收口和人工确认这三个层次。再比如“长上下文能不能替代 RAG”答“能”或者“不能”都不完整能说清楚“小资料量可以、大规模文档不行、混合方案最现实”才算过关。如果我要出题我会给一个具体的失败案例让人现场分析一个 Agent 在测试环境表现很好上线后成功率掉了一半可能是哪些原因这题几乎能把五层架构全考一遍——模型层可能是数据分布不同编排层可能是重试策略在真实延迟下失效工具层可能是某个接口在高并发下限流记忆层可能是上下文裁剪把关键信息裁掉了交互层可能是真实用户的表达更口语化。能按层次系统排查的人和只会说“换个模型试试”的人差距一眼就看出来了。5.2 团队选型与推进节奏团队落地我最反对的做法是“先选框架再找场景”。正确的顺序是先找一个边界清晰、结果可验证、失败代价可控的场景做完再谈平台化。什么叫边界清晰就是这个任务有明确的输入和明确的成功标准比如“从一批工单里提取结构化字段并归类”而不是“帮我提升团队效率”。什么叫失败代价可控就是它出错的时候不会造成资金损失或数据泄露能兜得住。这两条都满足项目成功率会高很多。选型时我会重点看四件事编排层能不能自己控制循环、重试、状态是否透明可改能力接入是不是标准化新增一个工具的成本有多高可观测和评测是不是内建有没有 trace 和数据集管理权限和审计能不能收口高风险动作能不能拦住并留痕。至于模型选谁反而是最后才定的因为模型可以换前面这四件事换起来伤筋动骨。团队节奏上我的建议是第一个月只做单 Agent 加三五个工具第二个月补记忆和评测第三个月再考虑灰度上真实流量多 Agent 放到最后除非有明确证据说明单 Agent 撑不住。最后再分享一个小技巧给 Agent 项目建一份“故障日志”每次线上出问题就往里记一条写清楚现象、原因、修复方式和复现用例。三个月后你回头看会发现大部分问题都是重复的几类而这份日志就是你团队最值钱的资产——它比任何框架文档都更贴合你们自己的业务。Agent 这个东西热闹的概念一大半会过时但排查问题的经验不会。
