1. 从“会调API”到“能交付系统”Agent开发真正的分水岭做了近两年的Agent开发我越来越觉得这个领域表面上热闹得不行——新框架、新概念、新论文几乎每周都在刷屏但真正落到工程里能决定一个Agent项目成败的东西其实就那么几件。很多刚入行的朋友问我“Agent开发到底要学什么”我一般不会直接甩一堆框架名字给他因为我自己踩过这个坑早期我也以为把LangChain的Chain、Tool、Memory都跑一遍就算入门了结果真到项目里一个简单的多轮工具调用就能把整个流程卡死日志里全是“agent execution terminated due to error”这种让人头大的报错。所以这篇东西我想按一个真正做过项目的人的视角把Agent开发里我认为最核心的五件事拆开讲。它不是一份“学习路线PDF”也不是面试题合集而是我在实际交付过程中反复验证、反复推翻又重建的认知。关键词里提到的LangChain、Spring AI、工程化、RAG、多智能体编排这些都会在对应的部分自然带出来。如果你是大模型开发工程师或者正准备从传统后端转向Agent方向又或者你在带团队做企业级Agent落地这篇应该能帮你少走一些弯路。先说一个我自己的判断2026年被很多人称为工业智能体从概念演示走向工程化落地的分水岭这个说法我认同。因为过去两年大家比的是“谁的Demo更惊艳”而接下来比的是“谁的系统能稳定跑在业务里”。这两件事需要的核心能力完全不是一回事。Demo阶段你可以靠一个Prompt加几个Tool糊弄过去工程化阶段你要面对的是状态管理、错误恢复、可观测性、成本控制、安全边界这一整套东西。下面这五件事就是我认为从“玩框架”到“做系统”之间必须跨过去的坎。2. 第一件事把“编排”当成一门独立的学问而不是框架的附属功能2.1 为什么很多人卡在“Chain能跑Agent跑不通”我见过太多人LangChain的入门教程跑得飞起LLMChain、SequentialChain用得滚瓜烂熟但一到Agent就懵了。原因很简单Chain是线性的、确定的你写死A到B到C它就跑A到B到C而Agent是动态的、带分支的、需要根据中间结果决定下一步的。这两者的心智模型完全不同。拿一个最典型的场景来说用户问“帮我查一下上个月华东区的销售数据然后跟去年同期对比最后生成一份简报”。在Chain里你得提前把“查数据→对比→生成”这条路径写死但在Agent里模型需要自己判断先调哪个工具查出来的数据格式对不对对比的时候要不要再调一次工具拿去年同期简报生成后要不要再校验一遍这些决策是运行时产生的不是编码时确定的。这就是为什么我说编排是一门独立的学问。它涉及的核心问题包括状态怎么在多个步骤之间传递工具调用的结果怎么结构化地回传给模型模型决定“下一步做什么”的时候上下文里应该放哪些信息这些问题LangChain、LangGraph、Spring AI各有各的答案但底层逻辑是相通的。2.2 LangChain和LangGraph的区别本质是“链式”和“图式”的区别关键词里有人搜“langchain和langgraph的区别”我用一句话概括LangChain的Agent本质还是在一个循环里跑“思考→行动→观察”而LangGraph把整个流程建模成一张有向图节点是计算单元边是状态转移。这个区别在简单场景下不明显但在复杂场景下是致命的。举个例子我之前做一个客服工单自动分类和分派的Agent。用LangChain的AgentExecutor流程是模型看工单内容→决定调分类工具→拿到分类结果→决定调分派工具→拿到分派结果→输出。看起来没问题但实际跑起来你会发现如果分类工具返回了一个模型没见过的类别模型会反复调用分类工具陷入死循环。因为AgentExecutor的循环控制很弱你很难在中间插入“如果分类置信度低于阈值就走人工审核分支”这种逻辑。换成LangGraph之后我把流程画成图入口节点做预处理然后条件边根据置信度决定走“自动分派”还是“人工审核”每个节点都有明确的输入输出状态。这样不仅逻辑清晰而且每个节点的执行都可以单独打日志、单独重试、单独做超时控制。这就是“图式编排”带来的工程价值。2.3 Spring AI在编排上的取舍更贴近企业后端的思维关键词里还有“spring ai”和“现在到底用spring ai还是langgraph4j”这种问题。我的看法是如果你的团队是Java技术栈而且Agent需要深度集成现有的Spring Boot服务那Spring AI的编排模型会更顺手。它不像LangGraph那样强调“图”而是更倾向于用Spring生态里常见的Bean、Service、事件驱动的方式来组织Agent流程。我去年帮一个做餐饮SaaS的团队做AI集成他们的后端全是Spring Boot数据库、消息队列、权限体系都在Spring里。如果用LangGraph4j虽然也能跑但跟现有服务的集成会很别扭很多地方要写适配层。用Spring AI的话工具可以直接暴露成Tool注解的方法Agent的调用链可以直接注入现有的Service状态管理也可以复用Spring的会话机制。这不是说哪个框架更好而是说编排方案要跟你的技术底座匹配。提示选框架之前先问自己三个问题——团队主力语言是什么Agent需要跟哪些现有系统交互未来半年会不会换框架这三个问题的答案基本能帮你排除掉一半选项。3. 第二件事RAG不是“向量库检索”那么简单它是Agent的长期记忆基础设施3.1 为什么Agent比纯问答更需要RAG很多人把RAG当成一个独立的问答技术觉得“我做个知识库问答才需要RAG做Agent不需要”。这个认知是错的。Agent的核心能力是“在动态环境中做决策”而做决策需要信息。这些信息一部分来自工具调用另一部分就来自RAG——也就是Agent的长期记忆和领域知识。我举个实际例子。之前做一个法律咨询Agent用户问“我这个合同里的竞业限制条款有效吗”。Agent需要做几件事先检索相关法条和司法解释RAG再检索类似案例的判决结果RAG然后结合用户合同的具体条款工具调用读取文档最后生成分析。如果没有RAG模型只能靠训练时记住的法律知识一来可能过时二来无法引用具体法条编号三来无法结合最新判例。这样的Agent在专业场景里是不可用的。3.2 LangChain里MultivectorRetriever的用法和它的适用场景关键词里有人搜“langchain multivectorretriever用法”我顺便说一下。MultiVectorRetriever解决的是一个很实际的问题你的文档可能很长直接拿整篇文档做向量检索粒度太粗检索出来的东西不精准但如果把文档切得太碎又会丢失上下文。MultiVectorRetriever的思路是为同一份原始文档生成多种“视图”——比如一份是摘要向量一份是假设性问题向量一份是原文分块向量——检索时命中任意一个视图都能回溯到原始文档。我在做一个技术文档助手时用过这个。原始文档是几百页的产品手册如果直接按段落切用户问“怎么配置超时重试”检索出来的可能是某个不相关的配置项。后来我用MultiVectorRetriever为每个章节生成一组“用户可能怎么问”的假设性问题把这些问题的向量和原文块的向量一起存进去。检索时用户的问题先匹配到假设性问题再回溯到对应的原文块。实测下来召回准确率提升很明显。3.3 Spring AI RAG的工程化细节别忽略元数据过滤Spring AI的RAG模块相对简洁但有一个细节很多人忽略元数据过滤。在企业场景里知识库往往是有权限层级的。比如一个HR Agent普通员工问“我的年假还剩多少”它只能查这个员工自己的数据HR问“部门今年的休假情况”它才能查汇总数据。如果RAG检索时不带元数据过滤很可能把不该给用户看的内容检索出来。Spring AI的VectorStore支持在检索时传入SearchRequest里面可以带过滤表达式。我的做法是在文档入库时给每个chunk打上tenant_id、role、department这些元数据检索时根据当前用户的身份动态构造过滤条件。这样既保证了检索质量又保证了数据隔离。这个思路在LangChain里也适用只是API写法不同。4. 第三件事工具调用是Agent的手脚但“怎么设计工具”比“怎么调工具”重要十倍4.1 工具描述写得好Agent的智商就高一半我刚开始做Agent的时候总觉得模型不够聪明老是调错工具。后来发现问题往往出在工具描述上。模型决定调哪个工具完全依赖你给的描述。如果你写“查询订单”模型不知道是查订单状态还是查订单历史如果你写“根据订单号查询订单的当前状态和物流信息”模型就能准确判断。我现在的习惯是每个工具的描述都包含四要素这个工具做什么、什么情况下用、输入参数的含义和格式、返回值的结构。比如一个查天气的工具描述会写成“查询指定城市指定日期的天气情况。当用户询问天气、气温、是否下雨等问题时使用。输入参数city为城市中文名date为YYYY-MM-DD格式的日期。返回包含温度、天气状况、湿度、风力的结构化数据。”这样写下来模型调用的准确率会高很多。4.2 工具粒度的取舍太粗和太细都是坑工具设计还有一个很容易踩的坑粒度。工具太粗比如一个“处理用户请求”的工具模型不知道怎么用工具太细比如“查询数据库表A的字段B”模型要调十几次才能完成一个任务延迟和成本都受不了。我的经验是按“业务动作”来划分工具粒度。一个业务动作应该是用户能理解的一个完整操作比如“查询订单状态”“取消订单”“申请退款”。这些动作背后可能涉及多个数据库操作但对模型来说它只需要知道“我要完成取消订单这个动作调这个工具就行”。至于工具内部怎么实现那是工程侧的事不需要暴露给模型。4.3 工具调用的错误处理别让一个失败的工具调用拖垮整个Agent这是我在生产环境里踩过的最大的坑之一。早期我做Agent工具调用失败就直接抛异常整个Agent就挂了。后来发现工具调用失败是常态——网络超时、第三方API限流、参数格式不对各种情况都会发生。如果每次失败都让Agent终止用户体验会非常差。正确的做法是把工具调用失败当成一种正常的“观察结果”返回给模型。比如工具返回“查询失败订单号格式不正确请检查后重试”模型看到这个结果会尝试修正参数或者询问用户。这样Agent就有了自我恢复的能力。LangChain里可以通过自定义ToolException的处理逻辑来实现Spring AI里可以在Tool方法里捕获异常并返回结构化的错误信息。注意工具返回的错误信息也要结构化最好包含错误类型、错误原因、建议的下一步操作。这样模型才能做出正确的决策而不是瞎猜。5. 第四件事状态管理和可观测性是Agent从Demo走向生产的分水岭5.1 多轮对话里的状态到底该怎么存Agent跟普通Chatbot最大的区别之一就是它有“任务状态”。普通Chatbot只需要记住对话历史Agent还要记住“当前任务进行到哪一步了”“已经调用了哪些工具”“拿到了哪些中间结果”。这些状态如果管理不好就会出现“模型忘了自己刚才做了什么”的情况。我的做法是把状态分成三层会话状态对话历史、任务状态当前任务的进度和中间结果、全局状态用户偏好、权限等长期信息。会话状态可以存在内存或Redis里任务状态跟着Agent的执行链路走全局状态存在数据库里。LangGraph的StateGraph天然支持这种分层每个节点可以读写自己关心的状态字段。Spring AI的话可以用ChatMemory加自定义的ConversationState来实现。5.2 可观测性没有日志和追踪Agent就是黑盒我见过很多团队Agent在测试环境跑得好好的一上生产就各种问题然后排查起来极其痛苦因为不知道模型在每一步到底看到了什么、想了什么、决定了什么。这就是缺乏可观测性的后果。一个可观测的Agent系统至少要记录这些东西每次模型调用的输入Prompt和输出结果、每次工具调用的参数和返回值、每个决策节点的状态变化、整个链路的耗时和Token消耗。LangChain有LangSmith可以做追踪Spring AI可以集成Micrometer和OpenTelemetry。但工具只是手段关键是你有没有意识去记录这些信息。我自己的习惯是在开发阶段就把日志级别调到DEBUG把每次模型交互的完整上下文都打出来。上线后再根据实际情况调整级别但关键决策点的日志永远保留。这样出问题的时候我能快速定位是模型理解错了还是工具返回错了还是状态传递错了。5.3 成本控制Token不是免费的Agent的Token消耗可能是Chatbot的十倍这一点很多人在Demo阶段不会注意但上了生产就是真金白银。一个Agent任务可能涉及多次模型调用、多次工具调用每次调用都要把上下文传进去Token消耗是普通对话的好几倍。如果不做控制月底账单会很吓人。我的控制策略有几个第一上下文裁剪只把当前步骤需要的信息放进Prompt不要把整个对话历史都塞进去第二工具结果摘要如果工具返回的是大段文本先做摘要再传给模型第三模型分级简单决策用便宜的小模型复杂推理用大模型第四缓存相同的查询结果缓存起来避免重复调用。这些策略组合起来能把成本压到可接受的范围。6. 第五件事安全边界和人工兜底是Agent敢上生产的最后一道保险6.1 Agent的安全风险比Chatbot高一个量级Chatbot说错话最多是尴尬Agent做错事可能造成实际损失。比如一个自动退款Agent如果被诱导把不该退的款退了那就是真金白银的损失。所以Agent的安全设计必须比Chatbot严格得多。我一般从三个层面做防护输入层做意图识别和风险分类识别出高风险请求直接拦截或转人工决策层做权限校验Agent能调用的工具、能访问的数据都要跟当前用户的权限匹配输出层做内容审核确保Agent的回复不包含敏感信息或不当承诺。6.2 人工兜底不是“失败”而是“设计的一部分”很多人觉得Agent就应该全自动转人工说明Agent不行。这个观念要改。在生产环境里人工兜底是必须的。关键是你要设计好“什么时候转人工”。我的经验是以下几种情况必须转人工模型置信度低于阈值、涉及金额超过一定限额、用户明确要求人工、连续多次工具调用失败、检测到潜在的安全风险。转人工的体验也要设计好。不能简单地说“我转人工了”而是要把Agent已经收集到的信息、已经做的判断一起传递给人工客服让用户不用重复描述问题。这样人工客服接手后能快速处理用户体验也是连贯的。6.3 从“Agent开发面试题”看行业对安全能力的重视关键词里有很多“agent开发面试题”“agent安全”相关的搜索。我最近也面了一些人发现一个趋势面试官越来越关注候选人对安全边界的理解。以前问“你怎么实现一个Agent”现在问“你怎么防止Agent被Prompt注入攻击”“你怎么设计Agent的权限体系”“你怎么做Agent的输出审核”。这些问题没有实际踩过坑的人很难答到点子上。我的建议是如果你在准备Agent方向的面试不要只准备框架API的用法多想想“如果这个Agent上线了可能出什么问题我怎么防”。这种思考方式比背八股文有用得多。7. 关于学习路线和框架选型我的一些个人体会回到开头那个问题Agent开发到底要学什么。如果让我给一个学习顺序我会说先学编排的基本概念状态、节点、边、条件分支再学RAG的工程化细节分块、元数据、检索策略然后学工具设计的原则描述、粒度、错误处理接着学状态管理和可观测性日志、追踪、成本最后学安全边界和人工兜底。框架只是这些概念的载体LangChain也好Spring AI也好LangGraph也好学一个就够了重点是理解背后的设计思想。至于“现在到底用Spring AI还是LangGraph4j”这种问题我的答案永远是看你的团队和场景。Java团队做企业集成Spring AI更顺需要复杂编排和灵活状态管理LangGraph更合适如果只是做个简单的工具调用Agent其实用哪个都行别在选型上纠结太久先跑起来再说。最后分享一个我自己的小习惯每做一个Agent项目我都会建一个“踩坑文档”把遇到的奇怪问题、奇怪的报错、奇怪的模型行为记下来。比如“agent execution terminated due to error”这个报错我遇到过三次每次原因都不一样——一次是工具返回了非JSON格式一次是状态字段类型不匹配一次是模型输出了非法字符。这些记录比任何教程都值钱。因为Agent开发这个领域变化太快今天的最佳实践明天可能就过时了但踩过的坑和总结出的排查思路是能一直用的。