好今天这篇我想聊聊 AI Agent 的工程实现。最近AI Agent这个词已经被说烂了朋友圈里十条有八条在聊但大部分聊的是概念和 Demo真正到生产环境里能稳定跑起来的项目反而很少有人把细节掰开讲。我自己前后做了几个 Agent 项目从最开始的玩具级到后来拆成服务、接上工具、带上记忆和权限控制最大的感受是Agent 不是一个模型调用的封装它是一整套工程系统。为了把这事讲清楚我把它拆成了两个维度——七要素和七个决策点。前者是 Agent 必备的组成器官后者是动手实现时必须拍板的路线选择。搞懂这两套东西你就不会被各种架构图唬住了。1. 先拆概念Agent 工程化的本质是什么1.1 为什么用七要素而不是直接看架构图市面上讲 Agent 的文章很多一上来就丢一张架构图模型放中间周边挂上记忆、工具、规划、安全看起来很清楚但你照着做就傻眼了记忆用什么存工具怎么定义规划逻辑谁来实现模型在里面扮演什么角色这些图全都不会告诉你。所以我建议换一种方式把 Agent 拆成一张工程检查清单。这也是我这里说七要素的原因——它不是学术定义更像是一个缺了哪个就要出事的部件清单。我的七要素是这七个模型底座负责语言理解、生成和基础推理规划与决策决定下一步要做什么、按什么顺序做记忆系统保存上下文、历史信息和长短期知识工具接入让 Agent 能调用 API、查数据库、操作文件行动执行把决策变成真实的执行动作反馈与反思根据结果修正后续行为安全与权限限制 Agent 能碰什么、不能碰什么你可以把 Agent 理解成一家微型公司。模型底座是公司里那个知识渊博但有点轴的员工规划层是部门经理负责拆解任务记忆系统是档案室前期聊过什么、做过什么决策都得存档工具接入是员工的办公设备行动执行是真正跑腿的部门反馈与反思是每周复盘会安全与权限则是公司的门禁和审批流。缺了任何一个这家公司都跑不稳。1.2 七要素之间的协作关系要素之间不是独立的它们之间有清晰的依赖链。模型底座是动力源规划层决策它发出指令指令落到行动执行需要用到工具接入执行期间和之后记忆系统不断记录新信息反馈机制把执行错误或异常结果回传给规划层触发反思安全与权限则贯穿全链路每一层访问都要过。我做一个简单的表格来对应要素和工程模块方便你动手时对照要素工程中的落地形式对应模块缺失时的表现模型底座主 LLM 辅助小模型指令理解偏差生成不稳定规划与决策Agent 主循环、任务分解逻辑死循环、跳步、不知道下一步干嘛记忆系统会话缓存、向量库、KV 存储聊到一半失忆重复劳动工具接入Function Calling 协议、API 网关模型只会回答不会执行行动执行工具函数、脚本、服务调用规划了但没人干活反馈与反思错误处理、重试机制、反思节点一错到底不会纠正安全与权限鉴权、白名单、操作审计越权调用、误操作、数据泄露这个表格我在实际做系统设计时经常拿来当评审清单。新项目开始前先对着这个表逐项检查我做了没有比一开始就纠结要不要上 RAG或要不要用 MCP之类的技术选项要靠谱得多。2. 七个决策点动手前必须拍的板要素是部件清单决策点则是工程实现时绕不开的路口。我在项目里基本都会遇到下面这七个决策每个决策背后都是实打实的坑。2.1 决策点一模型选型——Agent 的地基模型选型是最容易被低估的一个决策。很多人以为选模型就看谁强选谁但在 Agent 场景里你要看的指标完全不同。第一是上下文长度。上下文长度决定了你能给 Agent 多少历史信息和工作空间。如果你的 Agent 任务需要读长文档、做多轮规划上下文只有 8K 的模型会频繁截断导致中后段任务质量断崖式下跌。我习惯的底线是主模型至少 32K 上下文再短就得额外做记忆压缩工程复杂度会明显上升。第二是 Function Calling 的稳定性。这是最容易被忽略的坑。模型在普通对话里表现好不代表它的函数调用能力可靠。有些模型会在工具参数里编造根本不存在的字段或者把字符串枚举值写错。如果函数调用不稳定你后续的容错代码就会变得非常庞大且照样会漏。第三是成本和延迟。Agent 不是一个一次性的 Prompt 调用它有规划、执行、反思一股脑跑下来Token 消耗可能是单次对话的 5 到 10 倍。所以我的经验是主力模型负责规划和复杂推理小模型负责摘要、改写、分类这类简单任务。比如在一个客服 Agent 里我用大模型的调用量可能只占总量的三分之一剩下的是分类和提取全交给便宜的小模型成本直接省下一大截。2.2 决策点二任务规划走 ReAct 还是 Plan-and-Execute规划是 Agent 的大脑但现在主流的规划思路其实就两条ReAct 和 Plan-and-Execute。ReAct 的核心是边想边做模型每一步根据当前状态和工具结果输出下一轮行动直到任务结束。它的优点是灵活、适应变化缺点是在长任务里容易飘做着做着把原始目标忘了。Plan-and-Execute 的核心是先计划后执行模型先把任务拆成一个步骤列表然后按列表执行每一步比对要不要调整。它在复杂任务里更稳但对计划的拆解质量要求很高拆不好就是一步错步步错。我实际用的策略是混合式任务进来先做一个快速判断如果步骤少或不确定性高走 ReAct如果步骤多且有明确的流程逻辑先让模型生成执行计划并且在计划里强制加一个复盘检查点每两三个步骤回头校验一次目标。这个计划阶段复盘的混合方式比单纯用任何一种都稳。下面是我做选择时参考的判断表判断维度偏向 ReAct偏向 Plan-and-Execute任务步骤数少1-3 步多5 步以上目标明确度目标模糊需要探索目标清晰步骤可预期环境变化频率高常需要调整低流程固定典型场景问答、检索辅助数据分析、批量处理2.3 决策点三记忆系统怎么分层记忆是 Agent 最容易过度设计的部分。我见过很多项目一上来就上向量数据库结果任务只用到了最近两轮对话向量检索纯属摆设。我的建议是先按记忆类型做分层。短期记忆就是当前任务内的上下文通常用滑动窗口控制长度。我一般保留最近 4 到 8 轮对话或最近 2000 到 4000 Token超出部分压缩成摘要。工作记忆是当前任务的关键信息比如用户来自上海、订单编号是 10243。这个适合用结构化的 Key-Value 存储而不是塞进 Prompt 的对话流里。我把这种信息单独维护一个 JSON 字段每次请求时拼到系统提示里既准确又不占太多 Token。长期记忆是跨会话的知识比如用户的偏好、历史订单。这个才需要向量库或数据库。用向量库的话我建议按用户级做隔离召回时 TopK 设置在 3 到 5 就好太多了噪音反而大。嵌入模型维度常见是 768 或 1024但别以为维度越高越好对于短文本摘要512 维左右在召回效果和存储成本上更均衡。我给一个参考配置短期记忆Token 上限 4000超限后调用摘要模型压缩工作记忆增量更新 JSON保留最近任务的关键字段长期记忆按用户维度存向量库 MySQL召回 TopK52.4 决策点四工具协议走 Function Calling、MCP 还是纯 Prompt工具接入协议是 Agent 工程里争议最大的一环。目前三种主流方式各自有适用边界。纯 Prompt 方式就是在系统提示里描述你现在可以用哪些工具参数是什么请输出 JSON 格式。它实现起来最省事但可靠性最差输出格式经常出错解析成本高。适合只有一两个工具的小项目不推荐长期用。Function Calling函数调用是 OpenAI、Claude 等模型原生支持的机制。模型在回答时会附带一个结构化的工具调用请求你只需做参数校验再执行对应函数。这个是目前综合体验最好的方案因为底层经过了指令对齐稳定性远超 Prompt 方式。MCPModel Context Protocol是一个统一的工具接入标准把工具声明、参数、鉴权全部走一个通用协议。它的价值在于工具多了以后不失控一次接入多处复用。Rust 在MCP的生态里相当适合做工具网关因为工具网关往往是高并发入口Rust 的内存安全和性能特征在这里优势明显。我实际把自研工具网关换成 Rust 重写过一次压测下来延迟降低很明显CPU 占用也低了不少。我的建议是如果工具少于 5 个、没人跟你协作直接 Function Calling如果工具随时会增加到几十个或者要接入别的团队工具直接上 MCP别犹豫。工具数量一多统一协议带来的边际收益是几何级增长的。2.5 决策点五工具结果怎么回灌和容错工具调用的结果往往不是干净的。数据库查询返回的 JSON 可能缺字段API 可能超时第三方接口可能直接返回一段 HTML 错误页。如果这些原始结果原封不动地塞进 LLM 上下文轻则浪费 Token重则让模型产生幻觉。我常用的做法是结果净化。任何工具返回结果先经过一个包装器截断到合理的长度比如单次工具结果不超过 1500 Token把非结构化文本转成简洁描述带上下文和耗时信息。如果工具失败必须把失败原因结构化比如{status: error, code: 404, reason: 订单不存在}而不是让模型去猜。尤其要注意的是工具结果要不要交给模型这个决策不是天然的。有时候工具返回的是一个 50000 行的数据表模型根本处理不过来实际应该让工具层先聚合。比如 Agent 要统计一个月销售额工具层直接返回汇总值而不是原始订单明细。这类前置聚合在工具层用代码固定比靠模型自己知道要靠谱得多。2.6 决策点六观测和评估怎么做Agent 系统跟普通后端服务最大的区别是它的输出没有固定断言可测你在开发时只能看到它好像干成了或它好像搞坏了。所以可观测性是刚需。至少要做到三层。第一层是链路日志每次 Agent 循环里的 Prompt、模型输出、工具调用参数和结果都要完整记录下来。我自己会把每轮 Prompt 的 Token 数、耗时、模型名、温度参数全部结构化落库。第二层是运行指标包括单任务平均循环次数、工具成功率、Token 总消耗、任务中断率。第三层是业务结果评估用一个包含典型任务的回归集每次改动后自动跑一遍记录任务完成率和人工抽检分。在评估标准上我给一个可复用的经验值单任务 Agent 的平均循环数超过 8 次大概率是规划或工具定义有问题。Token 消耗环比上涨超过 30%通常不是任务变多而是记忆或上下文出了问题。这两个指标比任何看起来智能都更能反映工程质量。2.7 决策点七部署形态与并发策略最后是系统长什么样。我建议你尽量别让 Agent 逻辑直接暴露在 Web 请求里中间要夹一层队列和解耦。最初级的状态是脚本式运行适合后台批量任务。好一点的是 FastAPI 服务Agent 逻辑包成一个异步函数把流式输出通过 WebSocket 或者 SSE 推给前端。任务一旦多了你会发现同步阻塞在 LLM 响应上非常致命所以要把 Agent 跑在异步任务队列里比如 Celery 或 Redis Stream前端拿任务 ID 轮询或订阅结果。流式输出还有一个细节要对输出做增量清洗。模型偶尔会在流式输出中吐出一个未闭合 JSON 对象如果前端直接渲染会给用户看到半截脏数据。我的做法是只把最终 Token 流直接上屏结构化数据走独立接口不让用户直面模型的原生流。3. 实操现场搭一个最小可用的 Agent 服务前面讲的全是决策思路这一节我们来点能直接跑的东西。我会用 Python 展示核心骨架因为最容易理解。后面会说明哪些地方我换成了 Rust 组件。3.1 Agent 主循环下面这段代码是一个极简 Agent 循环。它做的事情是把用户输入加入消息列表循环调用模型看到工具调用就执行否则视为最终回答。async def agent_loop(user_input: str, tools: dict, max_iter: int 5): messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(max_iter): response await llm.chat_with_tools( messagesmessages, toolstools.values() ) if response.tool_calls: messages.append(response.to_message()) for tool_call in response.tool_calls: # 执行工具并净化结果 result await execute_tool(tool_call, tools) messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) continue return response.content return 任务未能在限定步数内完成请调整重试这里的关键是 final_answer。模型返回普通文本时整个循环就会终止。如果模型有返回{action: finalize}的倾向我们可以在 System Prompt 里明确要求。3.2 工具注册与执行工具定义务必要用 JSON Schema。我用一个装饰器把函数自动转成工具描述省去手写重复声明register_tool(create_post, 创建小红书图文内容) async def create_post(title: str, content: str, images: list[str]) - dict: # 实际业务里这里调用发布 API resp await xiaohongshu_api.create_post(title, content, images) return {status: ok, post_id: resp.id}工具层的执行过程必须包含超时和重试。我给每个工具调用设置的超时是 15 秒重试最多 2 次且只重试网络类错误业务错误不重试。这个规则必须在代码里写死不能交给模型判断。3.3 带反思的最小决策反思不是非要搞一个独立的 Reflection Agent。最小方案是在循环里检查每次工具调用的结果状态。如果连续两次工具失败就主动插入一条反思消息要求模型重新确认参数和当前目标而不是继续闷头执行。if consecutive_failures 2: messages.append({ role: user, content: 注意最近两个工具调用均失败。请暂停执行重新审视参数和任务目标然后只输出修正后的工具调用参数。 })这个简单策略在实际运行里极大降低了死循环式重试。因为模型在失败后往往会惯性用同样的参数重试插入一条外部提示句就能打破惯性——这算是零成本的反思机制。4. 常见问题与排查实录4.1 Agent 陷入死循环现象是任务迟迟不结束模型反复调用同一个或相似工具。排查时先看调用链日志确认是工具结果没被正确记录还是规划层在重复提出相同计划。常规解法有三步第一加最大迭代次数硬限制我常用 5 到 8 次第二规范化工具结果格式尤其是把无结果和出错明确区分第三在提示词里要求模型一旦拿到可用结果就立即输出最终答案。这三步能解决大部分死循环。4.2 Token 消耗失控最常见的原因是短期记忆把全历史一直带着跑。一长对话下来每次循环都重新发送全部历史Token 就会以指数级膨胀。我的解决方法是基于滑动窗口做历史归档超过窗口的对话内容先调用一次摘要模型压缩成一条记忆片段再长期存入记忆库。举个例子。一个任务跑了 20 轮未压缩时每轮要发 20000 Token总消耗可能 30 万 Token滑动窗口摘要后每轮新增量大概只有 4000 Token整体消耗降了一倍以上而且模型专注当前步骤的效果反而更好。4.3 工具调用出现幻觉参数模型会生成一个看起来像参数但实际上完全不存在的字段比如把content写成context或者给一个不知道从哪编出来的日期。这种问题不能靠提示词解决必须在执行前做严格参数校验。我用 Pydantic 定义每个函数的入参模型执行前强制反序列化校验不过是直接进入失败分支。这一条应该是底线所有外部侧输入的工具调用必须走校验。4.4 并发多用户场景记忆串线这个坑隐藏得比较深。如果你在一个全局对象里维护了一个 memory 列表两个用户同时使用时第二个用户的请求就会读到第一个用户的记录。解决方法是所有记忆对象必须按用户 ID/会话 ID 隔离不能存在全局实例的成员变量里。我在代码里用的是字典 会话锁或者直接用 Redis 按 key 存储会话状态后者在服务多实例部署时更可靠。4.5 工具网关的性能瓶颈等到单实例扛不住并发时可以关注一下工具网关的耗时分布。如果工具调用频率高但单个工具都是快速操作瓶颈往往在 Python 的处理层而不在 LLM。我把这部分换成 Rust 网关后QPS 提升了数倍内存占用反而下降。所以当一个 Agent 系统的瓶颈在工具调度层时用 Rust 做轻量网关是很值的方向这也是我关注 Rust 生态的直接原因。5. 一些不容易写在文档里的经验最后分享几个只有上手跑过才会知道的体会。第一Agent 工程最花时间的不是写 Agent 循环而是定义工具和清洗工具结果。工具定义是模型和现实世界之间的接口这个接口设计得不好后面所有环节都会失真。当初我做小红书发布 Agent最耗时的不是 Agent 逻辑而是对接发布 API、处理图片尺寸、适配不同内容模板。你以为在写 AI 应用其实在写中间件。第二再强的提示词也救不了不稳定的工具层。模型可以在参数上幻觉工具层可以返回脏数据记忆可以串线链路可以超时。一个生产级 Agent 的稳定性来自每一层都以处理异常为前提的设计而不是指望模型在端到端 Magic。第三别迷信某个框架能帮你解决所有问题。框架能够节省的是协议层工作量——比如工具调用协议的封装、MCP 的接入。但任务的规划策略、记忆的分层存储、评估集的设计这些始终是业务设计的一部分框架给不了你。如果这篇的七要素和七个决策点能帮你少走点弯路那就值了。下一期我可以聊一下Agent 的评估集怎么维护这个更实操的主题那个真的是谁做谁知道。