AI Agent 这个词在过去一年里被反复提起但真正动手搭过的人都知道从能跑通一个 Demo到能稳定扛住真实业务流量中间隔着一整套工程决策。我前后用 LangGraph、Spring AI、扣子这几套东西搭过几个不同量级的 Agent 项目踩过的坑从工具调用参数对不上、循环停不下来到并发一上来就雪崩基本都经历了一遍。这篇就把我理解的 Agent 工程实现拆开讲——从构成一个 Agent 的七个核心要素到落地时必须拍板的七个决策点尽量说人话把为什么这么选讲透而不是只丢一堆框架文档链接给你。如果你正在纠结 Agent 到底该怎么搭、框架怎么选、循环怎么控、并发怎么扛或者只是想知道Agent 和普通 LLM 调用到底差在哪这篇应该能帮你少走不少弯路。我会尽量把每个决策点背后的取舍逻辑讲清楚让你看完能直接对着自己的场景做判断而不是照抄某篇教程的代码。1. 先把Agent 是什么这件事说清楚1.1 从一次 LLM 调用到 Agent 的本质跨越很多人第一次接触 Agent脑子里其实是模糊的不就是调个大模型 API 吗加个循环就叫 Agent 了这个理解对了一半但漏掉了最关键的东西。一次普通的 LLM 调用是这样的你给一段 prompt模型返回一段文本结束。它是无状态、单轮、被动的。你问北京今天天气怎么样模型要么凭训练数据瞎猜要么直接说我无法获取实时信息。它没有手也没有脚只能动嘴。Agent 的本质跨越在于三点它能自己决定要不要调用工具、能根据工具返回的结果决定下一步做什么、能在一个循环里持续推进直到任务完成。换句话说Agent LLM 工具 循环 记忆 决策。LLM 是大脑工具是手脚循环是让它多想想再动手的机制记忆是让它别每次都从零开始。我常拿做饭打比方。普通 LLM 调用像你问一个美食家红烧肉怎么做他凭记忆给你背一段菜谱。Agent 则像你请了个厨师进厨房他会先看冰箱里有什么工具调用查库存发现没有冰糖就决定用白糖替代决策炒糖色的时候看颜色不对就调整火候循环中的反馈修正最后端出一盘菜任务完成。这个看情况调整的能力才是 Agent 真正的价值。所以判断一个东西是不是 Agent有个很实用的标准它有没有在一个循环里基于外部反馈自主决定下一步动作。如果只是prompt 进、文本出那再花哨也只是个 LLM 应用不是 Agent。1.2 七个要素拆开看每个部件到底在干嘛把 Agent 拆开我习惯分成七个要素。这不是教科书定义是我自己搭项目时总结的一套检查清单缺哪个都会在某个环节出问题。第一个是模型Model。这是推理核心负责理解意图、规划步骤、生成工具调用参数。选模型时不要只看榜单排名要看它在**函数调用Function Calling**上的稳定性。我实测下来有些模型聊天很溜但一到结构化输出就开始胡说工具参数经常缺字段或者类型不对这种模型做 Agent 会非常痛苦。第二个是工具Tools。工具就是 Agent 能调用的外部能力查数据库、调 API、读文件、发消息、执行代码。工具设计的好坏直接决定 Agent 的上限。我的经验是工具描述要写得像给新人看的说明书——说清楚这个工具干什么、什么时候用、参数是什么格式、返回什么模型才能用对。第三个是循环Loop。这是 Agent 的引擎。它决定了 Agent 能想几步。循环机制设计不好要么一步就停没完成任务就退出要么无限打转反复调同一个工具停不下来。第四个是记忆Memory。分短期和长期。短期记忆是当前对话的上下文长期记忆是跨会话的知识沉淀。没有记忆的 Agent 每次都是失忆状态用户体验会很割裂。第五个是规划Planning。复杂任务需要先拆解再执行。比如帮我订一张下周去上海的机票并安排接机这需要拆成查航班、比价、下单、约车好几个子任务。规划能力强的 Agent 会先列个计划再动手而不是走一步看一步。第六个是执行Execution。真正去调用工具、处理返回、捕获异常的那一层。这里最容易出工程问题超时怎么办、工具报错怎么办、返回格式不对怎么办。第七个是反馈与终止Feedback Termination。Agent 怎么知道自己做完了靠的是终止条件判断。这个要素最容易被忽略但它是防止 Agent发疯的关键闸门。这七个要素里模型和工具是能力循环、记忆、规划是机制执行和终止是保障。搭 Agent 的时候能力可以慢慢加但机制和保障必须一开始就想清楚否则后期改起来伤筋动骨。1.3 为什么七要素比框架 API更值得先搞懂我见过太多人一上来就扎进 LangGraph 或者 Spring AI 的文档里照着示例代码抄一遍跑通了就以为会了。结果业务一变需求一复杂整个人就懵了——因为他学的是这个框架怎么用而不是Agent 到底怎么运转。框架是会变的。去年流行的编排方式今年可能就被新的范式取代。但七要素这套底层结构是稳定的它对应的是 Agent 运行的本质需求。你把这七个要素想明白了换任何框架都是换个写法实现同样的东西学习成本会低很多。打个比方学做菜要先懂火候、调味、食材处理这些基本功而不是死记某个牌子的锅怎么用。锅可以换基本功换不了。所以我的建议是先用七要素建立心智模型再去挑框架这样你选框架的时候是有判断力的而不是被框架牵着走。2. 七个决策点落地时必须拍板的事七要素是Agent 由什么构成七个决策点是搭的时候你必须做哪些选择。这两者不是一回事。要素是静态的解剖图决策点是动态的施工方案。下面这七个决策每一个都会实质影响你的 Agent 能不能用、好不好用。2.1 决策一单 Agent 还是多 Agent 协作这是第一个要拍板的问题也是最容易拍错的问题。很多人一上来就想搞多 Agent觉得多个专家协作肯定比一个强结果复杂度爆炸调试到怀疑人生。我的判断标准很简单如果一个 Agent 用一套工具、一个系统提示词就能把任务干完就别上多 Agent。多 Agent 的价值在于职责隔离——当不同子任务需要完全不同的工具集、不同的提示词策略、甚至不同的模型时拆开才有意义。举个实际例子。做一个智能客服 工单处理的系统客服对话和工单流转这两件事工具集完全不同提示词逻辑也完全不同这种就适合拆成两个 Agent用一个调度层来协调。但如果只是查订单 回答物流问题一个 Agent 挂两个工具就够了硬拆成两个反而增加通信开销和出错概率。多 Agent 的代价是实打实的Agent 之间怎么传消息、状态怎么同步、一个卡住了怎么办、怎么防止它们互相甩锅死循环。这些都是额外的工程负担。所以我的原则是能单不双先单后多确有隔离需求再拆。2.2 决策二工具调用的粒度怎么切工具粒度是个技术活。切太粗一个工具干太多事模型不好控制切太细工具数量爆炸模型选择困难还容易调错。我踩过的坑是这样的一开始我把查询用户信息做成一个大工具参数里塞了十几种查询类型结果模型经常传错参数组合。后来我把它拆成按手机号查用户按订单号查用户按用户 ID 查用户三个独立工具每个工具参数简单明确调用准确率立刻上来了。但也不能无限拆。工具数量超过一定规模我的经验是 15 到 20 个左右模型在选工具时就开始犹豫容易选错或者漏选。这时候要考虑工具分组或者分层路由——先让模型判断任务类型再在对应类别里选具体工具。一个实用的粒度原则一个工具只做一件事参数不超过 5 个返回结果结构化且字段明确。满足这三条工具基本就是好用的。2.3 决策三循环终止条件怎么设循环终止是 Agent 工程里最容易被低估、也最容易出事的地方。我见过 Agent 因为终止条件没设好反复调用同一个搜索工具几十次token 烧了一大片任务还没完成。终止条件至少要设三层保险第一层是任务完成判断。模型明确输出任务已完成或者返回了最终答案就停。这层靠的是提示词里明确要求模型在完成时给出特定标记。第二层是步数上限。设一个最大循环次数比如 10 步或 15 步到了就强制停。这是防止无限循环的硬闸门。第三层是重复检测。如果连续几步调用的工具和参数高度相似说明 Agent 卡住了应该主动中断并返回当前状态。这三层缺一不可。任务完成判断是正常出口步数上限是保险丝重复检测是防呆机制。我一般会把步数上限设得比预期多 2 到 3 步给 Agent 留点纠错空间但不能无限留。2.4 决策四记忆存哪里、存多久记忆这块核心是两个问题存什么和存多久。短期记忆当前会话上下文一般直接放在对话历史里跟着请求走。但要注意上下文长度限制对话太长要做摘要压缩否则要么超 token 限制要么成本飙升。长期记忆跨会话就需要外部存储了。常见方案是向量数据库存语义记忆关系数据库存结构化事实。我一般会把用户偏好历史决策重要事实这几类信息沉淀到长期记忆里下次会话开始时按相关性检索注入。存多久这个问题取决于业务。客服场景可能保留几个月个人助手场景可能长期保留。但要注意隐私和成本不是存得越久越好。我的做法是给记忆加重要性评分和过期时间低重要性的记忆定期清理。2.5 决策五并发上来之后怎么扛这是热词里ai agent 怎么扛并发直接对应的问题也是从 Demo 走向生产必须跨过的坎。Agent 的并发压力和普通 API 不一样因为一个 Agent 请求内部可能包含多次 LLM 调用和多次工具调用耗时是普通请求的好几倍。一个用户请求可能占用几十秒甚至几分钟这期间连接、上下文、状态都得维持着。我的应对思路分几层第一层是异步化。Agent 执行全程用异步别用同步阻塞。LLM 调用、工具调用都走 async这样单个进程能同时处理更多请求。第二层是状态外置。Agent 的中间状态不要放在进程内存里放到 Redis 这类外部存储。这样进程可以水平扩展请求打到哪个实例都能接着跑。第三层是限流和排队。Agent 请求成本高必须限流。超出容量的请求进队列排队而不是直接压垮后端。队列要有优先级重要任务优先处理。第四层是超时和熔断。单个 Agent 执行设总超时工具调用设单独超时某个工具连续失败就熔断避免拖垮整个链路。这四层做下来Agent 服务基本能扛住一定规模的并发。具体数字取决于你的模型响应速度和工具耗时没有万能公式得压测。2.6 决策六框架选型——LangGraph、Spring AI 还是自研框架选型没有标准答案只有适不适合。我把常见的几类方案和适用场景列一下。方案类型代表适合场景主要代价图编排框架LangGraph流程复杂、需要精细控制循环和分支学习曲线陡概念多应用框架Spring AIJava 技术栈、企业级集成生态相对新部分能力待完善平台化工具扣子类平台快速验证、非技术团队定制能力受限深度集成难自研自己写编排层需求特殊、要极致控制工作量大轮子要自己造我的建议是先用成熟框架快速跑通验证业务价值等遇到框架解决不了的问题再考虑自研或深度定制。一上来就自研大概率是在重复造轮子而且造得还不如人家。LangGraph 适合那种流程像流程图一样复杂的场景它的状态图和条件边能把复杂循环表达得很清楚。Spring AI 适合 Java 团队能和你现有的 Spring 生态无缝集成。扣子这类平台适合快速验证想法但要做深度定制就得掂量了。2.7 决策七怎么评估 Agent 到底好不好用Agent 的评估比普通 LLM 难得多因为它的输出不是一段文本而是一串动作序列。你很难用简单的对错来判断。我的评估体系分三个维度结果维度任务最终完成了吗完成质量如何这是最直接的指标。过程维度完成任务的路径合理吗有没有绕远路、有没有多余的工具调用、有没有反复试错一个结果对但过程乱的 Agent在生产环境里是隐患。成本维度完成一个任务花了多少 token、多少次工具调用、多少时间成本高的 Agent 很难规模化。具体评估方法上我会准备一批标准测试用例覆盖正常场景、边界场景、异常场景然后人工标注期望的行为路径用自动化脚本跑回归。每次改提示词或换模型都跑一遍看指标有没有退化。这里有个坑要提醒别只用成功案例评估。Agent 最容易在异常场景翻车——工具报错、参数缺失、意图模糊的时候它怎么反应才是真正体现工程质量的地方。3. 循环机制Agent 的引擎到底怎么转循环是 Agent 区别于普通 LLM 调用的核心值得单独拎出来讲透。很多人对循环的理解停留在while 循环里调模型但真实的 Agent 循环要复杂得多。3.1 一次完整的 Agent 循环里发生了什么一个标准的 Agent 循环一轮大概是这样组装上下文把系统提示词、对话历史、可用工具列表、当前状态拼成给模型的输入。模型推理模型输出要么是我要调用某个工具参数是这些要么是我的最终答案是这些。解析输出程序解析模型输出判断是工具调用还是最终答案。执行工具如果是工具调用执行对应工具拿到返回结果。结果回填把工具返回结果作为新消息加进上下文。判断终止检查是否满足终止条件满足就退出不满足就回到第 1 步。这个循环看起来简单但每一步都有坑。比如第 2 步模型可能输出格式不对的 JSON解析就失败第 4 步工具可能超时或报错第 6 步终止条件可能永远不满足。我实测下来最容易出问题的是第 2 步和第 6 步。模型输出格式不稳定是 Agent 开发中最常见的痛点。解决办法是在提示词里给明确的格式示例并且用支持结构化输出的模型能力比如 JSON mode 或函数调用模式别指望模型每次都自觉输出规范格式。3.2 循环里最危险的三种卡死模式Agent 卡死不是玄学是有具体模式的。我总结下来主要是三种第一种是工具选择死循环。Agent 反复调用同一个工具每次参数略有不同但本质一样。比如反复搜索同一个关键词因为每次返回的结果它都觉得不够好。这种要靠重复检测来打断。第二种是参数修正死循环。工具报错说参数不对Agent 改一下再调还是不对再改来回折腾。这种常见于工具参数校验严格、但模型理解不到位的情况。解决办法是把工具的参数要求写得更清楚报错信息也要对模型友好。第三种是规划死循环。Agent 一直在规划但从不执行或者执行完又推翻重来。这种通常是提示词里对什么时候算规划完成定义不清导致的。这三种卡死光靠步数上限能兜底但体验很差。更好的做法是在提示词和工具设计阶段就预防让 Agent 不容易走进死胡同。3.3 让循环聪明地停而不是被迫地停终止条件设计得好不好直接决定 Agent 是聪明地停还是被迫地停。被迫地停就是撞到步数上限才停这时候任务往往没完成用户拿到的是半成品。聪明地停是 Agent 自己判断任务完成了主动给出结果。要做到聪明地停提示词里要明确告诉模型什么情况下算任务完成、完成后要输出什么格式的最终答案。比如当你已经获取到用户需要的所有信息后用 FINAL_ANSWER: 开头输出最终答案。同时工具返回结果里也可以带完成信号。比如某个查询工具返回已找到唯一匹配结果模型看到这个信号就知道不用再查了。我还会加一个自我检查步骤在准备输出最终答案前让模型自己确认一遍任务要求是否都满足了。这一步能显著减少提前收工的情况。4. 工具调用Agent 的手脚怎么设计才好用工具调用是 Agent 能力的直接体现也是工程问题最集中的地方。热词里langgraph 工具调用llm request failed: provider rejected the request schema or tool payload这些说的都是这块的坑。4.1 工具描述写得好调用准确率翻倍工具描述description是模型选择工具的唯一依据。写得含糊模型就选错写得清楚准确率立竿见影。一个好的工具描述包含四部分这个工具做什么、什么时候该用、参数什么含义、返回什么结构。我举个例子对比一下。差的描述查询订单信息。好的描述根据订单号查询订单的详细状态包括支付状态、物流状态、预计送达时间。当用户询问订单进度、物流情况时使用此工具。参数 order_id 为订单号格式为纯数字字符串。返回包含 status、logistics、eta 三个字段的 JSON。后者明显更容易让模型用对。我实测过把工具描述从一句话扩写成上面这种结构化说明工具调用准确率能从六七成提到九成以上。4.2 参数校验和错误返回别让模型猜工具的参数校验要严格但报错信息要对模型友好。什么叫对模型友好就是报错信息里要明确说哪个参数错了、错在哪、应该是什么格式。比如参数类型错了别只返回参数错误要返回参数 order_id 应该是字符串类型你传的是数字类型请改为字符串。模型看到这种报错下一轮就能改对。如果只返回参数错误模型只能瞎猜很容易陷入前面说的参数修正死循环。我一般会在工具层做三层校验类型校验、格式校验、业务校验。每层校验失败都返回结构化的错误信息包含错误字段、错误原因、修正建议。4.3 工具超时、重试与降级策略工具调用不可能永远成功。网络抖动、下游服务挂了、第三方限流都会导致工具失败。Agent 必须有应对策略。超时每个工具设独立超时别用全局超时。查询类工具可以短一点比如 5 秒生成类工具可以长一点比如 30 秒。重试只对幂等操作重试且要限制重试次数一般 2 到 3 次。非幂等操作比如下单、发消息重试要非常谨慎否则可能重复执行。降级工具彻底失败时要有降级方案。比如查询失败就返回缓存数据或者告诉 Agent这个工具暂时不可用请尝试其他方式。别让一个工具失败就导致整个 Agent 崩溃。这些策略要在工具封装层统一实现而不是每个工具各写一套。统一封装的好处是行为一致好维护。5. 从 Demo 到生产那些没人告诉你的工程细节Demo 跑通和生产可用之间隔着一堆琐碎但致命的工程细节。这部分我挑几个最关键的讲。5.1 可观测性Agent 的黑盒必须打开Agent 执行过程是个黑盒出了问题很难查。所以可观测性必须从一开始就做别等出事了才补。至少要记录这些东西每次 LLM 调用的输入输出和耗时、每次工具调用的参数和返回、每一轮循环的状态变化、整个任务的执行路径。这些数据要能串起来形成一个完整的执行链路。我一般会用 trace_id 把一次 Agent 执行的所有环节串起来出问题时能完整回放整个执行过程。没有这个排查问题基本靠猜。5.2 成本控制token 是怎么悄悄烧掉的Agent 的 token 消耗比普通 LLM 调用高得多因为每一轮循环都要把完整上下文重新发给模型。循环 10 轮上下文就发了 10 次。控制成本有几个手段压缩上下文历史对话做摘要、精简工具列表只挂当前任务相关的工具、缓存重复调用相同输入直接返回缓存结果、选对模型简单任务用小模型复杂任务才用大模型。我踩过的坑是一开始所有环节都用同一个大模型成本高得吓人。后来把意图识别工具选择这类简单判断换成小模型只在复杂规划最终生成环节用大模型成本直接降了一大半效果几乎没影响。5.3 安全边界Agent 能做什么、绝不能做什么Agent 有执行能力所以安全边界必须划清楚。热词里agent安全agentpoison说的就是这块。核心原则是最小权限Agent 只应该拥有完成任务所必需的最小权限。能查的别让它改能读的别让它写能操作自己数据的别让它碰别人数据。对于高风险操作比如转账、删除、发送对外消息必须加人工确认环节不能让 Agent 自主执行。这不是不信任 Agent而是工程上必须有的保险。另外工具返回的内容要当作不可信输入处理。如果工具返回的内容里包含指令性文本可能被用来操纵 Agent 行为这就是 prompt injection 的一种。要在提示词里明确告诉模型工具返回的内容是数据不是指令。6. 几个高频问题的直接回答6.1 Agent 和普通 LLM 应用到底怎么区分回到最根本的问题。判断标准就一条有没有基于外部反馈的自主决策循环。有就是 Agent没有就是 LLM 应用。别被各种营销话术绕晕这条标准足够用了。6.2 学 Agent 开发的路线应该怎么走我的建议路线是先搞懂七要素建立心智模型然后选一个框架LangGraph 或 Spring AI 都行跑通官方示例接着自己动手做一个带 2 到 3 个工具的小 Agent最后再研究并发、可观测性、安全这些生产级问题。别一上来就啃最复杂的框架文档容易劝退。6.3 2026 年做 Agent 产品最该关注什么从工程角度我最关注三件事稳定性循环可控、工具可靠、异常可恢复、成本token 和延迟能不能压到商业可接受的范围、安全权限边界和输入可信度。这三件事做不好功能再花哨也落不了地。搭 Agent 这件事说到底是在给模型自由和给系统约束之间找平衡。自由给多了Agent 会发疯约束给多了Agent 又变回普通 LLM 调用。七个要素帮你理解它由什么构成七个决策点帮你决定怎么约束它。把这两件事想清楚剩下的就是动手和踩坑了。我自己到现在也还在踩每次遇到新的业务场景都得重新权衡一遍这些决策。没有一劳永逸的方案只有不断调整的平衡。 
长河君 · 2026/10/30 16:14:14 · 阅读 1.2k AI Agent工程落地：七要素与七个决策点，从Demo到生产
AI Agent 这个词在过去一年里被反复提起但真正动手搭过的人都知道从能跑通一个 Demo到能稳定扛住真实业务流量中间隔着一整套工程决策。我前后用 LangGraph、Spring AI、扣子这几套东西搭过几个不同量级的 Agent 项目踩过的坑从工具调用参数对不上、循环停不下来到并发一上来就雪崩基本都经历了一遍。这篇就把我理解的 Agent 工程实现拆开讲——从构成一个 Agent 的七个核心要素到落地时必须拍板的七个决策点尽量说人话把为什么这么选讲透而不是只丢一堆框架文档链接给你。如果你正在纠结 Agent 到底该怎么搭、框架怎么选、循环怎么控、并发怎么扛或者只是想知道Agent 和普通 LLM 调用到底差在哪这篇应该能帮你少走不少弯路。我会尽量把每个决策点背后的取舍逻辑讲清楚让你看完能直接对着自己的场景做判断而不是照抄某篇教程的代码。1. 先把Agent 是什么这件事说清楚1.1 从一次 LLM 调用到 Agent 的本质跨越很多人第一次接触 Agent脑子里其实是模糊的不就是调个大模型 API 吗加个循环就叫 Agent 了这个理解对了一半但漏掉了最关键的东西。一次普通的 LLM 调用是这样的你给一段 prompt模型返回一段文本结束。它是无状态、单轮、被动的。你问北京今天天气怎么样模型要么凭训练数据瞎猜要么直接说我无法获取实时信息。它没有手也没有脚只能动嘴。Agent 的本质跨越在于三点它能自己决定要不要调用工具、能根据工具返回的结果决定下一步做什么、能在一个循环里持续推进直到任务完成。换句话说Agent LLM 工具 循环 记忆 决策。LLM 是大脑工具是手脚循环是让它多想想再动手的机制记忆是让它别每次都从零开始。我常拿做饭打比方。普通 LLM 调用像你问一个美食家红烧肉怎么做他凭记忆给你背一段菜谱。Agent 则像你请了个厨师进厨房他会先看冰箱里有什么工具调用查库存发现没有冰糖就决定用白糖替代决策炒糖色的时候看颜色不对就调整火候循环中的反馈修正最后端出一盘菜任务完成。这个看情况调整的能力才是 Agent 真正的价值。所以判断一个东西是不是 Agent有个很实用的标准它有没有在一个循环里基于外部反馈自主决定下一步动作。如果只是prompt 进、文本出那再花哨也只是个 LLM 应用不是 Agent。1.2 七个要素拆开看每个部件到底在干嘛把 Agent 拆开我习惯分成七个要素。这不是教科书定义是我自己搭项目时总结的一套检查清单缺哪个都会在某个环节出问题。第一个是模型Model。这是推理核心负责理解意图、规划步骤、生成工具调用参数。选模型时不要只看榜单排名要看它在**函数调用Function Calling**上的稳定性。我实测下来有些模型聊天很溜但一到结构化输出就开始胡说工具参数经常缺字段或者类型不对这种模型做 Agent 会非常痛苦。第二个是工具Tools。工具就是 Agent 能调用的外部能力查数据库、调 API、读文件、发消息、执行代码。工具设计的好坏直接决定 Agent 的上限。我的经验是工具描述要写得像给新人看的说明书——说清楚这个工具干什么、什么时候用、参数是什么格式、返回什么模型才能用对。第三个是循环Loop。这是 Agent 的引擎。它决定了 Agent 能想几步。循环机制设计不好要么一步就停没完成任务就退出要么无限打转反复调同一个工具停不下来。第四个是记忆Memory。分短期和长期。短期记忆是当前对话的上下文长期记忆是跨会话的知识沉淀。没有记忆的 Agent 每次都是失忆状态用户体验会很割裂。第五个是规划Planning。复杂任务需要先拆解再执行。比如帮我订一张下周去上海的机票并安排接机这需要拆成查航班、比价、下单、约车好几个子任务。规划能力强的 Agent 会先列个计划再动手而不是走一步看一步。第六个是执行Execution。真正去调用工具、处理返回、捕获异常的那一层。这里最容易出工程问题超时怎么办、工具报错怎么办、返回格式不对怎么办。第七个是反馈与终止Feedback Termination。Agent 怎么知道自己做完了靠的是终止条件判断。这个要素最容易被忽略但它是防止 Agent发疯的关键闸门。这七个要素里模型和工具是能力循环、记忆、规划是机制执行和终止是保障。搭 Agent 的时候能力可以慢慢加但机制和保障必须一开始就想清楚否则后期改起来伤筋动骨。1.3 为什么七要素比框架 API更值得先搞懂我见过太多人一上来就扎进 LangGraph 或者 Spring AI 的文档里照着示例代码抄一遍跑通了就以为会了。结果业务一变需求一复杂整个人就懵了——因为他学的是这个框架怎么用而不是Agent 到底怎么运转。框架是会变的。去年流行的编排方式今年可能就被新的范式取代。但七要素这套底层结构是稳定的它对应的是 Agent 运行的本质需求。你把这七个要素想明白了换任何框架都是换个写法实现同样的东西学习成本会低很多。打个比方学做菜要先懂火候、调味、食材处理这些基本功而不是死记某个牌子的锅怎么用。锅可以换基本功换不了。所以我的建议是先用七要素建立心智模型再去挑框架这样你选框架的时候是有判断力的而不是被框架牵着走。2. 七个决策点落地时必须拍板的事七要素是Agent 由什么构成七个决策点是搭的时候你必须做哪些选择。这两者不是一回事。要素是静态的解剖图决策点是动态的施工方案。下面这七个决策每一个都会实质影响你的 Agent 能不能用、好不好用。2.1 决策一单 Agent 还是多 Agent 协作这是第一个要拍板的问题也是最容易拍错的问题。很多人一上来就想搞多 Agent觉得多个专家协作肯定比一个强结果复杂度爆炸调试到怀疑人生。我的判断标准很简单如果一个 Agent 用一套工具、一个系统提示词就能把任务干完就别上多 Agent。多 Agent 的价值在于职责隔离——当不同子任务需要完全不同的工具集、不同的提示词策略、甚至不同的模型时拆开才有意义。举个实际例子。做一个智能客服 工单处理的系统客服对话和工单流转这两件事工具集完全不同提示词逻辑也完全不同这种就适合拆成两个 Agent用一个调度层来协调。但如果只是查订单 回答物流问题一个 Agent 挂两个工具就够了硬拆成两个反而增加通信开销和出错概率。多 Agent 的代价是实打实的Agent 之间怎么传消息、状态怎么同步、一个卡住了怎么办、怎么防止它们互相甩锅死循环。这些都是额外的工程负担。所以我的原则是能单不双先单后多确有隔离需求再拆。2.2 决策二工具调用的粒度怎么切工具粒度是个技术活。切太粗一个工具干太多事模型不好控制切太细工具数量爆炸模型选择困难还容易调错。我踩过的坑是这样的一开始我把查询用户信息做成一个大工具参数里塞了十几种查询类型结果模型经常传错参数组合。后来我把它拆成按手机号查用户按订单号查用户按用户 ID 查用户三个独立工具每个工具参数简单明确调用准确率立刻上来了。但也不能无限拆。工具数量超过一定规模我的经验是 15 到 20 个左右模型在选工具时就开始犹豫容易选错或者漏选。这时候要考虑工具分组或者分层路由——先让模型判断任务类型再在对应类别里选具体工具。一个实用的粒度原则一个工具只做一件事参数不超过 5 个返回结果结构化且字段明确。满足这三条工具基本就是好用的。2.3 决策三循环终止条件怎么设循环终止是 Agent 工程里最容易被低估、也最容易出事的地方。我见过 Agent 因为终止条件没设好反复调用同一个搜索工具几十次token 烧了一大片任务还没完成。终止条件至少要设三层保险第一层是任务完成判断。模型明确输出任务已完成或者返回了最终答案就停。这层靠的是提示词里明确要求模型在完成时给出特定标记。第二层是步数上限。设一个最大循环次数比如 10 步或 15 步到了就强制停。这是防止无限循环的硬闸门。第三层是重复检测。如果连续几步调用的工具和参数高度相似说明 Agent 卡住了应该主动中断并返回当前状态。这三层缺一不可。任务完成判断是正常出口步数上限是保险丝重复检测是防呆机制。我一般会把步数上限设得比预期多 2 到 3 步给 Agent 留点纠错空间但不能无限留。2.4 决策四记忆存哪里、存多久记忆这块核心是两个问题存什么和存多久。短期记忆当前会话上下文一般直接放在对话历史里跟着请求走。但要注意上下文长度限制对话太长要做摘要压缩否则要么超 token 限制要么成本飙升。长期记忆跨会话就需要外部存储了。常见方案是向量数据库存语义记忆关系数据库存结构化事实。我一般会把用户偏好历史决策重要事实这几类信息沉淀到长期记忆里下次会话开始时按相关性检索注入。存多久这个问题取决于业务。客服场景可能保留几个月个人助手场景可能长期保留。但要注意隐私和成本不是存得越久越好。我的做法是给记忆加重要性评分和过期时间低重要性的记忆定期清理。2.5 决策五并发上来之后怎么扛这是热词里ai agent 怎么扛并发直接对应的问题也是从 Demo 走向生产必须跨过的坎。Agent 的并发压力和普通 API 不一样因为一个 Agent 请求内部可能包含多次 LLM 调用和多次工具调用耗时是普通请求的好几倍。一个用户请求可能占用几十秒甚至几分钟这期间连接、上下文、状态都得维持着。我的应对思路分几层第一层是异步化。Agent 执行全程用异步别用同步阻塞。LLM 调用、工具调用都走 async这样单个进程能同时处理更多请求。第二层是状态外置。Agent 的中间状态不要放在进程内存里放到 Redis 这类外部存储。这样进程可以水平扩展请求打到哪个实例都能接着跑。第三层是限流和排队。Agent 请求成本高必须限流。超出容量的请求进队列排队而不是直接压垮后端。队列要有优先级重要任务优先处理。第四层是超时和熔断。单个 Agent 执行设总超时工具调用设单独超时某个工具连续失败就熔断避免拖垮整个链路。这四层做下来Agent 服务基本能扛住一定规模的并发。具体数字取决于你的模型响应速度和工具耗时没有万能公式得压测。2.6 决策六框架选型——LangGraph、Spring AI 还是自研框架选型没有标准答案只有适不适合。我把常见的几类方案和适用场景列一下。方案类型代表适合场景主要代价图编排框架LangGraph流程复杂、需要精细控制循环和分支学习曲线陡概念多应用框架Spring AIJava 技术栈、企业级集成生态相对新部分能力待完善平台化工具扣子类平台快速验证、非技术团队定制能力受限深度集成难自研自己写编排层需求特殊、要极致控制工作量大轮子要自己造我的建议是先用成熟框架快速跑通验证业务价值等遇到框架解决不了的问题再考虑自研或深度定制。一上来就自研大概率是在重复造轮子而且造得还不如人家。LangGraph 适合那种流程像流程图一样复杂的场景它的状态图和条件边能把复杂循环表达得很清楚。Spring AI 适合 Java 团队能和你现有的 Spring 生态无缝集成。扣子这类平台适合快速验证想法但要做深度定制就得掂量了。2.7 决策七怎么评估 Agent 到底好不好用Agent 的评估比普通 LLM 难得多因为它的输出不是一段文本而是一串动作序列。你很难用简单的对错来判断。我的评估体系分三个维度结果维度任务最终完成了吗完成质量如何这是最直接的指标。过程维度完成任务的路径合理吗有没有绕远路、有没有多余的工具调用、有没有反复试错一个结果对但过程乱的 Agent在生产环境里是隐患。成本维度完成一个任务花了多少 token、多少次工具调用、多少时间成本高的 Agent 很难规模化。具体评估方法上我会准备一批标准测试用例覆盖正常场景、边界场景、异常场景然后人工标注期望的行为路径用自动化脚本跑回归。每次改提示词或换模型都跑一遍看指标有没有退化。这里有个坑要提醒别只用成功案例评估。Agent 最容易在异常场景翻车——工具报错、参数缺失、意图模糊的时候它怎么反应才是真正体现工程质量的地方。3. 循环机制Agent 的引擎到底怎么转循环是 Agent 区别于普通 LLM 调用的核心值得单独拎出来讲透。很多人对循环的理解停留在while 循环里调模型但真实的 Agent 循环要复杂得多。3.1 一次完整的 Agent 循环里发生了什么一个标准的 Agent 循环一轮大概是这样组装上下文把系统提示词、对话历史、可用工具列表、当前状态拼成给模型的输入。模型推理模型输出要么是我要调用某个工具参数是这些要么是我的最终答案是这些。解析输出程序解析模型输出判断是工具调用还是最终答案。执行工具如果是工具调用执行对应工具拿到返回结果。结果回填把工具返回结果作为新消息加进上下文。判断终止检查是否满足终止条件满足就退出不满足就回到第 1 步。这个循环看起来简单但每一步都有坑。比如第 2 步模型可能输出格式不对的 JSON解析就失败第 4 步工具可能超时或报错第 6 步终止条件可能永远不满足。我实测下来最容易出问题的是第 2 步和第 6 步。模型输出格式不稳定是 Agent 开发中最常见的痛点。解决办法是在提示词里给明确的格式示例并且用支持结构化输出的模型能力比如 JSON mode 或函数调用模式别指望模型每次都自觉输出规范格式。3.2 循环里最危险的三种卡死模式Agent 卡死不是玄学是有具体模式的。我总结下来主要是三种第一种是工具选择死循环。Agent 反复调用同一个工具每次参数略有不同但本质一样。比如反复搜索同一个关键词因为每次返回的结果它都觉得不够好。这种要靠重复检测来打断。第二种是参数修正死循环。工具报错说参数不对Agent 改一下再调还是不对再改来回折腾。这种常见于工具参数校验严格、但模型理解不到位的情况。解决办法是把工具的参数要求写得更清楚报错信息也要对模型友好。第三种是规划死循环。Agent 一直在规划但从不执行或者执行完又推翻重来。这种通常是提示词里对什么时候算规划完成定义不清导致的。这三种卡死光靠步数上限能兜底但体验很差。更好的做法是在提示词和工具设计阶段就预防让 Agent 不容易走进死胡同。3.3 让循环聪明地停而不是被迫地停终止条件设计得好不好直接决定 Agent 是聪明地停还是被迫地停。被迫地停就是撞到步数上限才停这时候任务往往没完成用户拿到的是半成品。聪明地停是 Agent 自己判断任务完成了主动给出结果。要做到聪明地停提示词里要明确告诉模型什么情况下算任务完成、完成后要输出什么格式的最终答案。比如当你已经获取到用户需要的所有信息后用 FINAL_ANSWER: 开头输出最终答案。同时工具返回结果里也可以带完成信号。比如某个查询工具返回已找到唯一匹配结果模型看到这个信号就知道不用再查了。我还会加一个自我检查步骤在准备输出最终答案前让模型自己确认一遍任务要求是否都满足了。这一步能显著减少提前收工的情况。4. 工具调用Agent 的手脚怎么设计才好用工具调用是 Agent 能力的直接体现也是工程问题最集中的地方。热词里langgraph 工具调用llm request failed: provider rejected the request schema or tool payload这些说的都是这块的坑。4.1 工具描述写得好调用准确率翻倍工具描述description是模型选择工具的唯一依据。写得含糊模型就选错写得清楚准确率立竿见影。一个好的工具描述包含四部分这个工具做什么、什么时候该用、参数什么含义、返回什么结构。我举个例子对比一下。差的描述查询订单信息。好的描述根据订单号查询订单的详细状态包括支付状态、物流状态、预计送达时间。当用户询问订单进度、物流情况时使用此工具。参数 order_id 为订单号格式为纯数字字符串。返回包含 status、logistics、eta 三个字段的 JSON。后者明显更容易让模型用对。我实测过把工具描述从一句话扩写成上面这种结构化说明工具调用准确率能从六七成提到九成以上。4.2 参数校验和错误返回别让模型猜工具的参数校验要严格但报错信息要对模型友好。什么叫对模型友好就是报错信息里要明确说哪个参数错了、错在哪、应该是什么格式。比如参数类型错了别只返回参数错误要返回参数 order_id 应该是字符串类型你传的是数字类型请改为字符串。模型看到这种报错下一轮就能改对。如果只返回参数错误模型只能瞎猜很容易陷入前面说的参数修正死循环。我一般会在工具层做三层校验类型校验、格式校验、业务校验。每层校验失败都返回结构化的错误信息包含错误字段、错误原因、修正建议。4.3 工具超时、重试与降级策略工具调用不可能永远成功。网络抖动、下游服务挂了、第三方限流都会导致工具失败。Agent 必须有应对策略。超时每个工具设独立超时别用全局超时。查询类工具可以短一点比如 5 秒生成类工具可以长一点比如 30 秒。重试只对幂等操作重试且要限制重试次数一般 2 到 3 次。非幂等操作比如下单、发消息重试要非常谨慎否则可能重复执行。降级工具彻底失败时要有降级方案。比如查询失败就返回缓存数据或者告诉 Agent这个工具暂时不可用请尝试其他方式。别让一个工具失败就导致整个 Agent 崩溃。这些策略要在工具封装层统一实现而不是每个工具各写一套。统一封装的好处是行为一致好维护。5. 从 Demo 到生产那些没人告诉你的工程细节Demo 跑通和生产可用之间隔着一堆琐碎但致命的工程细节。这部分我挑几个最关键的讲。5.1 可观测性Agent 的黑盒必须打开Agent 执行过程是个黑盒出了问题很难查。所以可观测性必须从一开始就做别等出事了才补。至少要记录这些东西每次 LLM 调用的输入输出和耗时、每次工具调用的参数和返回、每一轮循环的状态变化、整个任务的执行路径。这些数据要能串起来形成一个完整的执行链路。我一般会用 trace_id 把一次 Agent 执行的所有环节串起来出问题时能完整回放整个执行过程。没有这个排查问题基本靠猜。5.2 成本控制token 是怎么悄悄烧掉的Agent 的 token 消耗比普通 LLM 调用高得多因为每一轮循环都要把完整上下文重新发给模型。循环 10 轮上下文就发了 10 次。控制成本有几个手段压缩上下文历史对话做摘要、精简工具列表只挂当前任务相关的工具、缓存重复调用相同输入直接返回缓存结果、选对模型简单任务用小模型复杂任务才用大模型。我踩过的坑是一开始所有环节都用同一个大模型成本高得吓人。后来把意图识别工具选择这类简单判断换成小模型只在复杂规划最终生成环节用大模型成本直接降了一大半效果几乎没影响。5.3 安全边界Agent 能做什么、绝不能做什么Agent 有执行能力所以安全边界必须划清楚。热词里agent安全agentpoison说的就是这块。核心原则是最小权限Agent 只应该拥有完成任务所必需的最小权限。能查的别让它改能读的别让它写能操作自己数据的别让它碰别人数据。对于高风险操作比如转账、删除、发送对外消息必须加人工确认环节不能让 Agent 自主执行。这不是不信任 Agent而是工程上必须有的保险。另外工具返回的内容要当作不可信输入处理。如果工具返回的内容里包含指令性文本可能被用来操纵 Agent 行为这就是 prompt injection 的一种。要在提示词里明确告诉模型工具返回的内容是数据不是指令。6. 几个高频问题的直接回答6.1 Agent 和普通 LLM 应用到底怎么区分回到最根本的问题。判断标准就一条有没有基于外部反馈的自主决策循环。有就是 Agent没有就是 LLM 应用。别被各种营销话术绕晕这条标准足够用了。6.2 学 Agent 开发的路线应该怎么走我的建议路线是先搞懂七要素建立心智模型然后选一个框架LangGraph 或 Spring AI 都行跑通官方示例接着自己动手做一个带 2 到 3 个工具的小 Agent最后再研究并发、可观测性、安全这些生产级问题。别一上来就啃最复杂的框架文档容易劝退。6.3 2026 年做 Agent 产品最该关注什么从工程角度我最关注三件事稳定性循环可控、工具可靠、异常可恢复、成本token 和延迟能不能压到商业可接受的范围、安全权限边界和输入可信度。这三件事做不好功能再花哨也落不了地。搭 Agent 这件事说到底是在给模型自由和给系统约束之间找平衡。自由给多了Agent 会发疯约束给多了Agent 又变回普通 LLM 调用。七个要素帮你理解它由什么构成七个决策点帮你决定怎么约束它。把这两件事想清楚剩下的就是动手和踩坑了。我自己到现在也还在踩每次遇到新的业务场景都得重新权衡一遍这些决策。没有一劳永逸的方案只有不断调整的平衡。