★ FEATURED ARTICLE 做 Agent 工程有一阵子了从最初用大模型接几个 API 拼出 demo到后来把规划、记忆、工具调用、评测这些模块逐个拆开做工程化最大的感受是网上聊 Agent 的文章很多但大多数停留在概念层面真正讲清楚实现一个 Agent 到底涉及哪些模块、每个模块怎么选型、有哪些坑的内容反而稀缺。这篇文章我打算用两个框架把 Agent 的工程实现讲透首先是七要素也就是无论你用什么框架、什么模型一个能稳定运行的 Agent 系统在结构上绕不开的七个组成部分然后是七个决策点也就是真正动手做选型时你必须拍板的关键分岔路。读完你至少能回答这几个问题Agent 为什么需要一个规划模块记忆到底该塞多少进上下文工具是不是越多越好多 Agent 到底值不值得上以及怎么判断 Agent 干得好不好。文章适合两类人一类是正准备在业务里落地 Agent 的工程师另一类是已经被 LangChain、CrewAI 这些框架类项目搞花眼、想回到原理层面重新理解 Agent 的人。1. 七要素Agent 工程实现的基本盘先说我自己的结论Agent 不是一个大模型 工具调用这么简单的东西它本质是一个小型的自动化系统。为了方便理解你可以把 Agent 想象成一家微型公司——模型是老板的脑子规划是管理层记忆是档案室工具是员工的手脚执行是干活过程评估是质检部编排则是整套的公司运营流程。七个部分缺了任何一个系统要么跑不起来要么跑起来完全不可控。1.1 大模型底座Agent 的推理引擎怎么选模型是整个 Agent 的大脑所有理解、推理、生成动作都从这里来。工程上选模型和平时做聊天机器人选模型的标准不太一样除了看榜单分数还要重点关注三个能力上下文窗口够不够长、工具调用的格式稳定性好不好、复杂任务的多步推理能力行不行。我踩过最大的坑是高分模型陷阱。有些模型在通用对话和考试基准上表现非常好但放到 Agent 场景里让它在限定 schema 下输出工具调用参数它总是会多塞一些自定义字段进去或者把 JSON 格式搞坏解析层一天到晚报错。后来我总结出一个经验Agent 专用模型必须拿 Agent 任务来测不要只看基准分。另外如果同一个任务里既有推理又有工具调用建议把推理阶段和工具调用阶段的温度参数拆开工具调用阶段温度设成 0规划阶段稍微给一点随机性但也不要超过 0.2。成本也是选型的重要维度。像我做过的一个工单分类场景对推理深度要求并不高用一个小参数模型配合结构化输出就能达到大模型九成以上的效果单次成本差了七八倍。所以模型选型不要一步到位先跑最小可用版本再根据评测数据决定是升级模型还是优化提示词。1.2 规划模块把目标拆成可执行的动作规划模块回答的问题是怎么做。用户给一个模糊目标比如帮我分析这批销售数据模型不能直接一把梭输出结论而是要先拆解成读取数据、清洗字段、做汇总统计、生成图表、写出结论这些子任务。工程实现上规划的结果通常是一个结构化的任务列表每一项有状态标记比如待执行、执行中、已完成、失败。为什么要维护这个状态因为 Agent 在执行过程中会拿到新的信息可能某个子任务已经不需要做了或者需要插入一个新的子任务。没有状态管理的话规划就退化成了一段一次性 prompt模型干到一半就忘了下一步该干什么。我自己的经验是规划粒度不要做得太细。拆出超过八步的完整计划模型在长链路执行时很容易失焦。更稳的做法是先拆出三五个粗粒度的阶段每进入一个阶段再动态细化。这种粗拆加分治的思路比一次性输出一个十步大计划要实用得多。1.3 记忆系统短期上下文与长期知识的分工记忆是 Agent 和普通 API 调用最大的区别之一。聊天接口是无状态的但 Agent 必须在多轮交互中记得自己做过什么、用户说过什么、工具返回过什么。工程上我会把记忆分成三层来设计。第一层是工作记忆也就是当前任务运行时状态比如正在处理的文件路径、临时变量、已完成步骤列表。第二层是短期记忆通常是最近几轮的对话记录可以用滑动窗口来控制长度。第三层是长期记忆用来存放跨会话的知识比如用户的偏好、历史工单的处理方式、项目背景文档这一层一般要接向量数据库做检索。很多初学者容易犯一个错误觉得上下文窗口现在很大就什么都往里面塞。且不说成本模型对过长上下文的注意力会分散中段信息经常被忽略。更重要的是大部分实际任务的记忆根本不需要全量历史只需要关键的结论和状态。所以记忆管理的核心动作不是存而是决定忘什么和压缩成什么。我常用两个手段窗口滑掉久远对话后用一小段摘要替代工作记忆只用结构化状态对象不把原始日志塞给模型。1.4 工具层Agent 触碰世界的边界没有工具的 Agent 只能纸上谈兵工具层负责定义 Agent 能做什么也就是能力的边界。工程上每个工具对外暴露的就是三个东西名字、描述、参数 schema。名字要短且语义清晰描述要写清楚这个工具适用于什么场景、不适用于什么场景参数 schema 要严格定义字段类型和必填项。这三个东西看似简单但直接决定了模型能不能在关键时刻选对工具。一个非常反直觉的结论是工具不是越多越好。我做过一个项目刚开始挂了三十多个工具模型的选择准确率明显下降经常在该用 A 工具的时候选了 B 工具。后来我把工具收敛到十个以内把相似功能合并准确率立刻就上来了。原因很好理解工具数量增加模型在超长工具列表里做选择的负担就变大。如果业务上确实需要很多能力建议按域拆成多个子 Agent每个子 Agent 只维护自己的少量工具。另外还要考虑工具的实现方式平台的 Function Calling、以 MCP 为代表的标准化工具协议、还是完全自建的内部协议。这个我在决策点部分详细展开。1.5 行动执行从意图到结果的最后一跳执行层负责把模型选定的动作真正跑起来包括参数校验、调用目标服务、处理超时和异常、把结果标准化后回传给模型。执行层最容易被忽略的是错误处理。实际环境中工具调用一定会遇到超时、限流、参数不合法、下游服务 500 等问题。这些错误信息不是只记到日志里就完了而是要结构化地回传给模型让模型知道刚才发生了什么、下一步可以怎么修正。没有这一环Agent 就会在同一个错误上反复重试直到用完全部轮次。执行还有一个重要原则能并行的尽量并行。比如 Agent 需要查三个维度的数据这些查询之间没有依赖关系就应该并发执行而不是串行等待。工程上我用异步任务池来做单个工具执行设 30 秒超时整体步骤设 2 次重试。需要特别提醒的是代码执行类 Agent。如果 Agent 能写代码并执行一定要做沙盒隔离。我见过有项目直接让 Agent 在宿主机上跑 Python结果模型生成了一段删文件的代码差点出事。正确的做法是把代码执行放到容器或受限环境里挂载只读目录限制网络和系统调用。1.6 评估反馈让 Agent 学会自省和纠错评估反馈是很多 Agent 项目里最薄弱的一环。模型输出的内容看起来合理不代表任务真的完成了。比如一个信息抽取 Agent 可能抽出了字段但字段值对不上数据库里的真实实体一个工单回复 Agent 可能语气很好但完全没解决用户的问题。工程上反馈回路分两层。第一层是即时反馈也就是工具调用后直接返回的结果模型根据成功或失败决定下一步。第二层是任务级反馈判断整个目标是否达成。任务级判断有很多种做法简单的可以写规则校验比如检查某个关键字段是否生成、某个过程是否执行成功复杂的可以再让一个模型当裁判把执行轨迹和产出一起交给裁判模型打分。裁判模型不一定比执行模型强但视角不同冷静地评估结果往往能发现不少问题。更进阶的做法是让 Agent 写反思。完成一个任务后单独生成一段执行回顾分析哪些步骤有效、哪些判断失误这段反思可以随着最终答案一起输出给用户也可以沉淀到日志里用于离线分析。我之前在一个爬取整理类任务里加了反思机制后第二轮的修正明显比第一轮有针对性不再是无头苍蝇式乱试。1.7 编排循环把要素串成自动化流程最后一个要素是把前面所有东西串起来的编排层。没有编排模型、规划、记忆、工具都只是散件。主流编排模式是循环式的拿到任务后让模型基于当前状态工作记忆 短期记忆 工具定义决策一个动作执行后更新状态再判断是否完成没完成就继续下一轮。这个循环的退出条件非常关键一般有三个任务被标记为完成、达到最大轮数、遇到不可恢复的错误。最大轮数我通常设 5 到 10 之间太少了复杂任务跑不完太多了成本失控且容易死循环。编排层还有一个职责是可观测性。每一轮循环的模型输入、输出、工具调用参数、返回结果、token 消耗、耗时、成本全部要记录成 trace。没有 trace 的 Agent 等于一个黑盒出了问题根本无从排查。这一点在系统上线后尤其重要。2. 七个决策点选型过程中的关键分岔七要素讲的是系统必有的结构七个决策点则是你在真正落地时绕不开的选择题。同一个需求决策不同做出来的系统性格完全不同。下面按照我在项目里做选型的思路一个一个说。2.1 决策点一推理模式ReAct 还是 Plan-and-ExecuteReAct 和 Plan-and-Execute 是两种最典型的 Agent 推理模式。ReAct 是边行动边思考每走一步都根据最新观察调整下一步灵活性强Plan-and-Execute 是先让模型制定完整的计划然后照着计划逐步执行中途不轻易改道token 消耗更省、过程更可控。我的判断标准是看任务的开放程度。如果任务是开放探索型的比如调研这个行业的最新动态情况随时在变化适合 ReAct如果任务是线性执行型的比如把这份 Excel 按模板生成周报步骤基本可预测适合 Plan-and-Execute。实际项目里我更喜欢一个折衷方案先让模型产出一个粗粒度计划然后进入计划-执行-校验的短循环每轮执行后比对当前结果和计划偏差偏差大的时候允许模型小范围修订计划但不允许推倒重来。这个方案兼顾了省 token 和动态调整能力实测比纯 ReAct 稳定不少。2.2 决策点二单 Agent 还是多 Agent这个决策现在被炒得特别热但我必须先泼一盆冷水能用单 Agent 解决的需求别为了架构好看而上多 Agent。单 Agent 只有一个上下文、一条决策链路调试容易token 开销也省。多 Agent 带来的角色分工确实能提升专项能力但通信成本、上下文传递损耗、状态一致性这些问题会成倍增加。什么情况下值得上多 Agent我总结了两类一是任务角色有明显冲突比如既要写代码又要审代码这两个动作放在同一个 Agent 里容易出现自己审自己的盲区拆成开发者和审查者两个 Agent 更合理二是工具集过大前面说过工具太多模型选不准按能力域拆成多个专员 Agent每个专员管少量工具反而清晰。多 Agent 的协作拓扑也别搞太复杂。优先选择主管 专员或者流水线模式A 的输出作为 B 的输入链路清晰易追踪。那种所有 Agent 互相都能通信的全互联网格调试起来真的是灾难。顺带提一句如果你对性能和资源占用特别敏感可以考虑用 Rust 实现 Agent 的运行时和并发调度层。Rust 的零成本抽象和无 GC 特性在多 Agent 高频消息传递场景下优势很明显社区里已经有团队在这么做了。2.3 决策点三工具接入方式Function Calling、MCP 还是自建协议工具接入不是一个纯技术选型问题它决定了你和模型提供方的绑定深度。Function Calling 是模型平台提供的原生能力实现成本最低模型的兼容性也最好。缺点是 schema 格式跟特定平台绑定后期如果换模型厂商工具定义要改一遍。我自己在做快速原型验证时一律先用 Function Calling最短路径拿到业务结果。MCP 是近两年快速发展的标准化工具协议核心思路是把工具实现从模型侧解耦出来做成独立的 MCP server。模型只要通过统一的客户端去发现和调用工具就行不再关心工具背后是 HTTP 服务、数据库还是本地脚本。如果你的系统里工具有很多种形态而且未来可能切换模型值得评估 MCP。需要注意的是它的生态还在快速发展接入前要确认对端服务器和 SDK 的成熟度。自建协议适合工具完全在企业内网、且对安全审计有强要求的场景。用一套 JSON-RPC 风格的内部协议由中心网关统一管理工具的注册、鉴权和调用。好处是安全可控坏处是全部要自己写维护成本高。我的建议路径是验证期用 Function Calling 跑通工具类型变多后统一走 MCP对安全有特殊要求的核心工具直接连内部网关不做协议暴露。2.4 决策点四记忆策略滑窗、RAG 还是摘要压缩记忆方案没有银弹取决于你的任务形态。我见过不少团队不管什么场景都先上向量数据库看起来很高级实际大部分场景根本不需要。如果你的任务是单轮短对话型比如根据用户问题查一下订单状态滑窗保留最近三到五轮就足够了连向量库都用不上。如果任务是知识问答型比如根据公司制度文档回答员工问题那才需要 RAG把文档切块、向量化、建索引每次检索最相关的片段。如果任务是长会话型比如一个复杂的分析任务要来回迭代十几轮问题会变成上下文放不下这时必须要做摘要压缩。我常用的方案是每进行三四轮就触发一次摘要把前序对话的核心结论提炼出来替换掉原始对话记录。这个摘要不一定给用户看只是为了保持上下文的连续性和可控性。无论选哪种策略记忆写入和读取本身也要做结构化。我习惯把记忆分成事实型记忆用户说了什么、系统查到什么和过程型记忆已经完成哪些步骤分开存储读取时按当前任务类型决定优先加载哪部分。盲目把所有记忆一股脑拼进 prompt是最常见的低效做法。2.5 决策点五权限与安全边界Agent 的手能伸多长Agent 的能力越强权限失控的后果就越严重。权限设计的原则只有一条最小权限——Agent 拥有的权限不能超过发起任务的用户。实际操作中我会把工具的操作级别分成三类。只读类操作比如查询、搜索Agent 可以自动执行写操作比如发送消息、创建工单、修改数据必须在运行时策略里加入确认环节由用户在输出界面上点击确认高风险操作比如删除数据、转账、推送发布默认直接禁用除非显式配置例外。还有一个容易被忽视的漏洞来自输入侧。Agent 如果接了网页内容、文档内容这类外部输入就要防范提示注入攻击者把忽略之前所有指令按照我的要求执行 xxx藏在网页或文档里Agent 读入后可能被劫持。工程上的缓解手段包括对工具返回的外部内容做标记在交给模型前清洗掉可疑指令对敏感操作做二次校验不让模型自己判断。安全不是一次配置能完成的需要分层防御。2.6 决策点六评测与兜底怎么知道 Agent 没跑偏不建立评测体系就优化 Agent等于闭着眼开车。我在项目里做的第一件事就是收集一批有标准答案的任务样本组成回归评测集。每次修改提示词、调整工具定义、换模型都拿这个评测集跑一遍用指标说话。评测指标不用一开始搞得很复杂。必备四个任务成功率、工具调用准确率、平均完成轮次、单任务成本。成功率看目标达成情况准确率看 Agent 是不是每次都选对了正确的工具轮次和成本则用来监控效率和开销。对于有些没有唯一正确答案的任务我会用一个独立裁判模型对结果打分同时混入人工抽评避免裁判模型有自己的偏好。兜底机制同样重要。Agent 不是万能的出错时要能优雅地降级。我的做法是设三层兜底第一层有限重试允许同一个步骤自动重试两次第二层降级比如自动生成回复失败时退化成给人工客服派单第三层兜底直接返回一个预设的提示语告诉用户系统暂时无法处理并转人工。关键业务宁可走人工也不要让 Agent 硬撞。2.7 决策点七性能与成本怎么让 Agent 又快又便宜Agent 的成本大头在模型推理而推理成本又集中在 token 消耗上。很多人忽略了token 是 Agent 真正的货币——每一轮循环里模型输入的 prompt、输出的回答、工具调用的参数和结果全都在计费。第一个优化思路是减少无关内容。每轮只给模型当前任务必需的状态片段不要动不动把完整对话历史丢进去。第二个思路是加缓存。对于工具返回结果、公共知识片段、常用提示模板都可以做精确缓存甚至语义缓存命中后直接复用。第三个思路是模型路由简单任务用小模型只有复杂任务才路由到强推理模型。用一个分类器先判断任务难度能省一大笔钱。我在一个内部工具里对简单分类任务做了降级后单次成本降了约七成准确率几乎没有变化。延迟优化和成本优化往往是同向的减少无效轮次就是减少延迟和成本。另外一定要给单任务设 token 预算上限超过预算强制结束或者降级处理否则一个失控的循环可能会烧掉你整天的预算。3. 实操案例一个最小闭环的工单助理是怎么搭起来的讲完框架我用一个自己近期做的智能工单助理项目来演示怎么把七要素和七个决策点落到具体实现上。这个案例不复杂但麻雀虽小、五脏俱全你完全可以照着这个思路往自己的业务上套。3.1 场景定义与要素排序需求背景是企业内部每天收到大量工单内容涉及账号权限、设备故障、报销审批等不同类别。人工处理要先判断类型、提取关键信息、回复处理建议。我的目标是在不改变既有流程的前提下让 Agent 先做一轮自动预处理生成候选的分类和回复草稿再由人确认发送。在七要素上我做了明确映射模型选的是当前性价比比较高的商用模型上下文窗口足够但不需要最顶级规划用三步线性流程因为工单处理路径基本固定记忆用滑窗加一个简单的历史工单查询工具没有上完整的 RAG工具只挂了两个查历史相似工单和读取用户信息执行层用普通 HTTP 调用评估用一个独立的裁判模型对草稿打分编排则是最简单的循环结构。选型时最关键的判断是这个场景不需要多 Agent不需要复杂记忆不需要太多工具。克制的结果是系统简单、调试快、上线稳定后续的维护成本也低。3.2 核心链路的工程实现核心代码结构非常简单跑通整个流程大约只要十几个函数。为了方便你理解我贴一个简化版的核心循环伪代码框架无关重点看逻辑。class Agent: def __init__(self, model, tools, memory): self.model model self.tools {tool.name: tool for tool in tools} self.memory memory def run(self, task, max_steps5): # 第一步规划阶段生成粗粒度子任务 plan self.model.plan(task) self.memory.save(plan, plan) # 第二步进入执行循环 for step in range(max_steps): state self.memory.get_state_for_prompt() # 决策选择一个工具动作 action self.model.decide(state, self.tools_schema()) # 如果是结束标记跳出循环 if action.type finish: break # 执行工具拿到结构化结果 observation self.tools[action.name].run(action.arguments) # 更新记忆并把观测结果回传给模型 self.memory.update(action, observation) # 判断任务是否完成 done self.model.is_done(state, observation) if done: break return self.memory.finalize_output()对应七要素来看这段代码model 是大模型底座plan 是规划模块memory 统管记忆tools 定义边界tools run 是执行层is_done 是评估反馈外层 for 循环就是编排。这个版本的优雅之处在于它把所有状态都保存在 memory 对象里。每个步骤结束后 memory 会记录下当前动作、工具返回、关键变量所以无论是断点续跑还是日志排查都特别方便。3.3 关键参数与避坑心得几个参数我直接给你参考值max_steps 设 5工单场景很少需要更多轮次decide 阶段 temperature 设 0保证工具选择稳定单次工具调用超时 20 秒重试 1 次单任务 token 预算上限在 6000 左右超出强制走人工。这些值你要根据自己的任务调整但方向是没错的——尽可能用较小的轮次和较小的预算逼出有效行为而不是无限放宽。日志字段建议记录这些时间戳、模型请求和响应的完整内容、token 消耗、选中的工具名和参数、工具返回码、耗时、当前步骤状态。至少保留七到十天的日志后面排查问题全靠它。另一个小心得给模型的工具描述一定要像写接口文档一样写清楚边界。比如查历史工单这个工具我在描述里加了一句仅用于查询近 90 天内的工单涉及权限问题建议使用用户信息工具。加了这句之后模型选错工具的次数明显减少。4. 常见问题与排查技巧实录最后这部分是我实际运行过程中遇到的典型问题整理成速查表送给你们。每个问题都附了我的排查思路和处理方式希望你不用再踩一遍。4.1 上下文爆炸导致遗忘和超时现象对话超过几轮后模型开始遗忘早期用户说过的话请求体积过大导致接口超时费用快速上涨。原因每次请求都把全部历史对话拼进 prompt没有做记忆管理。排查方法很简单看日志里每轮请求的输入 token 数如果随着轮次线性增长就是这个问题。处理启用滑窗保留最近五轮更早的内容做摘要把工具返回结果里的无关字段在回传前先截断只保留关键信息。4.2 工具调用解析失败和参数漂移现象模型输出不是合法 JSON参数名和 schema 不一致偶尔多传了不存在的字段。原因模型能力不足或者工具 schema 定义太模糊、示例太少。尤其在用小模型时这类问题几乎必然出现。处理优先用模型的 Function Calling 原生能力而不是裸 JSON 输出这能大幅减少解析错误。schema 里每个参数都要写描述并提供一两个示例这招在减少参数漂移上效果显著。解析失败时把错误信息反馈给模型并允许重试等于让模型看到自己的错误并修正实测成功率能提升不少。4.3 Agent 陷入死循环或反复无效尝试现象Agent 反复调用同一个工具或者在一个错误上不断自我纠正始终不进入下一阶段。原因循环没有熔断机制反馈信号不清晰模型不知道该换策略任务的最终目标太开放模型觉得永远没完成。处理一定要设最大轮数限制同时加一个去重检测——连续三次执行相同工具相同参数强制终止并降级。还要在提示词里明确什么时候算完成给出可以安全停止的信号。如果目标确实很开放拆成多个子任务逐个收敛。4.4 离线评测通过率很高、线上效果很差现象回归集上成功率 90%上线后用户满意度却不高。原因评测集规模太小且场景单一裁判模型有评分偏好离线测试时没有考虑真实输入里的噪声和歧义。处理评测集要尽量来自真实历史数据覆盖各种边界情况不要只用一个裁判模型混入规则校验和人工抽评对失败案例做聚类分析针对占比例最高的错误类型改提示词或加工具。4.5 成本失控和延迟超标现象单任务平均成本比预期高几倍用户等待时间太长。原因循环轮次过多模型频繁做无效决策每次请求携带的内容过大没有模型路由和缓存。处理先把 max_steps 收紧再用语义缓存拦截重复的查询请求。重点任务用大模型简单任务用小模型分流。最后一定要设单任务 token 预算超预算自动降级宁可把场景转人工也不能让成本无止境地涨。我在实际项目里还有一个一直保留的习惯每周花半小时把这一周所有 Agent 失败案例翻一遍挑三条最典型的改进掉。很多小问题不积累到一定程度根本不会被注意到但每周修一点系统的稳定性会以肉眼可见的速度提升。做 Agent 工程到最后比的不是模型多聪明而是整个系统的可维护性和可控性。先把最小闭环跑通再逐步加记忆、加评估、加多 Agent这条路最稳。
阅读完成 · 觉得有帮助？
