做了快两年的Agent开发有个感受越来越深这行看着门槛高框架天天出新模型月月换代但真到干活的时候翻来覆去要解决的其实是同一批问题。最近带新人我干脆把它们归纳成了五件事——目标拆解、模型能力边界、记忆管理、工具调用、框架与多智能体协作。想明白这五件事Agent开发的基本盘就算稳了。这篇文章就按这五件事的顺序往下捋。不论你是刚接触Agent开发的大模型工程师还是想从业务侧转过来的产品/后端同学只要搞清楚每件事背后“为什么重要、怎么落地、坑在哪”绝大部分Agent项目的坑你都能提前绕开。1. 目标定义与需求拆解别上来就调Prompt1.1 Agent开发失败的头号原因需求根本没定义清楚我见过太多团队拿到需求第一反应是“来先跑个大模型试试”试完发现效果不行就开始疯狂调Prompt、换模型、加few-shot折腾两周最后项目组集体陷入“玄学调参”状态。这是Agent开发里最典型的死法。问题不出在模型出在目标没定义清楚。早期我做客服Agent时业务方给的原始需求只有一句“让AI帮客户解决问题。”这句话看起来没问题但你细想——客户的问题是什么类型退换货、物流查询、投诉、售前咨询每种类型的处理流程完全不同。AI能查哪些系统能改哪些订单状态哪些场景必须转人工如果这些问题不回答模型就只能自己瞎猜而大模型最擅长的就是“一本正经地给出错误答案”。我现在的做法是动手写任何Prompt之前先画一张任务边界图。把用户请求拆成“用户旅程 × 任务边界 × 验收标准”三个维度。用户旅程用户从哪个入口进来会带着什么意图可能经历哪几步任务边界Agent能自主完成哪些步骤哪些步骤必须停下来等用户确认哪些必须转人工验收标准每个任务在什么条件下算“成功”输出什么格式失败时怎么兜底这一步做完你会发现后续所有的Prompt设计、工具接入、评测用例全都有了具体的靶子。说白了Agent开发不是让模型自己找活干而是你先把地圈好让模型在圈出来的范围内干活。1.2 三个实操工具用户故事地图、决策表、验收用例目标拆解听起来虚但落地有几个顺手工具。第一是用户故事地图。把用户从进入到问题解决要经历的步骤全部列出来用便利贴或者在线白板逐行排开标出哪些环节由Agent完成哪些由API完成哪些由人工兜底。这张图一画各方对“Agent到底管到哪一步”立刻达成共识比十次会议都管用。第二是决策表。这是做复杂业务Agent的秘密武器。我做过一个数据查询Agent用户可能同时提到“按部门汇总上月销售额”和“对比去年同期”这种请求落在Excel自动化的世界里就是一条SQL但落在Agent世界里模型要在“理解意图、判断维度、选择指标、生成查询参数”四层任务里各走一遍。决策表就是把每个组合可能性提前列清楚什么意图匹配什么参数集合参数缺失时该问哪一句话模糊时该给什么选项。有了这张表Prompt里的指令就不是模型自由发挥而是“查表填参”。第三是验收用例。没有验收用例的Agent开发等于没有刹车就上高速。每个任务至少准备三个正向用例、两个边界用例和一个失败用例。不要以为这很麻烦这些用例在后续换模型、改Prompt、加工具时能帮你节省几十个小时的回归测试时间。1.3 复盘心得范围蔓延是Agent项目的隐形杀手踩过几次坑之后我发现Agent项目的范围蔓延比传统软件项目严重得多。原因在于传统软件的功能边界是代码写死的而大模型的泛化能力会让业务方误以为“什么都能做”。业务方看到Agent能查天气就会追问能不能查股价看到能查股价就想让它顺便写个复盘报告。每加一个能力背后都是一套新的工具接入、一套新的Prompt逻辑、一套新的评测集成本是叠加的。所以我现在接需求的第一步就是砍需求。不是所有需求都值得做成Agent凡是人工能在30秒内做完、且规则固定的操作都先别让Agent上。Agent最适合解决的问题有三类流程长但步骤明确的多步任务、信息散落在多个系统里需要聚合查询的任务、以及需要根据上下文动态生成内容的生成式任务。把目标定义在这三类里项目成功率能翻一倍。2. 大模型能力边界决定Agent天花板的不是Prompt2.1 能力边界测试清单先给模型建档再谈调优很多Agent开发者的直觉是效果不好就继续调Prompt很少停下来问这个任务模型到底行不行我做Agent开发的第二条心得就是先把模型的能力边界摸清楚。大模型在语言理解、文本生成、内容总结上的能力毋庸置疑但Agent开发里真正消耗时间的是三个“偏科”场景结构化工件输出、工具参数补全、以及复杂逻辑判断。先说结构化工件输出。在Agent开发里模型几乎总是需要输出JSON。但实测下来不同模型在“稳定输出合法JSON”这件事上差距巨大。有的模型3次里有1次会在JSON外面加一段解释性文字有的模型会在JSON里写注释有的会把数字字段的字符串格式搞混。我的建议是正式用某个模型之前先跑50条结构化输出测试样例统计它的合法JSON率、字段缺失率和类型错误率。低于95%合法率的模型就别让它直接输出JSON要么用JSON模式约束要么让模型先生成文本再校验。再说工具参数补全。Agent调用工具时模型需要把用户的自然语言意图映射成工具的具体参数。比如用户说“把上周三的会议纪要给产品组的人”模型要正确解析出“上周三”具体是哪一日还要自动把“产品组的人”映射成具体的邮箱列表。这个链路里模型的能力是“做语义映射”真正的时间处理、通讯录匹配必须靠代码来完成。如果你发现模型经常把日期算错那不是Prompt的锅是你根本不应该让模型算日期。最后是复杂逻辑判断。大模型在“对错判断”类任务上表现不错但在“多条件排序”“区间计算”“精确计数”上经常翻车。我搭过一个数据看板Agent用户问“哪两个连续月份的销售额增长率最高”模型给出的结论经常是拍脑袋式的。解决方法是所有需要精确计算的逻辑全部外包给代码和SQL模型只负责把用户意图转成查询条件。2.2 用评测集给模型建档建立回归基线给模型建档的最佳方式是一套持续维护的评测集。这不复杂就是一组常见输入加上期望输出分两类单元评测和回归评测。单元评测覆盖每个核心任务的功能正确性。回归评测则用来防退化——每次换了模型版本、调整了Prompt模板或修改了工具Schema之后拿之前的样例集全部重跑一遍看有没有把以前对的事情做错。我维护的那套回归评测集大概两百条覆盖了客服、数据查询、办公自动化三个场景。每次换模型跑一遍全量回归拿到准确率对比表再决定要不要升级。有一次我们拿新发布的一个模型做评测对话体验明显更顺滑但回归集里“单证编号识别”的准确率从96%掉到了87%就是因为新模型在长数字识别上表现不如老版本。如果没有回归基线这种退化在线上可能要几周才会被用户骂出来。评测集的维护成本不低但对Agent开发的价值远超成本。它让团队从“今天调了个Prompt效果好了一点”的直觉模式变成了“这个改动让准确率从93.2%降到92.8%需要回滚”的科学模式。我建议从项目第一天就建哪怕只有二十条用例也比没有强。2.3 实操案例为什么加提示词不如换模型去年有一个需求是做合同审查Agent目标是让AI找出合同里缺失的关键条款。我们用某个开源模型试了几轮无论怎么加Prompt、加示例模型总是漏掉“违约赔偿”条款的缺失检查偶尔还会把“建议咨询律师”这种原文本来就有的内容判定为缺失。后来我们换了另一个同级别的模型同样的Prompt漏检率直接降了三分之一。原因不是新模型更聪明而是旧模型训练语料里涉及合同的内容较少对格式的敏感度天然不足。那次之后我得出一条经验如果模型在某个领域的表现和你的预期差了一个量级优先换模型而不是优先调Prompt。Prompt调整更多是在能力边界内把表现从“及格”推向“优秀”而你需要的不是“优秀”是“从零到一”时模型选型才是真正的变量。这也是为什么我一直强调要常留一个模型候选池别把整体架构死绑在一个模型上。3. 记忆与上下文管理Agent能不能“记住事”是分水岭3.1 从“聊天记录”到三层记忆结构初级Agent和成熟Agent的最大区别就是看它有没有记忆。很多人在早期做Agent的时候直接把所有聊天记录全部塞进Prompt里让模型“记住”上下文。但这有个致命的Token上限问题上下文稍微一长调用成本暴涨不说模型还会在无关的历史信息里“迷路”。我的做法是把记忆拆成三层短期记忆、工作记忆、长期记忆。短期记忆就是当前会话里最近的若干轮对话直接用最新对话内容做一个固定轮次的滑动窗口保证模型看到的始终是最近的状态。工作记忆是当前任务执行过程中产生的临时状态比如Agent正在处理一个多步订单流程已经确认了商品、数量、地址这些状态应该存在程序里的一个结构化数据结构中而不是靠模型去“回忆”用户刚才说过什么。长期记忆则是对用户偏好的抽象沉淀比如“用户习惯看简洁回复”“用户偏爱按月汇总统计数据”。这类信息需要在会话结束时由Agent触发一次总结写入向量数据库或结构化存储下次对话再检索相关部分注入上下文。三层记忆各司其职短期保新鲜、工作保准确、长期保个性。很多Agent项目一开始就急着上向量数据库结果连短期状态都没管好这就属于本末倒置。3.2 上下文压缩与检索策略在Token预算里做设计长期记忆必然涉及检索和上下文压缩这块有几个实操经验。第一能摘要的别全文塞。每轮会话结束时让模型把对话内容总结成结构化要点存下来下次检索到的就是这个摘要而不是原始聊天记录。摘要占用的Token往往只有原文的十分之一而信息密度反而更高。第二检索优先级要高过长度。向量检索召回的内容要按相关度排序后截断而不是一股脑塞给模型。我的习惯是先按召回分数取Top5再把召回内容按时间倒序整理最后控制在模型上下文窗口的四分之一以内。第三给记忆打时间戳。用户的偏好是会变的三个月前的“喜欢看长报告”可能现在已经不适用了。所有长期记忆条目都带时间戳检索时按时间加权旧记忆的权重随时间衰减。这个细节让我避开了好几次“用户都改需求了Agent还在按老偏好办事”的尴尬。我还测过不同压缩策略的效果发现让模型“边对话边总结”比“会话结束后一次性总结”质量更高。原因也很简单对话过程中模型对关键信息还留有注意力事后一次性总结容易丢掉上下文里的重点。3.3 记忆污染与“记错事”的坑记忆管理的另一面是防污染。Agent很容易把一次性的临时信息误当成长期偏好存下来或者在一次不成功的交互里把错误的结论记进长期记忆。我遇到过最典型的例子用户在某次对话里随口说了一句“最近在减肥”Agent就把“用户正在减肥”写进了长期偏好之后每个回答都带“建议您注意热量”。问题是用户那次只是帮家人问的。从那以后我规定只有用户在明确表达偏好、并且同一偏好在不同会话中出现两次以上才允许写入长期记忆。普通对话内容最多存进短期记忆和工作记忆会话结束自动丢弃。记忆的数据安全也要注意。涉及个人信息和敏感数据的记忆条目一定要加密存储并在对话中支持“忘记我”指令。否则Agent上线的合规风险比功能Bug还致命。4. 工具调用与Function Calling让Agent真正“动手”4.1 工具是Agent能力的延展但设计工具才是核心如果说大模型是Agent的大脑那么工具就是Agent的手脚。没有工具的Agent只会“说”有了工具的Agent才会“做”。但工具设计里藏着一个常见的误解以为工具越多越好。实际上每多一个工具模型在决策时就多了一个分叉选项误选工具的概率也随之上升。我的工具设计原则有三条。第一单一职责。一个工具只做一件事“查询订单”和“取消订单”一定是两个工具不要合成一个带参数的“订单操作”。第二参数Schema要足够简单。模型对复杂嵌套参数的遵循能力有限能只传两个字符串参数就别设计五个字段加两个嵌套对象。第三返回结构要稳定。工具返回的数据建议统一封装成固定的JSON结构带一个success字段和一个error字段模型判断“工具是否成功”的成本会大幅降低。这里直接给个示例。下面是一个“查询订单状态”工具的简化Schema{ name: query_order_status, description: 根据订单号查询订单的当前状态, parameters: { type: object, properties: { order_id: { type: string, description: 用户提供的订单号例如 DS202405001 } }, required: [order_id] } }设计得足够简单模型才不容易把参数传错。4.2 工具编排的两种形态ReAct和Plan-and-Execute工具再多模型也得知道“先调用谁、后调用谁、调用失败怎么办”。主流做法有两种。一种是ReAct模式让模型边推理边行动——先分析用户意图决定调哪个工具拿到结果后再决定下一步。这种模式适合任务链路不确定、需要动态决策的场景比如“帮我查一下最近的航班并预订”模型需要先搜索航班再根据结果选择预订还是问用户。另一种是Plan-and-Execute模式模型先一次性生成完整的执行计划把整条任务拆成有序的步骤然后按计划逐步执行。这种模式适合流程稳定的多步任务比如“生成月度销售报表”计划基本固定查数据、汇总、生成图表、写报告不需要每步都让模型重新决策。我的选择原则是任务步骤少于三步、且依赖用户实时反馈的用ReAct任务步骤多于三步、且流程基本确定的用Plan-and-Execute并且把计划交给代码来执行模型只做一次规划。你可能会问用传统代码写死流程不就行了对对于完全固定的流程代码确实比模型更可靠。Plan-and-Execute模式的价值在于规划这一步可以由模型根据用户语义动态调整比如用户加了一句“只要华东区的数据”模型的计划就会自动带上区域过滤条件这部分动态性是纯代码难以覆盖的。4.3 工具调用的五大实战坑工具这块我踩过不少坑总结五个最常见的坑一模型输出的JSON不合法。这是老生常谈了模型生成的参数经常带多余引号或注释。我的处理方案是所有工具调用参数必须先做一次JSON解析解析失败就重试一次再失败就让模型“只输出纯JSON”不要解释。坑二参数幻觉。模型在用户没有提供某些参数时会自作主张编一个值。比如用户只说“查订单”模型就猜了一个订单号。解决方案是在工具描述里写明“如果用户未提供该参数请先向用户确认不得猜测”。坑三循环调用。Agent可能会在两个工具之间反复横跳出不来。我的兜底方案是给单次任务设置最大工具调用次数上限一般5到8次达到上限直接转人工或返回默认结果。坑四权限边界不清。不是所有工具都应该让模型随意调用。删除类操作、扣款类操作、对外发送消息类操作默认应该加一道确认环节让模型先输出“我准备执行以下操作”供用户确认。坑五工具执行超时。外部API的响应不可控工具调用必须包一层超时控制超时后给模型返回明确错误信息避免整个Agent卡死。这块可以用下面的表格作为排查清单现象可能原因常规处理工具返回无法解析服务端返回了空JSON或非法格式增加返回内容校验超时/空值统一返回失败态模型反复调用同一工具上一步结果未被正确传递或理解检查上下文里是否保留工具返回结果必要时截断历史参数明显不合理模型幻觉参数加强工具描述约束不支持自动补参数调用后毫无反应外部API超时未兜底给工具调用加超时和重试机制误调敏感工具工具选择策略过于宽松按操作风险分级高风险操作加用户确认环节5. Agent框架与多智能体协作工程化的最后一公里5.1 主流框架怎么选别被新框架绑架自己从零写一个Agent当然可以但工程化落地时选一个合适的框架能省掉大量琐碎工作。现在社区里常见的主流方案各有所长。这里有我最近梳理的一个选型对照表方便你按自己的场景选框架核心特点适合场景上手难度LangGraph基于图结构编排Agent流程支持状态管理和条件分支可观测性好复杂多步任务、需要精细控制流程的工程化项目中高AutoGen强调多Agent对话协作适合研究探索型场景学术研究、快速原型验证中Dify偏应用平台化提供可视化编排、知识库、工作流自带运维界面企业内部工具、业务侧快速上线低扣子(Coze)低门槛智能体搭建平台内置大量插件能力非技术用户、轻量级智能体快速搭建低自研轻量框架自己封装Prompt管理、工具注册、记忆逻辑深度定制、需要完全掌控链路的核心业务高我的建议是业务逻辑复杂、链路调度要求高的项目优先选偏代码型的框架因为你迟早要自定义节点。业务偏流程化、内部工具单一的可以用可视化平台快速搭起来跑MVP。但无论选哪个有一点不能妥协——必须有日志和Trace能力。没有Trace的Agent项目出了问题等于盲人摸象。5.2 多智能体协作不要为了拆分而拆分“多Agent”听起来比“单Agent”高级但实际上多Agent系统每一次状态传输都有损耗模型之间的信息在传递过程中会失真而且整体延迟和成本都会成倍增加。我见过一个项目客服场景里拆了五个Agent意图识别Agent、订单查询Agent、物流查询Agent、售后Agent、聊天Agent感觉架构很专业。结果实际运行下来意图识别Agent把“我的快递什么时候到”误判成了订单查询消息传到物流Agent时连用户的原始地址信息都丢了最后用户被反复问“请问您要查什么”。我现在的经验是能用单Agent解决的绝不拆多Agent必须拆的优先按“职能边界”拆而不是按“关键词”拆。比如客服场景里只需要拆三个前台接待负责所有意图识别和分发能力越强越好、业务处理负责查询和操作、人工兜底复杂问题升级。Agent之间传递的不应该是自然语言描述而应该是标准化的结构化消息包含会话ID、用户意图、必要的参数数据和时间戳。多Agent的协作模式也是避坑重点。常见的有三种顺序模式A处理完交给B适合流水线型任务如内容审核后发布。分层模式一个“主管”Agent负责任务分配多个“执行”Agent各干各的适合任务复杂且有多个独立子需求的情况。辩论模式多个Agent就同一问题各自给出观点和评判适合做内容评审、方案对比这类需要多视角的任务。无论哪种模式都要给每个Agent定义清楚的职责边界和退出条件——什么情况下这个Agent可以结束任务什么情况下必须请求人工介入。否则多Agent协作就成了“多Agent甩锅”。5.3 可观测性与排查打印每一步的思维过程Agent开发的调试体验和传统开发差异很大。传统代码是确定性的报错就是报错栈信息一打就能定位。Agent是概率性的同一输入可能走两条完全不同的调用链路错误往往不是“崩溃”而是“悄悄做错了”。所以我对可观测性的要求是“每一步都要留痕”。具体来说每个Agent节点的日志至少包括模型输入Prompt、模型输出、选择的工具、传入参数、工具返回结果、下个节点的决策依据。这些信息全量写入日志系统线上出问题才能回放。另外我会为每个任务生成一个全局的Task ID贯穿整个Agent对话和工具调用的全过程。排查时直接按Task ID搜索所有步骤一目了然。这个习惯在线上事故处理时救过我很多次有一次用户反馈“Agent把订单取消了”按Task ID回放后发现是因为用户上一条消息里说“把上一单取消吧”模型引用了过期的短期记忆把新订单取消了。没有回放日志这个Bug根本无从查起。现在还可以用LLM来辅助分析日志——把一段出错的Agent链路日志扔给另一个大模型让它总结异常环节。实测下来它对错误定位的准确率相当不错可以当一个便宜的“AI排查助手”用。最后说点个人体会做了将近两年Agent开发如果只能给一条建议我的回答是把第五件事放最后把第一件事放最前。框架会过时模型会更新但“把目标拆清楚”和“把模型边界摸透”这两件事永远不会过时。我见过太多团队一上来就研究多Agent协作、讨论最新的Agent框架最后却在一个最简单的需求定义上翻车。真正稳定的Agent从来不是靠某个神奇框架或某个“最强模型”撑起来的而是靠扎实的需求分析、严谨的评测集、清晰的任务边界以及一层一层兜底的异常处理堆出来的。最后再分享一个实践细节在每个Agent项目的文档首页写清楚三行字——这个Agent不做什么、遇到什么情况必须停下来、什么情况必须转人工。这三行字比任何技术选型都值钱。祝你在Agent开发这条路上少踩坑多沉淀。