做了近两年的Agent开发从最开始用LangChain拼Demo时的兴奋到后来在Spring AI里被各种配置和抽象层折磨再到现在带团队落地Agent项目回头看真正需要掌握的东西其实就那么几件。市面上教程铺天盖地框架文档翻来覆去但很多人学完还是不知道怎么把一个Agent从能跑做到能用。这篇内容不讲某个框架的API怎么调而是把这近两年踩过的坑、想明白的事拆成五件真正要学的事每一件都配着我实际项目里的场景和判断逻辑。不管你是刚接触Agent开发还是已经用LangChain、Spring AI写过几个Demo想往生产环境推这五件事都值得对照着捋一遍。1. 先搞清楚Agent到底在解决哪类问题1.1 别把Agent当成更聪明的函数我见过太多人一上来就问LangChain怎么用Spring AI的ChatClient怎么配然后拿一个问答场景套上去跑通了就觉得自己会Agent开发了。这其实是在用调API的思路做Agent方向就偏了。Agent的本质不是输入问题输出答案而是让模型在一个循环里自主决定下一步做什么。普通函数调用是你写死逻辑先查数据库再拼字符串最后返回。Agent是你给模型一个目标、一组工具、一个停止条件然后它自己决定先调哪个工具、拿到结果后要不要再调一次、什么时候算完成。这个区别决定了你学Agent的第一件事不是学框架而是学会把一个业务问题拆成目标工具判断条件三件套。举个例子我做过一个合同审核的Agent目标是从合同文本里找出风险条款工具包括读取PDF检索法规库比对历史合同判断条件是风险条款全部标注且给出依据。这三样定义清楚了用LangChain还是Spring AI其实差别不大定义不清楚换什么框架都是白搭。1.2 哪些场景适合Agent哪些纯属自找麻烦不是所有任务都值得上Agent。我总结了一个简单的判断标准场景特征适合Agent不适合Agent步骤是否固定步骤动态依赖中间结果步骤固定可预先编排工具调用次数不确定可能多次固定一两次错误容忍度可重试、可回退必须一次成功输出格式相对灵活严格结构化比如根据用户描述生成一份周报这种步骤基本固定用Prompt模板加一次模型调用就够了硬套Agent反而增加不确定性和成本。而帮我在多个数据源里排查一个线上问题这种排查路径依赖每一步的发现就非常适合Agent。我踩过的一个坑是早期做一个数据清洗Agent本来规则很明确非要用Agent让它自主决定清洗策略结果每次跑出来的清洗结果都不一致调试了两周最后退回成固定Pipeline十分钟搞定。Agent的价值在于处理不确定性如果你的问题本身没有不确定性就别引入它。1.3 从能跑到能用中间隔着什么Demo能跑和线上能用中间隔着的是可控性。Demo里模型调错工具无所谓重跑一次就行线上调错工具可能触发一次真实的退款、发一封错误的邮件。所以学Agent的第二层认知是Agent开发的核心工作量不在让它动起来而在让它在该停的时候停、该问的时候问、该错的时候错得可控。这就引出后面四件事工具怎么设计才不容易被误用、上下文怎么管理才不会越跑越乱、多Agent怎么协作才不互相打架、以及怎么测试和观测一个概率性的系统。这五件事是一条线缺一件Agent就停在Demo阶段。2. 工具设计Agent能力的天花板由它决定2.1 工具不是越多越好而是越不容易被误用越好刚开始做Agent时我恨不得把公司所有API都封装成工具塞给模型觉得工具越多能力越强。结果模型在十几个工具里反复横跳选错率极高。后来才明白工具设计的核心不是数量而是每个工具的意图清晰度。什么叫意图清晰就是模型只看工具名和描述就能准确判断这个场景该不该用它。我现在的做法是工具名用动词对象结构比如search_contract_by_id而不是contract_tool描述里写清楚什么时候用、什么时候不用而不只是功能参数尽量少必填参数控制在3个以内返回值结构化避免让模型去解析一大段自然语言举个实际对比。早期我写过一个工具描述是查询合同信息模型经常在只需要合同金额的时候也去调它拿回一大堆无关字段。改成根据合同ID查询合同的签署方和金额仅在已知合同ID且需要核对金额时使用之后误调用率明显下降。2.2 工具粒度的取舍粗一点还是细一点这是被问得最多的问题之一。我的经验是优先做业务语义级的工具而不是API级的工具。比如后端有一个/api/order/detail接口你不要直接把它封装成get_order_detail丢给模型而是想清楚Agent在这个业务里真正需要完成的动作是什么。如果Agent的任务是处理用户退款咨询那工具应该是check_refund_eligibility判断是否符合退款条件而不是让模型自己去调订单详情、再调退款规则、再自己判断。原因很简单把业务判断逻辑放在工具里代码里比放在模型的推理里可靠得多。模型擅长的是决定调用哪个工具不擅长精确执行多步业务规则。我见过太多项目把本该写死在代码里的规则交给模型推理结果就是线上时不时出幺蛾子。当然粒度太粗也有问题——工具变成一个黑盒模型无法根据中间结果调整策略。折中方案是主流程用粗粒度工具需要模型介入判断的地方暴露细粒度工具。2.3 工具报错怎么返回直接决定Agent会不会发疯这一点极少有人讲但极其重要。工具执行失败时你返回给模型的内容直接决定它下一步的行为。我踩过的坑工具抛异常后我把原始堆栈直接返回给模型结果模型看到一堆英文报错开始胡乱重试甚至编造参数。后来改成结构化错误返回{ success: false, error_type: NOT_FOUND, message: 未找到ID为12345的合同请确认ID是否正确, retryable: false, suggestion: 请向用户确认合同ID }关键字段是retryable和suggestion。模型看到retryable: false就不会无脑重试看到suggestion就知道下一步该干嘛。实测下来加了这两个字段之后Agent在工具报错后的发疯率下降了一大半。提示工具返回里永远不要暴露内部堆栈、数据库字段名、服务器路径这类信息一是模型可能拿去做奇怪的事二是这些信息可能通过Agent的输出泄露给用户。3. 上下文管理Agent跑着跑着就失忆或跑偏的根因3.1 上下文不是越长越好而是要该记的记该忘的忘Agent和普通对话最大的区别是它会跑很多轮每轮都产生工具调用和结果。如果不加管理上下文会迅速膨胀然后出现两个典型症状一是模型开始忽略早期的重要指令二是token成本飙升。我在一个数据分析Agent上吃过这个亏。它需要连续调用七八个工具查数据跑到第五轮的时候模型已经忘了最初用户说的只看华东区。原因就是中间塞了太多工具返回的原始数据把最初的指令挤到了注意力边缘。解决办法是分层管理上下文系统层角色、核心约束、工具定义永远保留任务层当前目标、关键约束如只看华东区显式重述历史层工具调用记录做摘要压缩临时层当前轮的原始数据用完即弃具体操作上我通常会在每轮循环开始时把任务层的关键约束重新拼进Prompt而不是指望模型自己记住。这看起来笨但极其有效。3.2 工具返回结果要不要全塞进上下文不要。这是另一个高频坑。工具返回的原始数据往往很长比如一个查询返回50条记录全塞进去既浪费token又干扰模型判断。我的做法是在工具层做预处理工具返回给模型之前先做一次筛选或摘要。比如查询返回50条订单工具内部先聚合成共50条其中异常3条异常ID为...再返回给模型。模型需要的是决策依据不是原始数据。如果确实需要保留原始数据供后续使用就存到外部比如一个临时的state对象或缓存上下文里只放一个引用ID。模型需要时再通过工具去取。这就是所谓的上下文与状态分离——上下文放模型需要知道的状态放系统需要记住的。3.3 循环终止条件Agent什么时候该停Agent跑飞最常见的原因就是没有明确的终止条件。模型会一直觉得我还能再调一次工具然后无限循环。终止条件要设计成多层的硬性轮次上限比如最多10轮到了就强制停目标达成判断模型显式输出任务完成信号无进展检测连续两轮工具调用结果相同或高度相似判定卡住停止成本上限token消耗或工具调用次数超过阈值停止我一般把这四个都配上。硬性上限是兜底目标达成是正常出口无进展检测防止死循环成本上限防止烧钱。少任何一个线上都可能出问题。注意终止后要给用户一个明确的交代而不是静默停止。比如我已尝试X种方式未能完成Y建议您...这比直接卡住体验好得多。4. 多Agent协作什么时候该拆拆了怎么不打架4.1 单Agent搞不定的时候先想是不是Prompt的问题很多人一遇到复杂任务就想上多Agent觉得分工协作听起来更高级。但我的经验是大部分所谓需要多Agent的场景其实是单Agent的Prompt没写好或者工具没设计好。在拆多Agent之前先问自己三个问题单Agent的上下文是不是太长了如果是先做上下文压缩是不是工具太多导致选择困难如果是先做工具分组或路由是不是任务本身有明确的阶段划分如果是才考虑拆真正适合多Agent的场景是子任务之间需要不同的人格或权限。比如一个Agent负责和用户对话需要友好、耐心另一个Agent负责执行敏感操作需要严格、谨慎这两者的行为准则冲突放在一个Agent里会互相干扰这时候拆开才合理。4.2 主从模式 vs 对等模式怎么选多Agent协作主要有两种拓扑模式结构适用场景风险主从Orchestrator-Worker一个主Agent调度多个子Agent任务可分解、子任务相对独立主Agent成为瓶颈对等Peer-to-PeerAgent之间互相通信需要协商、辩论的场景容易陷入无限对话我90%的项目用的是主从模式。主Agent负责理解目标、拆解任务、分发给子Agent、汇总结果子Agent只负责执行自己那块不关心全局。这种结构可控性最强因为决策权集中在主Agent子Agent的行为边界清晰。对等模式我只在一个方案评审的场景用过——让两个Agent分别扮演提出方案和挑刺的角色互相辩论。这种模式很有意思但极难控制很容易两个Agent客套半天或者吵起来没完。用的话一定要设对话轮次上限。4.3 Agent之间传什么不传什么多Agent协作最容易出问题的地方是信息传递。传多了子Agent被无关信息干扰传少了子Agent缺上下文做不了事。我的原则是主Agent给子Agent传任务描述必要上下文期望输出格式子Agent给主Agent回结果置信度异常说明。具体来说主Agent调用子Agent时不要把它自己的完整对话历史传过去而是提炼出一个干净的任务包。子Agent返回时也不要返回一大段自然语言而是结构化结果。这样主Agent汇总时才好处理。我踩过的坑早期让子Agent返回自然语言总结结果主Agent要花大量token去解析这些总结还经常理解错。改成结构化返回后主Agent的处理逻辑简单多了整个系统的稳定性也上来了。5. 测试与观测概率性系统怎么保证线上不出事5.1 Agent的测试和传统软件测试根本不是一回事传统软件测试是给定输入断言输出。Agent不行因为同样的输入模型可能给出不同的工具调用路径最终结果也可能有差异。所以Agent测试的核心不是断言具体输出而是断言行为边界。我现在的测试分三层单元层测工具函数本身这个和传统测试一样输入输出确定行为层测Agent在给定场景下该调的工具调了没、不该调的调了没、该停的时候停了没端到端层用一批真实场景跑人工评估结果质量行为层是最关键的也是最容易被忽略的。我会为每个核心场景写一组期望行为比如用户问退款政策时应该调用query_refund_policy而不是process_refund。然后用自动化脚本跑一批case统计行为符合率。这个符合率不需要100%但要有基线且每次改动后不能明显下降。5.2 观测什么Agent的黑盒要打开哪些窗口Agent上线后最怕的是它出错了但我不知道。所以观测体系必须覆盖每轮的输入输出模型看到了什么、输出了什么工具调用链调了哪些工具、顺序、参数、结果token消耗每轮、每任务的消耗用于成本监控异常与重试哪些工具报错、模型怎么处理的终止原因正常完成、轮次上限、无进展、成本超限这些数据我一般会打到日志系统里按任务ID串起来。出问题时能完整回放一个任务的执行过程。这个能力极其重要——没有它Agent出问题你只能靠猜。提示日志里记录模型输入输出时注意脱敏。用户隐私、内部数据这些不能明文落盘。5.3 上线策略灰度、回滚、人工兜底Agent上线千万别一把梭。我的标准流程是影子模式Agent跑但不真正执行操作只记录如果执行会怎样人工对比灰度放量先放1%流量观察行为符合率和异常率人工兜底敏感操作退款、发邮件、改数据必须有人工确认环节或者设置金额/影响范围阈值快速回滚一旦异常率超过阈值能一键切回旧逻辑这套流程看起来保守但Agent是概率性系统保守一点不丢人。我见过太多团队Demo效果好就直接全量结果线上出了几次事故反而拖慢了整个项目的推进。6. 框架选型LangChain、Spring AI还是自己写6.1 框架解决的是重复造轮子不是替你思考LangChain和Spring AI这类框架核心价值是把模型调用、工具封装、循环控制、上下文管理这些通用逻辑封装好让你少写样板代码。但它们不解决业务问题也不替你决定工具怎么设计、上下文怎么管。我见过有人纠结到底用LangChain还是Spring AI纠结了两周。其实这个决策没那么重要因为你真正要学的那五件事换任何框架都一样。框架只是外壳里面的设计思想才是核心。6.2 选型看什么团队技术栈、可控性、生态我的选型逻辑很简单团队是Java栈优先Spring AI和现有Spring Boot服务集成顺滑运维体系统一团队是Python栈LangChain生态更成熟工具和示例多需要深度定制循环逻辑考虑自己写框架的抽象层有时候反而是束缚需要快速验证用框架别自己造Spring AI这两年在国内落地越来越多尤其是和Spring Boot、若依这类框架结合的企业项目。它的优势是和Java生态无缝缺点是抽象层有时候不够灵活遇到框架没覆盖的场景要绕。LangChain的优势是灵活、生态全缺点是版本迭代快、API变动大升级一次可能改一堆代码。6.3 我的实际选择框架打底关键逻辑自己控我现在的做法是混合用框架处理模型调用、工具注册这些标准化的部分但循环控制、上下文管理、终止条件这些核心逻辑自己写。这样既享受了框架的便利又保留了对关键行为的控制权。比如用Spring AI的ChatClient做模型调用和工具绑定但整个Agent的循环、状态管理、终止判断是我自己实现的。这样框架升级时我的核心逻辑不受影响框架没覆盖的场景我也能自己补。这个思路可能不适合所有人但对需要长期维护、对可控性要求高的项目我觉得是最稳的。7. 一些没人告诉你但很重要的实操心得7.1 Prompt里的不要做什么比要做什么更重要给Agent写系统Prompt时我花在禁止事项上的时间比任务描述还多。因为模型天然倾向于多做你不明确禁止它就会自作主张。比如我会写不要在没有用户确认的情况下执行任何写操作不要在工具返回错误时编造数据不要假设用户没说过的信息。这些负面约束每一条都是踩坑换来的。7.2 模型选型不是越强越好而是越稳越好Agent场景下模型的稳定性比聪明程度更重要。一个偶尔超神但经常抽风的模型不如一个稳定发挥的中等模型。因为Agent是多轮循环任何一轮的不稳定都会被放大。我一般会准备两个模型一个主力模型跑正常流程一个更强的模型做兜底当主力模型连续失败时切换。这样成本和稳定性兼顾。7.3 版本管理Prompt、工具、模型都要版本化Agent的行为由Prompt、工具定义、模型版本共同决定。任何一个变了行为都可能变。所以这三样都要版本化并且记录哪个版本组合产生了哪个结果。出问题时能快速定位是哪个变更导致的。这一点在团队协作时尤其重要。没有版本管理两个人同时改Prompt和工具出了问题根本查不出来。7.4 别追求全自动该让人介入就介入最后一条也是最重要的Agent不是越自动越好。在关键节点设置人工确认不是技术不行而是负责任。我做的所有生产级Agent在涉及资金、对外沟通、数据修改这些操作时都有人工确认环节。这不是妥协是设计。真正成熟的Agent系统是知道什么时候该自己决定什么时候该问人的系统。这个判断能力比任何框架技巧都值钱。回头看这两年Agent开发真正难的不是学某个框架的API而是建立一套关于如何让一个概率性系统可控地完成业务目标的思维方式。工具设计、上下文管理、多Agent协作、测试观测、框架选型这五件事本质上都是在回答同一个问题怎么让不确定的模型做出确定的业务结果。想清楚这个剩下的都是工程细节。