这两年真正动手做过 AI Agent 的人大概率都有过同一个体验模型本身并不差差的是怎么把模型组织成一个能稳定干活的系统。我最早接触 Agent 的时候想法非常朴素——把大模型接上几个工具让它自己调用就行了。结果一到真实任务就露馅任务复杂度稍微上来模型就开始在中间步骤里“自由发挥”要么工具返回了错误它却视而不见要么在同一个失败操作上反复重试白白烧掉大量 token。后来我被逼着换了个思路把一个 Agent 彻底拆开逐个环节排查才发现 Agent 工程化的问题从来不是“模型聪不聪明”而是组成 Agent 的各个要素有没有被认真设计七个关键决策点有没有被正面做过取舍。这篇文章就是当时拆解过程的完整复盘。我会把 Agent 工程实现中绕不开的七个组成要素讲清楚再沿着搭建时要回答的七个决策点逐个展开每一步都给出我实测过的坑和调整方向。适合正在用 LangChain、LlamaIndex 这类框架开发 Agent或者打算从零自己搭建一套 Agent 的工程师阅读。如果你还停留在“跑通 Demo”阶段这篇文章能帮你省掉不少“看起来能跑、一用就崩”的冤枉路。1. 七要素拆解先搞清楚 Agent 在工程上到底由什么组成我见过不少人把 Agent 直接等同于“大模型 工具调用”。做 Demo 展示的时候这个理解勉强够用一旦进入真实业务就会发现自己缺了一堆东西。从工程实现的角度看一个完整的 Agent 至少要包含七个要素推理核心、规划能力、记忆系统、工具调用、行动执行、反馈机制、运行环境。它们不是七个可以独立插拔的插件而是互相耦合的七个环节——你改任何一个都会影响其他六个的行为表现。1.1 推理核心与规划层Agent 的“大脑”和“路线图”推理核心是那个大模型本身负责理解用户目标、处理环境返回的信息、生成下一步决策。这里要强调一个容易被忽略的判断模型的能力边界直接决定了 Agent 的上限。我在对比不同模型的时候发现指令遵循能力和函数调用function calling的稳定性比通用知识测试分数重要得多。Agent 本质上在循环执行“读状态 - 决策 - 输出结构化动作”模型一旦在某一步输出格式不对整个闭环就得中断。规划层是“路线图”它把一个大目标拆解成模型可以逐步执行的小步骤。最简单的做法是让模型在每一轮输出时写下“当前任务、下一步动作”复杂一点的先让模型产出完整计划再逐项执行。这个环节最常见的误区是把所有步骤一股脑写进 System Prompt告诉模型“先做 A再做 B再做 C”。任务一变Prompt 就得跟着改毫无扩展性。工程化的做法是让模型根据目标动态生成步骤而不是在提示词里写死执行路径。1.2 记忆与工具Agent 的“笔记本”和“手”记忆分为短期和长期两部分。短期记忆就是当前会话的上下文窗口负责记录本回合内发生的事长期记忆是存放在外部的历史信息比如用户偏好、领域知识、历史操作记录需要时再检索回来。不少 Agent 项目在初期不做长期记忆也能跑但只要业务涉及跨会话或者大量历史数据记忆系统就成了硬需求——不做的代价是上下文被撑爆既费 token又降低准确率。工具层则是 Agent 能“动手”的关键。没有工具模型只能输出文字所有回答都停留在“建议”层面有了工具模型才能查数据库、发 HTTP 请求、读写文件、操作外部系统。工具层要处理的核心工程问题有三个工具描述是否足够清晰输入参数 schema 是否完备以及调用失败时错误信息能否被模型正确理解。这三个问题我会在决策点四里详细展开。1.3 行动与反馈闭环是 Agent 与普通提示词工程的分水岭行动层负责把模型决策变成真实可执行的动作比如发起一次 API 调用、执行一段代码。这里很多人会忽略“结果怎么送回模型”这个细节工具返回的数据、报错信息、超时状态都要以结构化方式写回上下文模型才可能在下一步做出正确判断。反馈机制则利用这些结果修正后续的决策方向。一个闭环的 Agent每一步都发生在“行动 - 观察 - 决策”的循环里直到完成目标或者触发终止条件。这也是 Agent 和普通提示词工程最本质的区别普通提示词是“一次性输出”Agent 是“多轮自我纠错”。没有反馈闭环你做的其实只是一个“会调工具的聊天机器人”不算是工程意义上的 Agent。1.4 运行环境Agent 能碰到哪一层决定了它能造成多大影响运行环境是 Agent 运行时的权限边界——它能读哪些数据、调用哪些服务、操作哪些系统。做 Demo 时放开权限没有感觉上了生产环境权限不收敛一定会出问题。我见过一个内部 Agent 因为工具权限过宽在一次测试中误删了测试环境的一批数据直接引发事故。工程上务必做到最小权限能只读就只读能隔离就隔离能加审计就加审计。别等到出了问题再回来补权限那时候代价往往已经付过了。2. 决策点一模型选型——先别盯榜单先看 Agent 的“稳定调用”能力很多人选模型时最爱比较“哪家排行榜分数高”但对 Agent 工程来说最关键的指标不是通用推理分数而是函数调用function calling的稳定性和指令遵循率。模型能不能稳定输出“该调用哪个工具、参数是什么”的结构化结果直接决定 Agent 能不能跑下去。2.1 为什么函数调用稳定性比分数更重要一个 Agent 任务里模型几乎每一轮都要输出结构化动作。只要模型经常输出格式错误、参数缺漏、或者幻觉出不存在的工具名再强的推理能力也发挥不出来。我在对比实测中发现相同任务在不同模型上的成功率差异可以非常大特别是工具数量超过十个时有些模型会开始频繁选错工具。所以我的选型习惯是先建一个“Agent 专项测试集”专门考察多工具场景下的正确调用率、参数准确性、错误恢复能力而不是靠几个问答样本来拍板。2.2 上下文长度是加分项不是必选项现在聊天模型普遍宣传 200K 上下文不少团队因此觉得买了大上下文模型记忆问题就解决了。这是典型的错觉。上下文窗口再大塞满之后照样影响延迟和效果而且 Agent 每轮带着状态走几十轮就把窗口打满。与其为超大上下文付出高昂成本不如在记忆层、上下文压缩上做工程处理具体方案我在决策点五里讲。选型时更应该看“有效注意力范围内的准确度”而不是“能装多少 token”这个数字。2.3 成本与并发不要只算单步单价要算单任务总成本Agent 跟普通聊天的成本模型完全不同。一次问答可能花一两万 token一个复杂 Agent 任务可能循环几十步每一步都把累积的上下文送到模型里单任务总 token 会非常可观。所以选型时不能只看模型单价还要估“平均步数 x 平均每步 token”这两个变量。我在一个项目里做过真实测算用某家大参数模型做 Agent单个任务总成本比中等参数模型高出五倍成功率只提升了六个百分点。后来我们微调了架构用中等模型加更精细的工具描述把成功率和体验拉回同一水平成本还降了一半。这个案例说明模型选型很少是“选最好的”而是“在成本、稳定性、上下文策略之间做权衡”。3. 决策点二规划策略——ReAct 还是 Plan-and-Execute本质是“探索”与“流程”的取舍第二个无论如何都要正面回答的决策是 Agent 怎么组织自己的行动步骤每一步“想一下再做一下”ReAct还是“先整体规划再逐步执行”Plan-and-Execute。这两个模式看着只是顺序不同实际跑起来体验天差地别。3.1 两种模式各自的长处和短板ReAct 模式让模型先思考当前状态做出一个动作观察结果再思考下一步。它的最大优势是灵活特别适合你不知道确切步骤、必须边做边摸索的探索型任务。缺点是步数越多token 消耗越大而且模型在中后期容易逐渐偏离最初的任务目标——这是长任务中最常见的失控方式。Plan-and-Execute 模式让模型先把整个任务拆成一份步骤计划再按计划逐一执行。它的优势是整体感强任务目标一直摆在那里不容易跑偏适合步骤相对明确的业务场景。缺点也很明显如果第一步计划就错了后面会全盘照着错误方向走所以必须额外设计“计划修正”机制在发现某一步不符合预期时重新规划。3.2 实际项目里怎么选混合路线最稳我的经验是优先考虑 Plan-and-Execute 的变体而不是让 Agent 完全自由地 ReAct。理由很简单真实业务中你通常对任务有相当程度的了解可以做一个初步规划即使模型计划得不够好也能通过“每步执行后对照计划”来纠正。纯 ReAct 在长时间任务中的失控率明显更高。更稳的折中方案是混合首轮让模型产出初步计划之后每个执行步让模型生成“当前状态 下一步动作 这一步对整体计划的影响”。这样既保留了规划的锚点又保留了执行时的灵活性。我在生产环境里推荐的就是这个形态它比单纯 ReAct 少了很多“跑着跑着忘了目标”的情况。3.3 终止条件和失败重试必须提前写死在工程里选好规划模式之后还要给 Agent 定死终止条件目标达成、达到最大步数、或模型判定失败三者必须至少有一个生效。否则 Agent 会无限循环费用跟着失控。我在生产环境里看到过太多因为重试策略不明确导致的死循环模型连续十次调用同一个失败工具照样不放弃。同时要设计失败重试的决策链工具调用出错时是重试、换一个工具、还是上报失败这个判断不能完全交给模型自由发挥应该在工程层预设好规则比如“固定工具连续失败两次以上进入人工兜底流程”。没有这层防护Agent 的稳定性永远建立在对模型自律性的幻想上。4. 决策点三记忆架构——“什么都往向量库里塞”其实是最贵的偷懒记忆系统在 Agent 工程里被高估的同时也被低估。高估的是大家相信“加个向量数据库Agent 就有记忆了”低估的是真正做好记忆牵涉到的工程细节远比想象中多。如果所有历史都无脑往向量库里塞你会很快发现检索回来的内容经常不是最关键的而是最相似的模型反而更糊涂。4.1 记忆分层的工程设计我建议按职能把记忆拆成三层。第一层是工作记忆负责当前任务上下文保留最近几轮的对话和工具结果用完后做压缩第二层是情景记忆负责跨会话的用户偏好、关键决策、历史任务摘要可以用结构化存储加向量检索第三层是语义知识负责领域知识库内容通常预先构建与单个用户历史关系不大。三层各自对存储方案的要求完全不同。工作记忆留在上下文里由 token 管理控制情景记忆比较适合向量库但没有必要每轮都查语义知识只在当前任务明确涉及某个领域时按需检索。很多人做出来的 Agent 变慢往往不是模型慢而是每轮都去向量库捞一大批无关片段把上下文塞满模型判断力自然下降。4.2 写长期记忆的门槛要设高一点最容易犯的错误就是“全量写入”——把每一轮工具输出、每一段用户对话都往向量库里写。这样做短期内看着“记录得很全”用一周之后检索质量就会急剧下降因为相似的片段实在太多了召回的正确率越来越差。真正值得写入长期记忆的是那些“对后续任务有确定性价值”的信息用户明确表达的偏好、用户纠正过的错误认知、任务最终结果、关键业务实体。我建议每次写入前先用模型做一个判断——“这条信息如果未来被检索到会不会帮助 Agent 做更好的决策”有价值才写入。这个“记忆整理”步骤会多花一次模型调用但换来的是长期记忆系统的可用性这笔账非常划算。4.3 记忆的时效性过期记忆比没有记忆更糟糕实战里我还发现记忆的“过期策略”是必须明确设计的点。用户偏好会变、历史订单会更新、地址会改动如果旧信息一直占据检索权重Agent 就会被过期记忆误导。简单可行的做法是给每条记忆增加时间戳和置信度字段检索时做加权排序超过有效期的降权或者直接清理。这一层在 Agent 上线初期看不到明显作用但运行时间越长它的价值越突出。我见过好几个项目上线一个月后效果明显下滑排查下来都不是模型退化了而是长期记忆里积累了太多过期且互相冲突的信息把决策信号搅浑了。早点把过期策略做进去后面省的是整夜的排查时间。5. 决策点四工具接口设计——模型没法跟你“心有灵犀”所以工具描述就是契约工具层是 Agent“动手”的通道但很多人把它理解为“注册几个 Python 函数”就完事了。真正的工程化是把工具设计成一份模型和系统都能理解的接口契约。你的工具描述写得好不好直接决定模型选对工具的概率你的返回值规不规范直接决定模型能不能理解执行结果。5.1 工具描述写“什么时候用”别只写“能做什么”在函数描述里光写“查询订单”远远不够。模型做决策时需要区分的是“该查订单还是该查库存”所以描述必须包含使用场景。比如查询订单——当用户询问订单状态、物流信息、售后进度时使用查询库存——当用户询问商品是否有货、库存数量、补货时间时使用。加上这类场景说明工具选择准确率能在不更换模型的前提下获得明显提升。这是我每次搭新 Agent 都优先做的低成本优化。5.2 工具粒度太粗会失控太细会噎住工具粒度是另一个关键决策。如果把“整站下单流程”做成一个工具模型无法控制中间步骤出错了也很难定位可如果拆得过细十几个参数让模型一次性填对填错率反而上升。实践下来比较稳的做法是中等粒度加参数收敛一个工具只完成一个有明确输入输出的子任务参数尽量控制在五个以内能做枚举就别用自由文本能设计默认值就别让模型必须填。整体上参数越是收敛模型调用工具的出错率越低。工具数量多了之后还会遇到一个问题功能相近的工具会让模型产生选择困难。这时候要在描述里明确写清楚差异点甚至可以直接写“本工具与 XX 工具的区别在于……”把容易混淆的边界直接点破。这种描述层面的“排错”比换模型便宜得多。5.3 返回结构和错误处理必须形成契约工具返回给模型的格式建议统一成 JSON 结构明确区分成功状态、业务数据、错误信息。一个血泪教训是错误信息写得含糊比如只返回“调用失败”模型经常理解成“工具成功了但没有结果”然后在没有任何实质进展的情况下反复重试同一个工具。所以每条错误信息里都要尽量带上“失败原因 下一步建议”。前端数据异常返回失败代码网络超时返回超时标记权限不足返回权限错误并明确告诉模型“不要重试”。这些约定都是 Agent 稳定性的隐形支柱越早定下来越好。6. 决策点五上下文与状态管理——Token 预算是 Agent 的命脉做过 Agent 的人都会承认上下文窗口是目前最稀缺的资源。模型调用费用、延迟、最终效果全都和上下文内容直接相关。如果不加控制一个多步任务会随着历史消息越堆越长先是变慢然后是变笨最后直接跑不动。6.1 三种上下文裁剪策略以及我习惯的组合常见的裁剪手段有三种。第一种是直接截断最旧的消息实现最简单但会丢掉早期关键决策第二种是滚动总结每 N 轮历史就调用模型生成一段摘要用摘要替换旧轮次适合对话型 Agent第三种是关键信息抽取把当前状态、用户约束、已完成步骤提取成一个结构化“状态块”放在每轮上下文最前面。我的实践是把三种策略组合起来每轮开始前对当前上下文做一次“总结 状态块”压缩用摘要替换掉中间轮的原始消息只保留最近三五轮原始消息供模型精细决策。这样既能控制 token 总量又不丢失任务关键信息。实测下来Agent 在长任务里的稳定性和成本控制都有明显改善。6.2 系统提示词也要做 Token 瘦身系统提示词是每轮调用都要计入的固定开销。很多人喜欢往里面塞大量公司资料、背景说明、规则手册动辄两三千 token。问题在于这些内容不是每轮都重要反而会摊薄模型对当前步骤的注意力。工程做法是“分层注入”把真正时刻需要的核心规则放进系统提示词按需使用的知识放到知识库在相关步骤触发时再检索注入。我做过一次很直观的优化把系统提示词从 2800 token 压到 600 token模型工具选择的准确率反而提升了 7 个百分点。内容少了模型注意力更聚焦效果自然上来了。6.3 状态持久化Agent 会话比 HTTP 请求活得久得多Agent 任务动辄持续几十分钟甚至几小时中途进程挂了怎么办会话状态必须做持久化。正确的做法是每轮循环结束后把当前任务计划、已完成步骤、状态块、决策历史全部写入存储。这样进程重启后Agent 能恢复到最近的决策点继续执行而不是从头再来。这里要特别区分两个概念上下文是给模型看的“当前信号”状态库是给程序用的“执行快照”。两者各管各的不要图省事把所有状态都塞进对话历史里。一旦混在一起你既没法做精准的 token 压缩也没法在重启后准确恢复。这个是很多自研 Agent 框架设计时的通病。7. 决策点六单 Agent 还是多 Agent——单体没做稳之前别急着让人开会多 Agent 是这两年的热门话题很多人一上来就规划“三个 Agent 协作完成任务”的架构。但工程上我必须先说一句逆耳的话绝大多数业务场景单 Agent 加工具已经够用。多 Agent 引入的沟通开销、上下文分裂、调试复杂度都是成倍增长的。它不是一个免费升级而是一笔需要算清楚的投资。7.1 什么情况才真正需要多 Agent我的判断标准很直白单 Agent 的上下文已经不可控或者任务需要多个专业角色并行处理时才考虑多 Agent。典型场景包括一个 Agent 负责理解用户意图另一个 Agent 负责数据操作还有一个负责审核输出三者职责互不重叠。注意职责必须“不重叠”否则大家都会抢着做同一件事结果互相矛盾。如果只是任务步骤复杂优先靠规划、记忆、工具设计去解决而不是拆分角色。多 Agent 最常见的失败形态是几个 Agent 各干各的没有一个统一目标最后产出互相冲突的内容效果比单 Agent 还差。分布式系统的复杂度不会因为加了层模型就消失。7.2 协作模式主从编排比议会讨论更可控多 Agent 的协作模式有很多种我建议从最简单的主从模式开始一个编排 Agent 负责拆解任务、分派子任务、汇总结果若干个执行 Agent 只负责执行分配下去的子任务。这种模式的调试性最好因为你总能定位到“是编排者决策错了还是某个执行者执行错了”。议会讨论模式看起来很美——多个 Agent 自由讨论、投票决定方案——但在生产环境里稳定性很差。投票过程消耗大量 token模型之间又容易相互说服最后得到的常常不是更理性的结论而是更强词夺理的结论。不是不能做但它更适合用于研究性项目不适合默认业务链路。7.3 多 Agent 之间的上下文隔离比任何框架都重要多 Agent 之间必然要传递信息但工程上不要把所有内容都塞进一个共享上下文。应该只传递“任务描述 必要数据 约束条件”。每个执行 Agent 都有自己的独立上下文避免执行过程中的中间噪音污染其他 Agent。需要共享的状态应该写入一个统一状态中心各 Agent 按需读取。其实这又回到了记忆架构的设计Agent 与 Agent 之间的通信本质上就是记忆系统的一次接口调用而不是“让所有 Agent 围观同一份聊天记录”。顺着这个思路设计多 Agent 系统会清爽很多。8. 决策点七可观测性与评测——没有 Trace 的 Agent 不值得上线普通后端接口出了问题你靠日志和报错堆栈就能定位。Agent 不一样它是非确定性的多步系统每轮都在决策和行动无法用普通接口测试保证可用。没有可观测性Agent 出错时你只能对着模型的原始输出猜那效率低得可怕。这也是 Agent 工程和普通后端工程最大的不同必须提前设计“看得到模型每一步在想什么、做了什么”的观测体系。8.1 可观测性的三个层次日志、Trace、评估最基础的是日志每个节点的输入、输出、工具调用结果、token 数、耗时都记录下来。再往上一层是 Trace把一次 Agent 任务的完整决策链串起来用户问了什么、模型想了什么、调了哪个工具、拿到了什么结果、下一步怎么决策。光有日志没有 Trace你仍然很难把碎片拼成完整画面。第三层是评估准备一组标准任务定期跑回归看成功率、平均步数、平均成本、延误率这些指标的变化。三个层次缺一个你优化 Agent 就只能靠感觉。尤其到了后期调 Prompt、调工具描述时没有评估体系你根本说不清这次改动到底是让系统变好了还是变差了。8.2 评测集要提前建失败用例要持续沉淀很多团队把评估放在 Agent 开发完成后这是顺序搞错了。正确做法是先建评测集再开发功能。比如做一个客服 Agent先准备五十个能代表真实用户分布的典型问题标注好期望的工具调用路径和期望的最终回答每次修改后跑一遍全部用例哪条失败就说明哪次改动引入了回归。评测集还应该是活的。每次真实环境里 Agent 表现不佳的案例都值得整理进评测集里长期维护成一个“失败用例库”。这大概是最笨但也最有效的 Agent 质量提升方式——每解决一个失败用例系统就真实地变好了一点而不是靠感觉调参。8.3 上线的灰度与兜底比模型切换更重要上线时不要全量切流量一定要灰度。要给 Agent 配置“人工兜底”的通道Agent 处理不了时能顺利转人工或走默认流程。很多自研 Agent 项目翻车不是因为模型选得不好而是上线前只测了 Happy Path一遇到边界情况就崩还没有兜底预案。Agent 的稳定性永远不能靠模型自觉只能靠工程上的失败降级和人工介入预案。你可以先让 Agent 只处理它最有把握的任务类型其他全部转人工等成功率稳定上来了再逐步扩大边界。这个渐进过程才是 Agent 上生产环境的正确姿势。这套“七要素 七个决策点”的框架我自己用了很多遍之后最大的体会是Agent 从来不是“搭出来”的而是“调出来”的。每个决策点都没有标准答案并且它们互相牵制——选了便宜的模型可能就得在工具描述上多花功夫选了 Plan-and-Execute就得同步设计计划修正机制选了多 Agent就要接受调试成本的上升。你不可能在方案评审阶段一次性全想对但只要清楚每个决策点背后的权衡迭代起来就有明确方向。最后分享一个我一直在用的小技巧每次只优化一个决策点然后用同一套评测集跑三遍盯住成功率、平均步数、平均成本三个指标。如果一次改动让成功率上升但成本暴涨或者成本降了但成功率明显下滑那就说明这个改动不划算需要继续找平衡点。按这个节奏迭代几个月你会明显看到 Agent 越来越稳定而且每一分改进究竟花在了哪里心里都有数。 
长河君 · 2026/10/8 4:50:20 · 阅读 1.2k AI Agent工程化实战：七要素拆解与七个关键决策点全复盘
这两年真正动手做过 AI Agent 的人大概率都有过同一个体验模型本身并不差差的是怎么把模型组织成一个能稳定干活的系统。我最早接触 Agent 的时候想法非常朴素——把大模型接上几个工具让它自己调用就行了。结果一到真实任务就露馅任务复杂度稍微上来模型就开始在中间步骤里“自由发挥”要么工具返回了错误它却视而不见要么在同一个失败操作上反复重试白白烧掉大量 token。后来我被逼着换了个思路把一个 Agent 彻底拆开逐个环节排查才发现 Agent 工程化的问题从来不是“模型聪不聪明”而是组成 Agent 的各个要素有没有被认真设计七个关键决策点有没有被正面做过取舍。这篇文章就是当时拆解过程的完整复盘。我会把 Agent 工程实现中绕不开的七个组成要素讲清楚再沿着搭建时要回答的七个决策点逐个展开每一步都给出我实测过的坑和调整方向。适合正在用 LangChain、LlamaIndex 这类框架开发 Agent或者打算从零自己搭建一套 Agent 的工程师阅读。如果你还停留在“跑通 Demo”阶段这篇文章能帮你省掉不少“看起来能跑、一用就崩”的冤枉路。1. 七要素拆解先搞清楚 Agent 在工程上到底由什么组成我见过不少人把 Agent 直接等同于“大模型 工具调用”。做 Demo 展示的时候这个理解勉强够用一旦进入真实业务就会发现自己缺了一堆东西。从工程实现的角度看一个完整的 Agent 至少要包含七个要素推理核心、规划能力、记忆系统、工具调用、行动执行、反馈机制、运行环境。它们不是七个可以独立插拔的插件而是互相耦合的七个环节——你改任何一个都会影响其他六个的行为表现。1.1 推理核心与规划层Agent 的“大脑”和“路线图”推理核心是那个大模型本身负责理解用户目标、处理环境返回的信息、生成下一步决策。这里要强调一个容易被忽略的判断模型的能力边界直接决定了 Agent 的上限。我在对比不同模型的时候发现指令遵循能力和函数调用function calling的稳定性比通用知识测试分数重要得多。Agent 本质上在循环执行“读状态 - 决策 - 输出结构化动作”模型一旦在某一步输出格式不对整个闭环就得中断。规划层是“路线图”它把一个大目标拆解成模型可以逐步执行的小步骤。最简单的做法是让模型在每一轮输出时写下“当前任务、下一步动作”复杂一点的先让模型产出完整计划再逐项执行。这个环节最常见的误区是把所有步骤一股脑写进 System Prompt告诉模型“先做 A再做 B再做 C”。任务一变Prompt 就得跟着改毫无扩展性。工程化的做法是让模型根据目标动态生成步骤而不是在提示词里写死执行路径。1.2 记忆与工具Agent 的“笔记本”和“手”记忆分为短期和长期两部分。短期记忆就是当前会话的上下文窗口负责记录本回合内发生的事长期记忆是存放在外部的历史信息比如用户偏好、领域知识、历史操作记录需要时再检索回来。不少 Agent 项目在初期不做长期记忆也能跑但只要业务涉及跨会话或者大量历史数据记忆系统就成了硬需求——不做的代价是上下文被撑爆既费 token又降低准确率。工具层则是 Agent 能“动手”的关键。没有工具模型只能输出文字所有回答都停留在“建议”层面有了工具模型才能查数据库、发 HTTP 请求、读写文件、操作外部系统。工具层要处理的核心工程问题有三个工具描述是否足够清晰输入参数 schema 是否完备以及调用失败时错误信息能否被模型正确理解。这三个问题我会在决策点四里详细展开。1.3 行动与反馈闭环是 Agent 与普通提示词工程的分水岭行动层负责把模型决策变成真实可执行的动作比如发起一次 API 调用、执行一段代码。这里很多人会忽略“结果怎么送回模型”这个细节工具返回的数据、报错信息、超时状态都要以结构化方式写回上下文模型才可能在下一步做出正确判断。反馈机制则利用这些结果修正后续的决策方向。一个闭环的 Agent每一步都发生在“行动 - 观察 - 决策”的循环里直到完成目标或者触发终止条件。这也是 Agent 和普通提示词工程最本质的区别普通提示词是“一次性输出”Agent 是“多轮自我纠错”。没有反馈闭环你做的其实只是一个“会调工具的聊天机器人”不算是工程意义上的 Agent。1.4 运行环境Agent 能碰到哪一层决定了它能造成多大影响运行环境是 Agent 运行时的权限边界——它能读哪些数据、调用哪些服务、操作哪些系统。做 Demo 时放开权限没有感觉上了生产环境权限不收敛一定会出问题。我见过一个内部 Agent 因为工具权限过宽在一次测试中误删了测试环境的一批数据直接引发事故。工程上务必做到最小权限能只读就只读能隔离就隔离能加审计就加审计。别等到出了问题再回来补权限那时候代价往往已经付过了。2. 决策点一模型选型——先别盯榜单先看 Agent 的“稳定调用”能力很多人选模型时最爱比较“哪家排行榜分数高”但对 Agent 工程来说最关键的指标不是通用推理分数而是函数调用function calling的稳定性和指令遵循率。模型能不能稳定输出“该调用哪个工具、参数是什么”的结构化结果直接决定 Agent 能不能跑下去。2.1 为什么函数调用稳定性比分数更重要一个 Agent 任务里模型几乎每一轮都要输出结构化动作。只要模型经常输出格式错误、参数缺漏、或者幻觉出不存在的工具名再强的推理能力也发挥不出来。我在对比实测中发现相同任务在不同模型上的成功率差异可以非常大特别是工具数量超过十个时有些模型会开始频繁选错工具。所以我的选型习惯是先建一个“Agent 专项测试集”专门考察多工具场景下的正确调用率、参数准确性、错误恢复能力而不是靠几个问答样本来拍板。2.2 上下文长度是加分项不是必选项现在聊天模型普遍宣传 200K 上下文不少团队因此觉得买了大上下文模型记忆问题就解决了。这是典型的错觉。上下文窗口再大塞满之后照样影响延迟和效果而且 Agent 每轮带着状态走几十轮就把窗口打满。与其为超大上下文付出高昂成本不如在记忆层、上下文压缩上做工程处理具体方案我在决策点五里讲。选型时更应该看“有效注意力范围内的准确度”而不是“能装多少 token”这个数字。2.3 成本与并发不要只算单步单价要算单任务总成本Agent 跟普通聊天的成本模型完全不同。一次问答可能花一两万 token一个复杂 Agent 任务可能循环几十步每一步都把累积的上下文送到模型里单任务总 token 会非常可观。所以选型时不能只看模型单价还要估“平均步数 x 平均每步 token”这两个变量。我在一个项目里做过真实测算用某家大参数模型做 Agent单个任务总成本比中等参数模型高出五倍成功率只提升了六个百分点。后来我们微调了架构用中等模型加更精细的工具描述把成功率和体验拉回同一水平成本还降了一半。这个案例说明模型选型很少是“选最好的”而是“在成本、稳定性、上下文策略之间做权衡”。3. 决策点二规划策略——ReAct 还是 Plan-and-Execute本质是“探索”与“流程”的取舍第二个无论如何都要正面回答的决策是 Agent 怎么组织自己的行动步骤每一步“想一下再做一下”ReAct还是“先整体规划再逐步执行”Plan-and-Execute。这两个模式看着只是顺序不同实际跑起来体验天差地别。3.1 两种模式各自的长处和短板ReAct 模式让模型先思考当前状态做出一个动作观察结果再思考下一步。它的最大优势是灵活特别适合你不知道确切步骤、必须边做边摸索的探索型任务。缺点是步数越多token 消耗越大而且模型在中后期容易逐渐偏离最初的任务目标——这是长任务中最常见的失控方式。Plan-and-Execute 模式让模型先把整个任务拆成一份步骤计划再按计划逐一执行。它的优势是整体感强任务目标一直摆在那里不容易跑偏适合步骤相对明确的业务场景。缺点也很明显如果第一步计划就错了后面会全盘照着错误方向走所以必须额外设计“计划修正”机制在发现某一步不符合预期时重新规划。3.2 实际项目里怎么选混合路线最稳我的经验是优先考虑 Plan-and-Execute 的变体而不是让 Agent 完全自由地 ReAct。理由很简单真实业务中你通常对任务有相当程度的了解可以做一个初步规划即使模型计划得不够好也能通过“每步执行后对照计划”来纠正。纯 ReAct 在长时间任务中的失控率明显更高。更稳的折中方案是混合首轮让模型产出初步计划之后每个执行步让模型生成“当前状态 下一步动作 这一步对整体计划的影响”。这样既保留了规划的锚点又保留了执行时的灵活性。我在生产环境里推荐的就是这个形态它比单纯 ReAct 少了很多“跑着跑着忘了目标”的情况。3.3 终止条件和失败重试必须提前写死在工程里选好规划模式之后还要给 Agent 定死终止条件目标达成、达到最大步数、或模型判定失败三者必须至少有一个生效。否则 Agent 会无限循环费用跟着失控。我在生产环境里看到过太多因为重试策略不明确导致的死循环模型连续十次调用同一个失败工具照样不放弃。同时要设计失败重试的决策链工具调用出错时是重试、换一个工具、还是上报失败这个判断不能完全交给模型自由发挥应该在工程层预设好规则比如“固定工具连续失败两次以上进入人工兜底流程”。没有这层防护Agent 的稳定性永远建立在对模型自律性的幻想上。4. 决策点三记忆架构——“什么都往向量库里塞”其实是最贵的偷懒记忆系统在 Agent 工程里被高估的同时也被低估。高估的是大家相信“加个向量数据库Agent 就有记忆了”低估的是真正做好记忆牵涉到的工程细节远比想象中多。如果所有历史都无脑往向量库里塞你会很快发现检索回来的内容经常不是最关键的而是最相似的模型反而更糊涂。4.1 记忆分层的工程设计我建议按职能把记忆拆成三层。第一层是工作记忆负责当前任务上下文保留最近几轮的对话和工具结果用完后做压缩第二层是情景记忆负责跨会话的用户偏好、关键决策、历史任务摘要可以用结构化存储加向量检索第三层是语义知识负责领域知识库内容通常预先构建与单个用户历史关系不大。三层各自对存储方案的要求完全不同。工作记忆留在上下文里由 token 管理控制情景记忆比较适合向量库但没有必要每轮都查语义知识只在当前任务明确涉及某个领域时按需检索。很多人做出来的 Agent 变慢往往不是模型慢而是每轮都去向量库捞一大批无关片段把上下文塞满模型判断力自然下降。4.2 写长期记忆的门槛要设高一点最容易犯的错误就是“全量写入”——把每一轮工具输出、每一段用户对话都往向量库里写。这样做短期内看着“记录得很全”用一周之后检索质量就会急剧下降因为相似的片段实在太多了召回的正确率越来越差。真正值得写入长期记忆的是那些“对后续任务有确定性价值”的信息用户明确表达的偏好、用户纠正过的错误认知、任务最终结果、关键业务实体。我建议每次写入前先用模型做一个判断——“这条信息如果未来被检索到会不会帮助 Agent 做更好的决策”有价值才写入。这个“记忆整理”步骤会多花一次模型调用但换来的是长期记忆系统的可用性这笔账非常划算。4.3 记忆的时效性过期记忆比没有记忆更糟糕实战里我还发现记忆的“过期策略”是必须明确设计的点。用户偏好会变、历史订单会更新、地址会改动如果旧信息一直占据检索权重Agent 就会被过期记忆误导。简单可行的做法是给每条记忆增加时间戳和置信度字段检索时做加权排序超过有效期的降权或者直接清理。这一层在 Agent 上线初期看不到明显作用但运行时间越长它的价值越突出。我见过好几个项目上线一个月后效果明显下滑排查下来都不是模型退化了而是长期记忆里积累了太多过期且互相冲突的信息把决策信号搅浑了。早点把过期策略做进去后面省的是整夜的排查时间。5. 决策点四工具接口设计——模型没法跟你“心有灵犀”所以工具描述就是契约工具层是 Agent“动手”的通道但很多人把它理解为“注册几个 Python 函数”就完事了。真正的工程化是把工具设计成一份模型和系统都能理解的接口契约。你的工具描述写得好不好直接决定模型选对工具的概率你的返回值规不规范直接决定模型能不能理解执行结果。5.1 工具描述写“什么时候用”别只写“能做什么”在函数描述里光写“查询订单”远远不够。模型做决策时需要区分的是“该查订单还是该查库存”所以描述必须包含使用场景。比如查询订单——当用户询问订单状态、物流信息、售后进度时使用查询库存——当用户询问商品是否有货、库存数量、补货时间时使用。加上这类场景说明工具选择准确率能在不更换模型的前提下获得明显提升。这是我每次搭新 Agent 都优先做的低成本优化。5.2 工具粒度太粗会失控太细会噎住工具粒度是另一个关键决策。如果把“整站下单流程”做成一个工具模型无法控制中间步骤出错了也很难定位可如果拆得过细十几个参数让模型一次性填对填错率反而上升。实践下来比较稳的做法是中等粒度加参数收敛一个工具只完成一个有明确输入输出的子任务参数尽量控制在五个以内能做枚举就别用自由文本能设计默认值就别让模型必须填。整体上参数越是收敛模型调用工具的出错率越低。工具数量多了之后还会遇到一个问题功能相近的工具会让模型产生选择困难。这时候要在描述里明确写清楚差异点甚至可以直接写“本工具与 XX 工具的区别在于……”把容易混淆的边界直接点破。这种描述层面的“排错”比换模型便宜得多。5.3 返回结构和错误处理必须形成契约工具返回给模型的格式建议统一成 JSON 结构明确区分成功状态、业务数据、错误信息。一个血泪教训是错误信息写得含糊比如只返回“调用失败”模型经常理解成“工具成功了但没有结果”然后在没有任何实质进展的情况下反复重试同一个工具。所以每条错误信息里都要尽量带上“失败原因 下一步建议”。前端数据异常返回失败代码网络超时返回超时标记权限不足返回权限错误并明确告诉模型“不要重试”。这些约定都是 Agent 稳定性的隐形支柱越早定下来越好。6. 决策点五上下文与状态管理——Token 预算是 Agent 的命脉做过 Agent 的人都会承认上下文窗口是目前最稀缺的资源。模型调用费用、延迟、最终效果全都和上下文内容直接相关。如果不加控制一个多步任务会随着历史消息越堆越长先是变慢然后是变笨最后直接跑不动。6.1 三种上下文裁剪策略以及我习惯的组合常见的裁剪手段有三种。第一种是直接截断最旧的消息实现最简单但会丢掉早期关键决策第二种是滚动总结每 N 轮历史就调用模型生成一段摘要用摘要替换旧轮次适合对话型 Agent第三种是关键信息抽取把当前状态、用户约束、已完成步骤提取成一个结构化“状态块”放在每轮上下文最前面。我的实践是把三种策略组合起来每轮开始前对当前上下文做一次“总结 状态块”压缩用摘要替换掉中间轮的原始消息只保留最近三五轮原始消息供模型精细决策。这样既能控制 token 总量又不丢失任务关键信息。实测下来Agent 在长任务里的稳定性和成本控制都有明显改善。6.2 系统提示词也要做 Token 瘦身系统提示词是每轮调用都要计入的固定开销。很多人喜欢往里面塞大量公司资料、背景说明、规则手册动辄两三千 token。问题在于这些内容不是每轮都重要反而会摊薄模型对当前步骤的注意力。工程做法是“分层注入”把真正时刻需要的核心规则放进系统提示词按需使用的知识放到知识库在相关步骤触发时再检索注入。我做过一次很直观的优化把系统提示词从 2800 token 压到 600 token模型工具选择的准确率反而提升了 7 个百分点。内容少了模型注意力更聚焦效果自然上来了。6.3 状态持久化Agent 会话比 HTTP 请求活得久得多Agent 任务动辄持续几十分钟甚至几小时中途进程挂了怎么办会话状态必须做持久化。正确的做法是每轮循环结束后把当前任务计划、已完成步骤、状态块、决策历史全部写入存储。这样进程重启后Agent 能恢复到最近的决策点继续执行而不是从头再来。这里要特别区分两个概念上下文是给模型看的“当前信号”状态库是给程序用的“执行快照”。两者各管各的不要图省事把所有状态都塞进对话历史里。一旦混在一起你既没法做精准的 token 压缩也没法在重启后准确恢复。这个是很多自研 Agent 框架设计时的通病。7. 决策点六单 Agent 还是多 Agent——单体没做稳之前别急着让人开会多 Agent 是这两年的热门话题很多人一上来就规划“三个 Agent 协作完成任务”的架构。但工程上我必须先说一句逆耳的话绝大多数业务场景单 Agent 加工具已经够用。多 Agent 引入的沟通开销、上下文分裂、调试复杂度都是成倍增长的。它不是一个免费升级而是一笔需要算清楚的投资。7.1 什么情况才真正需要多 Agent我的判断标准很直白单 Agent 的上下文已经不可控或者任务需要多个专业角色并行处理时才考虑多 Agent。典型场景包括一个 Agent 负责理解用户意图另一个 Agent 负责数据操作还有一个负责审核输出三者职责互不重叠。注意职责必须“不重叠”否则大家都会抢着做同一件事结果互相矛盾。如果只是任务步骤复杂优先靠规划、记忆、工具设计去解决而不是拆分角色。多 Agent 最常见的失败形态是几个 Agent 各干各的没有一个统一目标最后产出互相冲突的内容效果比单 Agent 还差。分布式系统的复杂度不会因为加了层模型就消失。7.2 协作模式主从编排比议会讨论更可控多 Agent 的协作模式有很多种我建议从最简单的主从模式开始一个编排 Agent 负责拆解任务、分派子任务、汇总结果若干个执行 Agent 只负责执行分配下去的子任务。这种模式的调试性最好因为你总能定位到“是编排者决策错了还是某个执行者执行错了”。议会讨论模式看起来很美——多个 Agent 自由讨论、投票决定方案——但在生产环境里稳定性很差。投票过程消耗大量 token模型之间又容易相互说服最后得到的常常不是更理性的结论而是更强词夺理的结论。不是不能做但它更适合用于研究性项目不适合默认业务链路。7.3 多 Agent 之间的上下文隔离比任何框架都重要多 Agent 之间必然要传递信息但工程上不要把所有内容都塞进一个共享上下文。应该只传递“任务描述 必要数据 约束条件”。每个执行 Agent 都有自己的独立上下文避免执行过程中的中间噪音污染其他 Agent。需要共享的状态应该写入一个统一状态中心各 Agent 按需读取。其实这又回到了记忆架构的设计Agent 与 Agent 之间的通信本质上就是记忆系统的一次接口调用而不是“让所有 Agent 围观同一份聊天记录”。顺着这个思路设计多 Agent 系统会清爽很多。8. 决策点七可观测性与评测——没有 Trace 的 Agent 不值得上线普通后端接口出了问题你靠日志和报错堆栈就能定位。Agent 不一样它是非确定性的多步系统每轮都在决策和行动无法用普通接口测试保证可用。没有可观测性Agent 出错时你只能对着模型的原始输出猜那效率低得可怕。这也是 Agent 工程和普通后端工程最大的不同必须提前设计“看得到模型每一步在想什么、做了什么”的观测体系。8.1 可观测性的三个层次日志、Trace、评估最基础的是日志每个节点的输入、输出、工具调用结果、token 数、耗时都记录下来。再往上一层是 Trace把一次 Agent 任务的完整决策链串起来用户问了什么、模型想了什么、调了哪个工具、拿到了什么结果、下一步怎么决策。光有日志没有 Trace你仍然很难把碎片拼成完整画面。第三层是评估准备一组标准任务定期跑回归看成功率、平均步数、平均成本、延误率这些指标的变化。三个层次缺一个你优化 Agent 就只能靠感觉。尤其到了后期调 Prompt、调工具描述时没有评估体系你根本说不清这次改动到底是让系统变好了还是变差了。8.2 评测集要提前建失败用例要持续沉淀很多团队把评估放在 Agent 开发完成后这是顺序搞错了。正确做法是先建评测集再开发功能。比如做一个客服 Agent先准备五十个能代表真实用户分布的典型问题标注好期望的工具调用路径和期望的最终回答每次修改后跑一遍全部用例哪条失败就说明哪次改动引入了回归。评测集还应该是活的。每次真实环境里 Agent 表现不佳的案例都值得整理进评测集里长期维护成一个“失败用例库”。这大概是最笨但也最有效的 Agent 质量提升方式——每解决一个失败用例系统就真实地变好了一点而不是靠感觉调参。8.3 上线的灰度与兜底比模型切换更重要上线时不要全量切流量一定要灰度。要给 Agent 配置“人工兜底”的通道Agent 处理不了时能顺利转人工或走默认流程。很多自研 Agent 项目翻车不是因为模型选得不好而是上线前只测了 Happy Path一遇到边界情况就崩还没有兜底预案。Agent 的稳定性永远不能靠模型自觉只能靠工程上的失败降级和人工介入预案。你可以先让 Agent 只处理它最有把握的任务类型其他全部转人工等成功率稳定上来了再逐步扩大边界。这个渐进过程才是 Agent 上生产环境的正确姿势。这套“七要素 七个决策点”的框架我自己用了很多遍之后最大的体会是Agent 从来不是“搭出来”的而是“调出来”的。每个决策点都没有标准答案并且它们互相牵制——选了便宜的模型可能就得在工具描述上多花功夫选了 Plan-and-Execute就得同步设计计划修正机制选了多 Agent就要接受调试成本的上升。你不可能在方案评审阶段一次性全想对但只要清楚每个决策点背后的权衡迭代起来就有明确方向。最后分享一个我一直在用的小技巧每次只优化一个决策点然后用同一套评测集跑三遍盯住成功率、平均步数、平均成本三个指标。如果一次改动让成功率上升但成本暴涨或者成本降了但成功率明显下滑那就说明这个改动不划算需要继续找平衡点。按这个节奏迭代几个月你会明显看到 Agent 越来越稳定而且每一分改进究竟花在了哪里心里都有数。