做 AI Agent 工程最尴尬的时刻不是模型能力不够而是你发现 Demo 五分钟能跑通但真要把它变成一个能上线、能维护、敢交到用户手里的系统横在中间的全是选择题。过去一年我帮团队评审过不少 Agent 项目几乎无一例外都卡在同一个地方大家把 Agent 当成一个“会自己想的脚本”写起来很爽跑起来也很惊艳一接真实业务就崩。后来我把整个思考方式拆成两个框架先用“七要素”看清 Agent 内部由什么组成再用“七个决策点”理清工程实现时每一步到底在选什么。这篇就把这两个框架完整讲明白——你不需要先会 LangGraph 或 FastAPI只需要按这个思路走一遍就知道一个生产级 AI Agent 是怎么从概念落成代码的。适合正准备把 Agent 搬进业务系统的开发者也适合想给团队定技术方案但总觉得“网上教程太散”的架构师。1. 七要素先把 Agent 拆开看看一台“有手有脑”的机器怎么组成很多人描述 Agent 时喜欢说“大模型 工具 记忆”这话对但太粗了。真到了工程层面我发现一台能稳定干活的 Agent 至少要拆成七个部分缺一个后面上线就会拿命补。1.1 任务边界Agent 是瑞士军刀还是专用扳手先回答一个最土但最重要的问题这个 Agent 到底负责什么不负责什么。任务边界不是一句需求描述而是输入输出的严格契约——接受什么格式的消息产生什么类型的动作哪些话题必须拒绝哪些情况必须转人工。我见过最典型的失败案例是有人把“智能客服”做成了“啥都能聊的机器人”结果用户问天气它也答问股票它也答最后答错一句整个产品的可信度就崩了。反过来说真正能落地的 Agent 往往非常“偏科”它只做售后工单分类、只做日报生成、只做代码审查建议。边界越窄行为越可预测也越好评估。1.2 模型底座LLM 是发动机不是整辆车第二个要素是模型本身但要注意一个认知陷阱LLM 只是发动机Agent 是整车。发动机决定上限但方向盘、刹车、仪表盘决定能不能上路。很多人以为“换个更强的大模型Agent 问题就解决了”实际不是——你缺的往往是流程控制、状态管理、错误恢复这些“车身部件”。工程上选模型要看的不是排行榜而是三个硬指标推理能力够不够处理带约束的任务、是否支持稳定的工具调用Function Calling 或 Tool Schema、以及推理成本和延迟能不能被业务接受。同一个任务简单分类可能用小模型十几个毫秒就出结果复杂规划才需要大模型慢慢想这直接引出后面的“决策二”。1.3 记忆系统桌面干净的人才能干好活记忆是 Agent 被讨论最多、也最容易做错的要素。我习惯把记忆分成三层工作记忆当前任务上下文、长期记忆跨会话的历史信息、程序记忆Prompt、工具定义、规则配置这些“肌肉记忆”。这里有一个反直觉的点上下文窗口不是记忆。很多新人以为窗口越大越好于是把几十页历史全塞进去结果模型注意力被冲散回答质量反而下降token 成本还打不住。好的记忆设计是把上下文当桌面——只放当前这步需要的东西其他资料放文件柜向量库、Redis、数据库随用随取用完归档。1.4 工具调用手伸得太长就容易拿错东西工具是 Agent 的“手”和“脚”。一个客服 Agent 要能查订单、改地址、发起退款一个数据分析 Agent 要能查库、跑 Python、画图。但工具不是越多越好——模型每多一个工具可选选错工具的概率就高一分。工程上每个工具要定义清楚三件事名字动词 名词如query_order、参数 Schema严格 JSON别用自然语言描述参数、以及描述说明这个工具是干嘛的、什么时候该用、有没有副作用。这跟给人写工作手册一个道理写得越明白越少出岔子。1.5 规划机制先抠 GPS 还是走一步问一步规划机制决定 Agent 怎么从“用户说了一句话”走到“完成一个多步任务”。目前主流就两派一派是走一步看一步的 ReAct推理 行动交替循环适合开放探索型任务比如“帮我研究一下这个竞品”另一派是 Plan-and-Execute先定计划再执行适合目标清晰、步骤可拆的任务比如“对所有待处理工单做分类并生成报表”。生产环境里我见得最多的其实是第三种固定管线 局部决策也就是预先画好流程图每个节点内部让模型做选择题而不是让它自由发挥。原因后面讲决策五的时候细说总之你先记住规划机制越自由系统越不可控调试成本越高。1.6 执行状态能停、能续、能交给人的流程才敢上线脚本是一次性从第一行跑到最后一行而 Agent 是一个长时间、多步骤、随时可能出错的流程。执行状态要素想解决的是任务跑到一半比如第三步调外部 API 超时了系统能不能停下来、报个错、重试一次或者把控制权交给人类审核再继续。我实践中强烈建议用显式状态图来管理 Agent 流程LangGraph 就是这么干的而不是把流程逻辑写在自然语言 Prompt 里让模型“自觉遵守”。代码层面的状态机看得见、摸得着、能测试Prompt 里的“请按步骤执行”则完全无法保证。StateGraph节点之间怎么跳、什么条件下跳、跳不过去怎么办都要是显式的、可回放的条件分支。1.7 观测与评估没有尺子就没有优化最后一个要素最容易被忽略却是生产环境的生命线。LLM 的输出有概率性同一个输入换一次调用可能得到不同结果这意味着你无法用“这次跑通了”来证明系统是好的。必须有结构化的 Trace 日志、细粒度的评估集和护栏规则才能回答三个问题这次回答质量好不好、花多少钱、慢不慢。做不了观测评估的 Agent 就像不带仪表盘开车——你敢开上路但出了问题永远不知道是发动机、油门还是路况的责任。具体怎么做后面“决策七”展开。2. 从要素到决策工程实现就是一连串取舍2.1 Demo 与生产之间隔着七个选择把七要素记在脑子里之后再看“工程实现”这四个字就会觉得清晰很多工程实现不是一个动作而是一连串取舍。Demo 只需要把七要素搓成一条能跑通的路生产系统则要求在每一个岔路口都选对——因为上线之后你没法靠“重启一下”来修 Agent。我把这些岔路口总结成七个决策点每个决策点都对应前面的一个要素。它们不是按时间顺序逐个完成而是互相影响、成组出现。比如你选定了多 Agent 架构模型、工具、状态的设计全部要跟着变你选了长流程规划记忆策略就要重新考虑。2.2 七个要素对应的七个决策点总览先把整套对应关系放在一张表里后面逐个展开七要素对应决策点核心矛盾任务边界决策一单 Agent 还是多 Agent智能化上限 vs 可控性模型底座决策二一个模型还是大小模型配合效果质量 vs 成本延迟记忆系统决策三上下文放多少、仓库存什么信息完整 vs 噪音成本工具调用决策四开放多少工具、每个怎么定义能力强 vs 容易选错规划机制决策五固定流程还是自由推理确定性 vs 灵活性执行状态决策六状态建模与人工介入点自动化 vs 风险控制观测评估决策七上线标准与持续观测迭代速度 vs 系统稳定这张表是这套框架的核心。你拿着它去套任何 Agent 项目都能快速定位问题出在哪个环节——是边界没定清楚还是工具定义太含糊还是评估手段缺失。下面我把七个决策点分别拆开讲重点说每一条背后的代价。3. 前四个决策点边界、模型、记忆、工具3.1 决策一这个 Agent 管多宽单 Agent 还是多 Agent第一个决策也是整个系统的地基到底做一个什么边界的 Agent需不需要拆成多个 Agent。先说结论倾向能单 Agent 解决的就不要拆多 Agent。多 Agent 看似各司其职很“高级”实际上引入了三大麻烦一是通信成本Agent 之间用自然语言传递信息信息一定会失真二是调试难度出了问题你分不清是哪个 Agent 的锅三是资源开销每个 Agent 都要消费模型调用成本线性翻倍。单 Agent 的能力边界卡在哪里卡在单次任务复杂度。如果任务链路超过七八步或者需要同时维护多套上下文单 Agent 的上下文就会很挤。这时候我建议的拆法不是“按功能拆”而是“按责任拆”——比如一个负责理解分类一个负责执行操作中间通过结构化数据传消息而不是靠文字“你一句我一句”。实操里我一般先问三个问题这个任务能不能用一个固定流程描述清楚如果必须靠模型自由推理才能完成推理链路有多长最坏情况下需要同时记住几份相互独立的信息如果三个答案都偏向简单闭眼选单 Agent。3.2 决策二用什么模型要不要大模型小模型混着来第二个决策点最热闹也最容易踩坑。很多人一上来就选最强模型理由是“反正效果好”。但在生产环境“效果好”必须和“成本、延迟、合规”放在一起算账。我的经验是一个真实业务里至少有两类任务一类是固定格式、答案明确的比如工单分类、关键词抽取、意图识别这类任务根本不需要大模型“思考”中等参数模型甚至微调后的小模型就能干又快又便宜另一类是开放式、需要推理的比如写回复、做总结、拆解复杂指令这必须上强模型。于是“模型路由”方案就出现了入口先用一个又快又便宜的分类器判断任务类型简单任务走小模型复杂任务才转发给大模型。这种混合架构能省下相当可观的 token 成本响应速度也好看很多。实现路由的方式也不一定非得上复杂框架一个 LLM 分类 if-else 就够。另外提醒一句数据合规如果业务数据不能出内网就别纠结“最强开源模型跑不跑得动”了直接用可私有化部署的模型比如 Qwen 系列或者私有化 API 网关这比效果排行重要得多。模型这层追求的是“够用还稳”不是“顶配”。3.3 决策三上下文是桌面存储是仓库中间是摘要第三个决策处理记忆系统核心问题是哪些信息进上下文窗口哪些进外部存储上下文被撑爆了怎么办。先定一个原则上下文窗口里只放“当前这一步必须看到的东西”。比如售后 Agent 在处理工单时工单编号、用户诉求、相关订单状态这三样必须在场但用户三个月前的购买记录就不该出现在上下文里它应该躺在外部存储数据库或向量库等需要时再检索出来。当一段会话变得很长光靠“裁掉老消息”是不够的因为关键信息可能就藏在老消息里。我常用的套路是滚动摘要每处理完一轮就把此前对话压缩成一段结构化摘要下次调用时把摘要 最近几轮完整对话一起放进去。这样既保留了全局信息又控制住了 token 成本。再进阶一点就是分层记忆全局用户画像长期、会话摘要中期、原始对话短期按需组装。工程上建议把这些逻辑封装成独立的记忆管理模块不要散落在 Prompt 里——Prompt 里的记忆规则模型完全是“凭感觉遵守”的模块化代码才是真正可控的。3.4 决策四工具是用得越多越好还是越少越好第四个决策点直接决定 Agent 的“行动力”。我在 1.4 里说过工具太多会加大选错概率这里补一组实际数据感觉模型在 5 个候选工具里的选对率往往比在 20 个候选工具里的选对率高出不少——开放性候选越多推理压力越大越容易在工具描述上产生语义混淆。所以工具集的设计原则是“够用就好 语义清晰”。上线时先只给 Agent 三到五个最核心的工具跑通了再逐步加。每个工具的 Schema 要写成可以独立理解的小文档做什么、什么情况下调用、参数怎么填、有没有副作用比如“此操作不可逆”必须写清楚。还有一个很容易被忽视的点工具返回结果太复杂一样会把上下文窗口塞爆。你查一个订单接口可能返回 200 个字段但 Agent 真正需要的只有 5 个。建议在工具内部做裁剪和格式化返回给模型的是“精炼后的 JSON”而不是原始接口大包。这相当于给 Agent 配一个会“先说重点”的助手而不是把整本说明书砸它脸上。4. 后三个决策点规划、状态、上线与评估4.1 决策五固定管线还是自由 ReAct前面说过规划机制三选一这里重点讲第五个决策点业务里到底用固定流程还是自由推理。我的判断标准是如果任务结果需要可预测、可解释、可追责选固定管线如果任务本身就是开放探索型的——例如“帮我查查市场上还有什么竞品在做类似功能”选 ReAct 式自由规划。排错类任务可以适当让模型在管线内做局部选择但全局路径必须由流程控制。为什么这么强调因为自由 ReAct 的本质是“每走一步都让模型决定下一步做什么”这在一个有明确 KPI 的业务里是灾难模型可能突然去调一个无关工具可能陷入重试死循环可能在三步之后彻底忘掉用户最初的要求。固定管线恰好把“每一步做什么”写死在状态图里模型只需要在每个节点里做“小决策”比如这一步选哪个分支、提取哪些字段。工程实现上这套固定管线不要用超大 Prompt 去“感化”模型遵守要用代码控制。LangGraph 这类状态图框架在这一层价值很大节点、边、条件、中断、恢复全都在代码里明确定义模型只负责节点内部的生成任务。这样出问题你可以在图的任一步打断、改参数、重放而不是对着十几轮对话找“模型哪里想歪了”。4.2 决策六状态怎么建模失败重试和人工审批放哪里第六个决策点是最容易被新手工程忽略的Agent 不是一个“一问一答”而是一个有生命周期的工作流它的状态必须被建模、被持久化。先定一个最小状态集任务 ID、当前节点、输入快照、各节点输出、错误次数、审批状态。这个状态要存在外部存储里Redis 或 Postgres而不是存在内存变量里——道理很简单进程一重启、机器一挂内存里的状态全没了客户工单就丢了。然后是失败重试策略。工具调用一定会偶发超时、返回脏数据、鉴权失败这些都要在状态图里给出分支超时就重试重试两次还不行就转人工数据校验不通过就回到上一个节点重新抽取。重试要带退避不要狂轰接口——很多上游系统对突发重试很敏感会直接限流。最关键的还是人工审批节点Human-in-the-loop。凡是涉及改数据、退款、发消息、下单这类有实际影响的操作都必须在这个操作前插入一个“待审批”状态流程挂起等人工确认后继续。这个设计不只是为了合规也是给系统兜底——模型再怎么聪明也不能让它直接对真实世界做不可逆操作。状态图框架里的interrupt能力就是干这个的用起来比你手写队列靠谱得多。4.3 决策七上线前怎么评估上线后怎么观测最后一个决策点决定项目能不能“体面地活着”评估与观测体系怎么搭。先说评估别指望“用人眼抽查几条结果”就算评估。上线前至少要准备 50~100 条带标注的测试用例每条用例写明输入、期望行为、验收口径比如分类正确、回复包含退款链接、语气合规。然后跑批统计指标任务完成率、准确率、平均工具调用次数、失败率。没有这组数字你根本不敢跟业务方说“可以上了”。然后是观测。生产环境每跑一次 Agent都应该留下一条完整 Trace用户输入、每一步调了哪个工具、工具返回了什么、模型输出是什么、耗时多少、花了多少 token、命中哪个分支。工具上我推荐 LangSmith 或者 Langfuse 这类可观测平台能自动把链式调用串起来出问题以后点开 trace 图一眼看到哪一步歪了。最后补一个容易被忽略的成本问题Agent 的 token 消耗是普通 Chat 的几倍甚至十几倍因为一次任务要反复调用模型。上线前你要给每个任务设 token 预算上限超预算直接熔断转人工并且每周做一次成本复盘。评估和观测这层做扎实了后续优化才有依据——不然每个“灵光一闪”的优化都在蒙着眼睛改系统。5. 完整推演一个售后工单 Agent 从零到上线5.1 需求背景与七要素快照为了把这七个决策点串起来我拿一个我们团队实际做过的项目来推演售后工单自动处理 Agent。业务背景是一家电商公司每天几百张售后工单客服人力吃紧希望让 Agent 自动完成“工单分类 → 查询订单 → 生成回复草稿 → 高风险转人工”这一条链路。先把七要素快照填一遍。任务边界只处理售后工单不闲聊不做营销推荐模型底座公司数据不出内网用可私有化部署的模型配合一个小模型做前置分类记忆系统会话摘要 当前工单信息工具调用三个——查订单、查物流、发起退款申请规划机制固定管线执行状态状态图管理退款节点前插入人工审批观测评估接 Langfuse 做 Trace准备 80 条标注工单做回归集。5.2 七个决策点一次落完第一步定边界决策一不拆多 Agent单 Agent 走完整个工单流程。理由很直接链路虽然长但每一步输入输出都很清晰不需要两个模型互相“商量”拆成两个 Agent 反而多一层自然语言传递的开销。第二步定模型决策二做一个三层路由——入口用一个小模型做意图识别判断“这是售后单、是物流催单、还是其他类型”只有需要生成回复正文时才调用大模型固定模板场景比如纯物流催单用一个规则模板直接回复连模型都不调。这样算下来真正走到大模型 step 的请求大概只有四成成本立刻打下来。第三步定记忆决策三上下文里只放四样东西——工单编号、用户诉求截取前 500 字、订单状态摘要、近三轮会话摘要。用户的历史售后记录存向量库需要时按 top3 召回不占用主上下文。第四步定工具决策四只开放三个工具query_order(order_id)、query_logistics(tracking_no)、apply_refund(order_id, reason, amount)。前两个只读第三个有副作用工具描述里明确写了“调用后不可撤回需要人工确认”。返回结果在工具内部就裁剪成模型真正关心的字段。第五步定规划决策五固定管线状态图四个节点classify分类→lookup查订单/物流→draft_reply生成回复草稿→human_review人工审批。伪代码示意from langgraph.graph import StateGraph, END builder StateGraph(WorkOrderState) builder.add_node(classify, classify_node) builder.add_node(lookup, lookup_node) builder.add_node(draft_reply, draft_reply_node) builder.add_node(human_review, human_review_node) builder.add_edge(classify, lookup) builder.add_edge(lookup, draft_reply) builder.add_edge(draft_reply, human_review) builder.add_edge(human_review, END) graph builder.compile()第六步定状态决策六每个工单任务的状态快照写入 Postgreslookup节点工具调用超时重试一次仍失败则写入failed状态转人工apply_refund之前强制插入human_review节点流程挂起等审核人点“同意”才继续。这一步把整个系统的风险控制住了——模型生成错了不用慌人工在看门。第七步定上线评估决策七先跑 80 条标注工单重点看两个指标分类准确率要求 95% 以上和草稿可用率人工审核时需修改比例低于 30%。上线后每天看 Langfuse 里的 trace 分布哪个节点耗时最长、哪一个分支命中率最低、平均单量成本是多少。一旦单量成本超预算就把对应分支切回模板回复。5.3 上线两周我调整了什么这套系统上线两周最出乎我意料的是分类节点和回复节点都没出大问题真正拖后腿的是工具返回里的一个小字段——order_status有几种边缘状态比如“已申请退款待仓库确认”模型经常把这类状态误判成“退款已完成”导致回复话术给错。我们没有急着换大模型而是做了三件事第一在工具返回里把边缘状态单独拆字段并加中文释义减少歧义第二在draft_reply节点前加了一条规则判断命中边缘状态直接走人工模板第三把这类 case 补进回归集防止后续回归。改完以后草稿可用率从 74% 提到 88%效果立竿见影。这个案例想说明的就是Agent 工程不是搭好架子就完事它是一个持续用评估驱动迭代的过程——而每次迭代能精准找到问题靠的正是上线前布好的观测和评估体系。我个人的体会是大部分 Agent 项目翻车翻的从来不是模型能力而是前六个决策没想清楚第七个决策完全没做。把这套七要素、七决策的框架过一遍基本能把项目里至少八成的不确定性提前排掉。