最开始接触 AI Agent，是给团队做一个自动整理工单分拣的工具。当时我天真地以为，Agent 就是把大模型接到几个 API 上，给一段提示词，它就能自己干活了。第一次跑通的时候确实很兴奋——它真的会调工具，会按照指令把工单归类，还知道在拿不准的时候问我一句。这种"智能感"很容易让人上头。
但真正往生产环境推的时候，麻烦全来了。同样的提示词换个场景就失灵，工具参数偶尔传错，上下文越填越长然后开始胡说，最离谱的是有一次它在一个简单的查询任务里循环了二十几次，直到把预算跑穿才被熔断拦下来。那一刻我意识到，Agent 看起来是魔法，拆开之后全是工程。它不是"接一个大模型就行"，而是一套由若干个部件、若干个选择共同决定成败的系统。
这篇文章我不会从头讲什么是大模型，也不会列一堆框架的 API 文档。我把它拆成两组东西：第一组叫"七要素"，是任何一个 Agent 系统都绕不开的零件清单；第二组叫"七个决策点"，是你在工程实现时必然要做的七个关键取舍。把这两组东西理清楚，你就能看懂市面上的主流 Agent 架构到底在解决什么问题，也能自己动手搭一个不容易翻车的 Agent。
1. 为什么我要用"两个七"来拆解 Agent
先说清楚一个背景。我见过太多人讨论 Agent 的时候，是把"模型""工具""记忆"这些词混在一起说的。模型强不强、工具多不多、记忆有没有，好像每一项都能单独决定 Agent 的好坏。这是最典型的误区。
Agent 的本质是什么？其实不复杂。你给它一个目标，它自己决定要做什么，自己调用外部工具，然后根据结果调整行动，直到目标完成或者它判定目标无法完成。就这么一个循环。但在这个循环里，有一大堆静态的东西——比如模型、工具、记忆、提示词——它们是 Agent 的"零件"；还有一大堆动态的东西——比如用什么策略规划、什么时候重试、怎么防止死循环——它们是开发者在构建过程中做的"决策"。
我把这两件事分开的原因很简单：**零件是你可以直接看得到的，决策是你必须自己拍板的。**零件选错了，顶多效果差一点；决策选错了，Agent 直接不可用。
比如很多团队第一版 Agent 用的都是现成框架，零件齐全：模型有，工具函数接了一大堆，还加了向量库当记忆。看起来什么都有，结果跑起来一塌糊涂。问题出在哪？出在决策上：模型选太大了还是太小了？工具函数拆得太细导致模型老选错？上下文一长就开始丢信息？重试逻辑没有上限导致死循环？这些都不是"再买一个零件"能解决的，是你在每个分叉口怎么选的问题。
所以这篇文章的结构也定了：先用七要素把 Agent 的构成彻底拆一遍，看看哪些东西是决定能力上限的、哪些是决定稳定性的；再用七个决策点带着你走一遍工程实现里的关键取舍。最后用一个完整的案例，让这两组东西在同一个项目里碰一次头。
这个框架适合谁？适合正准备做 Agent 的开发者，也适合已经做完 Demo、但在往生产环境推的过程中被各种稳定性问题折磨的人。如果你是团队的技术负责人，想弄清主流架构里那些眼花缭乱的概念到底哪个值得投入精力，这七个决策点也能给你一张很实用的清单。
2. 第一组核心：七要素拆解，Agent 的"零件清单"
2.1 模型：一切能力的天花板，但只是起点
模型是 Agent 的大脑，这一点没人会反对。但我想强调的其实是另一个点：模型决定了 Agent 能力的上限，而工程决定了你的 Agent 到底能逼近这个上限多少。
选模型的时候，除了看它的通用能力，一定要重点看三件事：指令遵循能力、工具调用（Tool Calling）的准确率、上下文窗口的利用效率。我在实践中发现，两个模型可能跑通用对话任务时分数差不多，但放进 Agent 里，一个工具调用错误率不到 2%，另一个能到 15%。这个差距在单次对话里感知不强，在 Agent 的多轮循环里会被迅速放大——因为一个错误调用会引发一连串的修复尝试，消耗大量 token，最后还未必修得对。
我见过一个非常典型的例子。同样是让 Agent 查天气并提醒用户带伞，一个模型能老实地把城市参数传进查天气工具；另一个模型把"城市"解析完还自己补了一个"日期"参数，而那个工具根本没有这个参数。单看这个错误很小，但如果你有 30 个工具，每个工具的参数都很复杂，这种错误就会高频出现。所以在项目早期，不要只盯着模型的通用排行榜，拿你自己的工具列表做一个只有 50 条用例的工具调用评测，比什么都有说服力。
还要多说一句：别盲目追求大参数模型。小模型便宜、快、延迟低，如果你的任务模式相对固定、工具数量不多，很多场景下中小模型配一个精心设计的提示词，效果完全不输大模型，成本却差了一个数量级。后面第七个决策点里，我会专门聊怎么在项目里做这个选型。
2.2 工具：Agent 的手脚，也是它闯祸的来源
没有工具的 Agent 只是一个高级聊天框。工具层干的事情很直接：把外部能力封装成模型可以调用的函数接口，比如查数据库、调 API、发消息、操作文件、执行代码等等。
工具设计是整篇内容里我最想强调的部分，因为它是 Agent 系统里工程含量最高、也最容易埋雷的地方。市面上的主流架构都把工具定义成一组 JSON Schema：函数名、描述、参数类型、必填项。听起来很简单，但你一写就会发现，工具的边界和粒度直接决定模型调用它的成功率。
我自己的经验法则："工具描述写在给机器看，不是给人看。"每个工具的描述里要写清楚什么时候该用它、什么时候不该用它、参数格式是什么。不要小看这句话。我见过不少人写的描述是"查询用户信息"，结果模型在完全不该查用户的场景里也去调了它。如果你把描述改成"仅当需要获取用户的姓名、手机号或会员等级时使用，登录场景不要调用，用户画像展示不要调用"，错误率立刻降一截。
工具数量的控制也很重要。一个 Agent 接 10 个以内工具的时候，模型选错工具的概率很低；一上 40 个，选错的概率指数级上升。这时候不是简单的加描述能解决的，更多要考虑归类合并，或者上一级路由工具。这就是后面决策点里要细说的问题。
2.3 记忆：短期上下文是工作台，长期记忆是档案柜
很多讲 Agent 的文章会把记忆讲得很玄，什么"长期记忆""记忆增强生成"满天飞。实际工程里，记忆只分成两种，管理思路完全不同。
短期记忆就是当前对话的上下文窗口。模型所有推理都在这个窗口上进行，它就像一个工作台——台面就这么大，摆满了东西，新东西就放不下了。你处理短任务还好，一旦 Agent 需要连续做几十步操作，这个工作台很快就会满。满了之后怎么办？这是决策点五要聊的上下文管理问题，但你要先有这个意识：上下文不是免费的。
长期记忆则是存放在模型外部的东西，常见的有三种形式：向量库存语义记忆、KV 存储存精确记录、摘要文本存压缩后的历史信息。短期记忆和长期记忆不是替代关系，是互补的。在实际项目里，我会把最关键的几轮对话摘要后写进长期记忆，在需要时再拉回上下文。这比你一上来就上向量库要实在——因为很多场景下，你的记忆需求根本不需要语义检索，一个精确查询就能搞定。上了向量库反而引入一堆"明明该精确命中的数据，却因为向量相似度排序被排到了后面"的新问题。
2.4 提示词策略：同一个模型，两个 Agent 的表现可能完全不一样
提示词是 AI Agent 里最被低估的要素，因为框架文档从来不强调它，但实际效果差异巨大。我自己做过实验：用同一个模型、同一组工具、同一个任务，只改系统提示词的结构，成功率从 50% 能拉到 85%。
好的 Agent 提示词一般包含这几块：角色与目标定义、行为边界（能做什么不能做什么）、决策流程指引、输出格式要求、兜底策略。这五个部分里，最容易写漏的是"兜底策略"。大部分人会写"你要做什么"，但没人写"如果你拿不准怎么办"。我在给每一个 Agent 写提示词的时候，都会强制加一句：当你不确定用户意图时，必须向用户澄清，不要猜。这句看似简单的话，能把幻觉率降下去一大截。
另外想提醒一点：Agent 提示词和普通对话提示词不一样，它要的是"确定性"而不是"创造性"。同一个工具调用场景，你给模型的选择空间越大，它发挥越离谱。尤其是给几个工具选项时，描述越具体，选择越精准。这就像你带一个新员工入职，你给的操作手册越模糊，他上手出错的概率越大。
2.5 规划与循环：Chain 是直线，Agent 是有分叉的树
规划是 Agent 区别于普通 LLM 应用最核心的部分。普通 LLM 应用是一条直线：输入进，输出出，完事。Agent 是一个循环：思考 → 行动 → 观察结果 → 再思考。这个循环里有分叉、有回退、有纠偏。
工程实现上，目前主流架构基本可以分成三类链式、树式和图式。
链式最简单：每一步都有明确先后，模型不需要做复杂决策，适合任务流程固定的场景。
树式稍微复杂：模型在关键节点要做判断，选择不同的分支继续走。大部分 ReAct 风格的 Agent 本质就是隐形的树——每次工具调用结果都可能改变下一步的方向。
图式最灵活但最复杂：节点之间可以有环、有条件跳转、有并行，像 LangGraph 这类框架就是干这个的。图式最适合复杂工作流，但代价是调试难度成倍上升，你需要在开发环境里看状态流转才能看懂一个问题出在哪。
我建议一开始别急着上最复杂的方案。先画一下你的任务流程图：如果流程里分支很少，链式就够；如果分支中等，树式加一个规划器就够；只有真正需要场景切换、并行、条件循环的时候，再上图式。决策点二里我会细说 ReAct 和 Plan-and-Execute 到底怎么选。
2.6 安全边界：杀不死的循环，正在吃掉你的预算
很多人把 Agent 的要素列成五个：模型、工具、记忆、提示词、规划。我会坚持再加一个：**终止条件与安全边界。**这是我在生产环境里摔过跟头才加上的。
Agent 的核心是一个自循环，没有终止条件，它理论上可以一直执行下去。你以为模型会自己判断"任务完成了，停下吧"？大部分场景下它确实会，但只要有一次它判断失误，就会陷入一个恐怖的死循环：调用工具、发现结果不对、换个参数再调用、结果还是不对、再换参数……每次循环都在消耗 token，账单上的数字嗖嗖往上涨。
所以我在生产系统里设置的终止条件从来不是单一依赖模型自觉，而是三管齐下：最大迭代次数硬限制、连续多次结果一致就提前停止的"防抖"逻辑、以及异常路径上的熔断开关。这三件事加在一起，才能保证一个 Agent 最起码是"可控的"。没有这个要素，其他六个做得再好，你也不敢把它扔到生产环境里睡觉的时候还在跑。
3. 第二组核心：七个决策点，工程实现的分叉路口
如果说七要素是"这个 Agent 由什么组成"，那七个决策点就是"你在构建它的时候必须做的七个关键选择"。这七个选择每一个都没有绝对正确的答案，只有"在什么场景下什么选择更合理"。下面逐个过。
3.1 决策一：模型选型，是买最大的还是够用就行？
这是第一个分叉口，也是很多人最容易跟风的决策点。一个大参数的旗舰模型确实聪明，工具调用准，指令理解强，但它的成本、延迟也是跟着往上走的。如果你的 Agent 每一步都要调用一次大模型，而任务本身又不算复杂，这种成本会被放大得极其离谱。
我自己踩坑的经验是：**先用大模型验证逻辑，再用小模型压成本。**第一版先求稳，用能力最强的模型把整个链路跑通，确认 Agent 的设计没问题。然后拿一个验证集，把模型换小一号，对比工具调用成功率和任务完成率。如果差距不大，就换小的；如果明显变差，就再换回去或者考虑混合方案——大模型做规划，小模型做执行。
还有一个很多人忽略的点：真正重要的是 tool calling 准确率，不是纯文本能力。两个模型跑公文写作看不出差别，一到解析工具返回的 JSON 结构时，一个稳如老狗，一个天天给你多返回一个多余字段。这种评测不做，光看跑分选模型，迟早吃亏。
3.2 决策二：循环架构，选 ReAct 实时反馈还是 Plan-and-Execute 先规划？
这是当前主流架构里争论最多的一对。ReAct 的逻辑就四个字：边想边做。模型每一步都观察结果，再决定下一步。优点是灵活，任务中途情况变了也能马上调整方向。缺点也很明显：不可控。你永远不知道它到底要几步，token 消耗波动极大，而且一旦中间结果有噪声，它可能被带偏。
Plan-and-Execute 的逻辑完全不同：先让模型根据目标写出一个完整的执行计划，列出每一步要做什么，然后按步骤执行，每步只做机械的事，不重新做高级决策。优点是可控性好，计划定完之后执行路径基本确定，适合预算预估和进度管理。缺点是一旦现实结果和计划假设不符，它不会灵活调整。
我的建议是分级处理：如果任务是"流程固定 + 工具反馈直接"，比如定时抓数据、生成报表、发送通知，优先选 Plan-and-Execute；如果任务是"探索性 + 反馈多变"，比如客服问答、竞品调研、代码修复，用 ReAct。还有一个被低估的混合方案：先让模型写一个粗粒度计划，然后每个计划步骤内部用 ReAct 微调。这个方案在复杂任务里表现非常稳定，代价是工程实现复杂度略高，但对场景跨度大的系统值得。
3.3 决策三：工具粒度，一个函数包揽一切还是拆得越细越好？
工具粒度是我在代码评审时最常提的问题。很多人的直觉是：把工具拆得细，模型选择更精准。这个直觉方向是对的，但存在一个明显的反噬：工具越细，数量越多，模型的选择空间越大，选错的概率反而上升。
你去看那些主流框架的 Demo，通常只接了三四个工具，每个功能都不小，所以模型几乎不会选错。但真实业务里，你可能需要接十几个、几十个业务系统的接口。这时候怎么办？
结合我自己做过的项目，我的推荐是粗细结合。把最核心的高频动作拆成细粒度工具，让模型能精确控制；把低频的、完整的业务场景封装成粗粒度工具，减少模型做组合决策的负担。比如"给用户发验证码"是一个工具，"完成用户注册"是另一个工具——前者细，后者粗，调用路径非常清楚。
另外，工具参数的设计也要考虑模型的解析能力。参数太多、嵌套太深，模型很容易传错。我在设计工具时有个原则：能平铺就不要嵌套，能少必填参数就少必填。一个工具如果必有参数超过五个，考虑一下是不是拆成两个更合理。
3.4 决策四：记忆方案，向量库、关系库还是直接塞上下文？
记忆方案的决策通常犯两个极端错误：一是啥都往上下文塞，上下文一多就乱；二是啥都往向量库里塞，最后查出来一堆不相关的内容，还美其名曰"长期记忆"。
我的分类方式是：先区分这个记忆"要被精确查询还是要被模糊回忆"。用户订单、配置信息、操作记录这些，需要的是精确查询——用关系库或者 KV 存储，按 ID 或时间查出来，直接拼进上下文。向量库适合的是"语义匹配"：比如"用户之前有没有提过对咖啡因过敏""类似的历史工单是怎么解决的"这种模糊查询。用错向量库是很多团队最常见的工程失误，不是向量库不行，是问题类型不匹配。
实际操作上，我习惯把记忆拆成三层：第一层是当前上下文，直接可见；第二层是会话摘要，每几轮对话就生成一次摘要，顶掉早期细节；第三层是长期档案，挑有价值的沉淀进存储，按需检索。三层配合，既控制 token 成本，又保证关键信息不丢。跑过几个项目之后你会发现，能做到这点的 Agent 已经很不容易了。
3.5 决策五：上下文压力，当工作台被塞满时该怎么办？
上下文窗口是 Agent 系统里最现实的压力源。一个执行了 20 步的 Agent，每一步的思考和工具返回都堆在上下文里，可能到第 15 步时上下文就快满了，模型开始忘记最初的用户目标，行为变得不可预测。
这个问题的工程解法我归纳成三种策略。第一种是裁剪：保留最早的系统提示词和用户目标，把中间过程压缩成摘要，只保留最近几步的完整内容。第二种是压缩：每几轮工具调用后，用模型把前面这轮对话的核心信息和结论提炼成一段话，覆盖掉原始内容。第三种是外置：关键信息写入外部存储，需要时再精确检索回来。
这三招里，最容易实现的是裁剪，因为它的逻辑就是截断，但最容易出问题——一旦你把不该裁的内容裁掉了，后续决策就失去了依据。所以我的建议是至少做两层：系统提示词和用户核心目标永不裁剪，其余中间过程按 token 预算滚动挤压。
每次在项目里看到 pinned 消息、long-context 使用报告这类工具，我都会提醒团队：上下文管理不是模型能力问题，是架构问题。模型上下文窗口再大，也只是推迟了你必须面对这个问题的时刻。
3.6 决策六：终止机制，让模型自己喊停还是硬性规定步数？
前文说过终止条件是 Agent 的第七要素，但"具体怎么做终止"本身是个独立的决策。我们团队的默认配置是这样：最大迭代次数 + 连续判定机制 + 业务兜底。
最大迭代次数好理解，就是硬上限。我的经验值一般设在 10-15 步之间。太少了复杂任务做不完；太多了成本不可控。连续判定机制则是防止"假完成"：如果模型连续两到三次输出结果基本一致，没有变化，就认为它陷入重复，强制终止。业务兜底是最后一道防线：超时直接返回当前已获取的信息，不要空手去死等一个永远完不成的结果。
这里还有一个容易忽略的点：终止条件的触发信息一定要记录到日志里，区分"正常完成""超时终止""重复终止"三种状态。我见过太多团队只关心正常完成的路径，完全不看终止日志，导致 Agent 每周都在幕后偷偷烧掉几百上千块而不自知。
给团队做 Agent 代码评审时，我第一个问的问题永远是：它什么时候停下来？答不上来，别谈上线。
3.7 决策七：容错策略，失败之后你允许 Agent 做什么？
最后一个决策点，也是把 Demo 和生产力区分开的关键：**失败后的重试策略。**很多 Agent Demo 是一次成功的，所以你不会想到失败的情况有多糟。真实场景里，工具调用失败的频率远高于你的预期——第三方接口超时、参数格式错误、返回数据结构变化、权限过期，每个都是日常。
容错方案的第一个选择是"要不要重试"。我的判断标准是看失败类型：超时、限流这种临时性失败，可以重试，但要退避；参数错误、鉴权失败这种确定性失败，重试一万次都是同一个结果，赶紧返回错误让上层处理，别浪费预算。
容错方案的第二个选择是"重试到什么程度"。我常用的做法是给每种失败定义"备选路径"：主工具失败后，Agent 可以尝试备选工具；备选也失败，就降级让模型凭已有信息直接输出结果；再不行，就明确告诉用户"这件事当前做不到"。很多团队失败后只会让模型一遍遍自我重复，就是因为根本没有定义备选路径，模型只能靠撞运气。这是最贵的容错方式。
我在系统里做了一个简单的降级熔断状态机：区分健康、重试中、降级中、熔断四个状态。每个外部工具都带超时、重试次数和熔断阈值。这套机制看着繁琐，但一上线，Agent 的可用性立刻从"偶尔超神"变成"稳定合格"。
4. 一个走查案例：让"两个七"在同一个项目里碰头
光讲抽象概念很容易读过就忘，下面我拿一个真实做过的项目——"自动整理周报并发送到项目群"的 Agent——把七要素和七个决策点完整串一遍。这个 Agent 的任务很简单：每周五下午读取当前迭代的 Git 提交记录和任务状态，按模板生成周报，发到指定群。
先看七要素怎么落地：
模型：选了一个中等规格的模型，理由是任务模式非常固定，不需要顶级推理，工具调用准确率达标就行。工具：只接四个——读 Git 提交、读任务列表、生成周报文档、发送群消息。四个工具覆盖全部动作，粒度刚好匹配任务步骤。短期记忆：存当前迭代编号、用户填写的周报模板偏好。长期记忆：存历史周报的结构，用来感知用户偏好的变化，但这个项目里只需要最近三次的摘要，不用上向量库。提示词：明确规定了"当 Git 提交为空时，不要编造内容，应向用户确认"。规划：用 Plan-and-Execute，先让模型生成"读取 → 汇总 → 成文 → 发送"四步计划，再逐步执行。终止条件：最大迭代 5 步，正常完成就停，发送成功后立刻终止，不允许多余动作。
再看七个决策点怎么选：
决策一选型：用中等模型而不是旗舰模型，省了 80% 成本，任务完成率一样。决策二架构：选了 Plan-and-Execute，因为周报流程极其固定，不需要临场发散。决策三工具粒度：四个工具各管一段，不拆更细，让模型动作路径清晰。决策四记忆：核心信息用 KV 存，历史偏好用摘要文本，没上向量库——因为没有语义检索需求。决策五上下文：这个任务总步数很少，上下文压力小，只需在第一步完成后裁剪掉原始提交的细节，保留摘要。决策六终止：发送成功后从工具返回值里直接判定完成。决策七容错：Git 提交读取失败要重试两次但退避；发送失败不重试，直接返回"需要人工发送"——因为群消息发重了比没发更麻烦。
这个案例想表达一个事：你不需要在每一个决策上都选最潮、最复杂的方案。上向量库、上图结构、上大模型听起来很满，但真正的工程是往真实需求上收敛。这套项目跑下来稳定跑了好几个月，一次没翻车，秘诀就是每一步决策都在问同一个问题：这个复杂度，值不值？
5. 从 Demo 到生产，再分享几个必须提前做好的基建
把"两个七"梳理完，Agent 的主链路基本就清晰了。但你要是准备把它推到生产环境，有几个基建必须在第一版就做进去，不然后面补起来代价极大。
第一个是可观测性。Agent 的日志绝对不能只记录输入输出，必须把每一步的思考、工具调用、返回结果全部摊开记录。我习惯给每步打一个 trace_id，把"模型想干什么 → 调了哪个工具 → 传了什么参数 → 工具返回什么 → 下一步怎么决策"完整串起来。排查问题的时候，没有这套日志，你连模型为什么会走这么一条歪路都看不出来。
第二个是成本预警。Agent 的 token 消耗是脉冲式、非线性的，你的预算是按单次对话估的，但一个 Agent 可能在一个任务里跑十几轮循环，每轮都要调用模型。我在生产环境里同时设了三道防线：单次任务成本上限、单用户小时成本上限、日总成本上限。任意一道触发就熔断并告警。
第三个是回归测试集。Agent 项目改动起来非常容易"按下葫芦浮起瓢"——优化了一个场景，破坏了另一个场景。我会固定维护一份三五十条的任务集，按场景打标签，每次改提示词或工具定义后批量跑一遍，看完成率的变化。没有这套回归测试，你在生产环境里做任何改动都是开盲盒。
最后是一条最朴素、但最值钱的经验——Agent 的第一版，永远把一个复杂任务的人力成本降下来作为成功标准，不要迷恋"智能"。AI Agent 最大的价值是稳定、可靠地完成以前需要人盯着干的工作，而不是展示模型有多聪明。把七要素装好，把七个决策点想明白，你会发现工程化的 Agent 远没有想象中那么玄乎，但绝对比想象中更考验功力。
