Agent系统工程化落地指南：架构、代码与避坑实践

聊 Agent 的文章这半年多太多了但大部分停在概念层要么讲 Prompt 技巧要么贴个框架 Demo。我这篇不太一样想从一个实际做过的工程角度把 Agent 系统这套东西掰开揉碎讲清楚它到底解决什么问题、理想形态长什么样、框架怎么选、代码怎么写、坑在哪里。文章后半部分还会给一个真实落地的完整拆解包括工具 Schema、ReAct 循环、记忆接入和评测方案你可以直接照着搭。先交代一个反常识的结论Agent 系统最大的难点不在模型而在工程。模型选型、提示词编排这些东西两三天就能上手真正难的是把记忆、工具、编排、安全和评测这几层结构搭稳让系统在真实业务里不失控、不烧钱、可排查。这篇就按这个思路展开。1. 先想清楚Agent 到底是一套什么系统1.1 别被概念带偏Agent 的核心是决策闭环讲 Agent 之前先把概念校准一下。现在市面上很多号称 Agent 的产品本质上是把 Prompt 写得很唬人让模型按照固定格式输出 JSON外边再包一层 if-else。这类东西不是不能用但它缺了 Agent 最核心的东西自主决策循环。真正的 Agent 系统至少要满足三个特征。第一它能感知环境比如拿到用户任务、看到工具返回的状态第二它能做决策决定下一步调用哪个工具、按什么顺序执行第三它能根据结果修正把工具返回的数据喂回模型继续推理直到任务完成或者触发终止条件。这个闭环一旦成立系统就能处理那些没有标准答案、步骤不固定的任务。这也是 Agent 和传统工作流最本质的区别——工作流是预先把每一步写死Agent 是让模型自己走流程。我判断一个需求要不要上 Agent就提一个问题任务的步骤是否固定如果固定用传统工作流引擎更稳省 token、好排查、行为可控如果步骤不固定或者各种分支路径太多这时候才值得考虑 Agent。很多团队一开始就把架构想复杂了恨不得第一版就上多 Agent、上复杂记忆结果后面调试起来极其痛苦。我的经验是能用规则解决的就用规则模型只在规则的间隙里做决策这样系统才抗造。还有一个容易被忽略的点执行层的存在。很多项目做到模型生成计划就停了没有真正调用外部系统因为调用意味着权限、沙箱、审批、超时这些工程负担。但恰恰是执行层决定了一个 Agent 是会说话的文档还是能干活的系统。我坚持的原则是没有实际副作用的决策循环不算 Agent。1.2 方法论从业务闭环倒推而不是从框架倒推我见过太多失败项目开头就错了团队先选好 LangChain 或者 Dify然后才开始想用它做什么。正确顺序是反过来的——先画出任务闭环再决定哪些环节交给模型哪些交给规则哪些留给人工。举一个我自己做过的例子。我们要做一个智能客服加工单处理的 Agent用户输入是一句自然语言问题最终输出是解决方案文本 一条已创建的工单 归档摘要。把这条链路拆开依次是意图识别、知识检索、方案生成、工单创建、异常升级。拆到这里架构需求就很清楚了需要一个规划器一个检索工具一个工单工具一个人工审批节点。每一步用什么模型、要不要调 RAG都是直接从业务需求反推出来的而不是框架决定的。方法论的第二个要点是从最小可跑闭环开始。不要第一步就搞长链路、复杂记忆、多 Agent 编排先拿一个模型 两个工具 一个终止条件跑通一遍让真实用户用一版再往里加能力。我做工程这多年越来越认同一个说法Agent 系统是长出来的不是设计出来的。这和写传统单体软件的心态完全相反传统软件讲究先架构后编码Agent 系统讲究先跑通再生长。因为模型的行为你没法在设计阶段完全预测只有跑起来才发现工具描述哪里写反了、上下文在哪里丢失了、哪类问题它天生就处理不了。1.3 理想形态不是一张架构图是一组取舍原则很多人喜欢看架构图但架构图其实是最终结果真正值钱的是背后的取舍原则。Agent 系统的理想形态并不是组件越多越高级、也不是越自动化越好而是每一层都有明确的边界和可控的出口。几个我长期坚持的原则直接分享在这里。第一模型负责不确定的推理系统负责确定的事实第二所有工具调用必须可追踪、可回滚高副作用操作必须有人在环第三记忆必须分层不能指望一个上下文窗口装下所有东西第四永远有终止条件包括最大轮数、超时、预算上限第五评测不是上线之后再做而是从第一天就有的回放机制。这几条原则贯穿了我在正文后面讲的所有设计也是我后来评估别人的 Agent 架构时最先看的几点。接下来就进入理想形态的分层拆解。2. 理想形态拆解一个 Agent 系统应该有哪些层2.1 五要素目标、规划、记忆、工具、执行我把一个合格的 Agent 系统抽象成五个要素目标、规划、记忆、工具、执行。目标是指系统必须理解用户真正想达成的结果而不是停留在礼貌回复。比如用户说帮我把上周的周报整理出来发给 leader目标不是生成一段周报文本而是创建版本、写入内容、调起发送动作这一条完整链路。规划是把目标拆成一串可执行的步骤也就是 task planning模型需要知道做完第一步之后第二步依赖什么状态。记忆是混合体既包含当前对话的短期上下文也包含长期存储的知识和历史摘要。工具是系统与外部世界交互的接口比如检索库、API、代码解释器。执行是把规划真正落地的过程包含权限控制、超时处理、结果回传。这五个要素映射到架构上自然就分成规划编排层、记忆层、工具层、执行层加上横切整个系统的安全层和观测层。你回头看 LangChain 的 agent、tool、memory、callback 这些模块其实就是这五大块的工程化包装。理解这层对应关系之后你再去看任何框架都不会被它绕晕因为所有框架本质上都在做同一件事让模型在一个可控的循环里调用外部能力。2.2 记忆层短期窗口、长期向量库、工作记忆与摘要策略记忆是 Agent 工程里最大的坑没有之一。LLM 的上下文窗口再大也扛不住多轮工具调用之后的信息堆叠。上下文一旦爆炸模型会开始忽略早期的关键信息回复质量直线下滑token 费用也不可控。我的做法是把记忆拆成三层。第一层是短期记忆直接放在 message 列表里但必须做窗口裁剪。我一般只保留最近 3 到 5 轮原始消息更早的内容交给第二层。第二层是长期记忆用向量库存历史的语义摘要每个会话按时间切成若干块每块压缩成摘要文本存进去。第三层是工作记忆专门保存任务过程中的结构化状态比如订单号、当前步骤序号、已经完成的工具列表。这类数据绝对不要扔进语义检索里应该单独额度 KV 存储用精确的键值去读。实际调优下来我发现摘要策略比向量库更值钱。把长时间对话每隔几轮做一次压缩摘要比把所有原文塞进向量库要经济得多也准确得多。原因是 Agent 在每一步决策时真正需要的往往是上一阶段我们完成到什么程度、结论是什么而不是全部原文。全文召回反而经常召回到噪声干扰模型判断。这个经验是我在一个连续 40 轮工具调用的任务里踩出来的那次之后我把对话摘要的触发频率从 20 轮调到了 10 轮失败率明显下降。摘要有它的必杀坑不能丢结构化字段。任务编号、用户 ID、金额这类字段一旦被压缩掉模型后面就会失忆所以摘要模板里我会强制保留这些字段的位置。2.3 工具层与技能层Function Calling 和技能抽象工具层定义了 Agent 的能力边界。没有工具模型只能空谈有了工具模型才有手。工程上一个工具的本质是一份描述 一个可执行函数描述是给模型看的函数是给执行层调的。拿当前主流的 function calling 来说模型会在推理时输出一个结构化的 tool_calls 对象里面包含函数名和参数系统按参数真实调用外部系统再把结果返回给模型继续推理。这里有几个细节直接决定工具层好不好用。工具描述里必须写清楚什么时候用、什么时候别用比如一个搜索知识库的工具描述要写明它只回答公司内部文档问题不做通用问答否则模型会把所有问题都甩给它。参数定义最好用严格的 JSON Schema模型会照着 schema 填参数字段名写模糊了很容易得到空值。工具返回结果一定要截断我通常只保留前 2000 字符防止大段无关输出污染后续推理同时也省 token。再往上一层是技能抽象这是现在越来越流行的做法。一个数据分析技能可能包含执行 SQL、画图表、生成结论三个工具模型按技能粒度去选择把原来几百个小工具收敛成十几个技能调用稳定性和可维护性都会大幅提升。Claude 的 Agent Skills、OpenAI 的 Agents SDK 里的 skill 概念本质上都是这个思路。这里也顺便回答一个经常被问的问题为什么有人用 Rust 做 Agent 框架因为 Rust 在高并发、低延迟的工具调度和沙箱隔离上有天然优势适合做底层的 Agent Harness。但对大多数业务团队来说Python 生态的迭代速度仍然是第一位的语言选择要看你的瓶颈在性能还是开发效率。2.4 编排层ReAct 循环、Harness 与多 Agent 触发条件编排层负责决策循环的具体执行。最经典的范式是 ReAct也就是 Reason Act。流程可以概括成模型思考下一步 - 输出文本或工具调用 - 系统执行工具 - 返回观察结果 - 模型继续思考 - 直到输出最终答案或达到终止条件。很多框架里的 AgentExecutor、AgentRunner干的就是这个循环的封装。它不是一个复杂的东西核心就是一个 for 循环加终止条件判断。真正要用心设计的是循环外面的约束也就是通常说的 Agent Harness。Harness 像缰绳用来限制模型的自由度防止它在错误的路径上无限打转。最基本的配置包括最大迭代轮数、单次工具调用超时、整体会话超时、人工中断机制。我给绝大多数任务设置的默认值是最多 12 轮、单工具 15 秒超时、整体任务 60 秒上限。没有这些约束的 Agent要么在死循环里烧钱要么卡在一个外部调用上让整个会话僵死。多 Agent 编排是单 Agent 跑通之后才需要考虑的事。为什么这么说因为多意味着决策路径更多、状态同步更难、调试复杂度指数上升。我只有在三种信号同时出现时才会上多 Agent任务有明显专业分工比如一个研究型 Agent 和一个执行型 Agent有并行处理多路信息的需求存在天然的角色对冲比如生成者与质检者。常见编排模式有 Supervisor 统一调度、Hierarchical 分层管理、Pipeline 链式流转、Debate 多角色讨论。但我的初始默认永远是先单 Agent 跑业务确定瓶颈是上下文混乱或者模型角色冲突再拆成多 Agent。一上来就上多 Agent 的团队往往是在用系统的复杂度换取架构图的漂亮。2.5 安全与沙箱层给 Agent 画红线的六个方向Agent 安全的特殊之处在于一个有自主性的软件要去调外部系统而且是模型自己在做决策。因此安全设计不能靠约定要靠结构。我总结了六个必做项。第一权限最小化。Agent 持有的 API Key 只给必要权限绝不能给数据库全局权限这个听起来像废话但我见过不止一次事故。第二命令沙箱。凡是模型要执行的代码一律丢进 Docker 或者轻量级虚拟机里跑网络按需放行默认拒绝出网。第三工具准入白名单。工具层只放行已经过审的 API没有登记注册的一律拒绝模型没有权限调用未知接口。第四人工确认节点。付款、发邮件、删数据、创建对外工单这类高副作用操作必须配置人工审批Agent 只能提交请求不能直接执行。第五审计日志。每一步模型输出、工具参数、返回结果、最终状态全部落日志出问题才有得回溯。第六限流与配额。对单会话、单用户的 token 消耗和调用次数设上限超过直接熔断。这些都是教训换来的。我经历过一个事故调试模式下Agent 在一个错误循环里反复调分析工具一晚上烧掉了数千美元的 API 费用原因就是没配限流和最大轮数。从那以后这两项成了所有 Agent 项目的默认配置。安全层不用做得多花哨把红线画清楚系统才敢放开手脚干活。3. 一次真实落地从选型到上线的全过程3.1 框架对比LangChain、Dify、CrewAI、自研到底怎么选框架选择直接决定你的开发节奏和调试体验。市面上常被提到的四个方案我全都实际用过做个直接对比方案优点缺点适合场景LangChain生态最全、组件丰富、抽象灵活版本迭代快、抽象层厚、出问题难查需要深度定制的业务Dify可视化编排、内置 RAG、开箱即用可编程性弱、复杂逻辑受限非工程团队快速验证CrewAI多 Agent 角色化清晰、上手快复杂编排和精细控制不够多角色、轻逻辑任务自研编排 裸模型完全可控、调试直接、依赖最少工作量大、底层全要自己处理核心业务、长期演进我的结论比较直白如果你是小团队要做的是内部工具直接走自研编排加官方模型 SDK别把核心逻辑外包给框架。如果你要给客户快速出 DemoDify 是最快的路径。如果团队已经有了大模型基建LangChain 可以用但要有随时自己写替代层的觉悟。CrewAI 适合 demo 性质的多角色场景真上生产你会很快碰到它能力边界。以我自己那次真实落地为例最终选择了半自研路线底层模型通信自己封装编排循环自己写工具接入自己管理向量库和部分工具组件复用了开源库。这个选择不是炫技纯粹是可控性优先——框架的抽象层在排障时太费时间。LangChain 这类框架胜在组件多但也意味着你在查问题时要在它的检索器、回调、链式逻辑里翻很久不如自己的 200 行循环看得清爽。3.2 落地需求与方案一个研发助手的完整目标这次落地的产品是个内部研发助手核心需求一句话让研发团队用自然语言少开几个页面。具体来说它要能回答项目背景类问题能帮员工生成周报能创建内部任务还能查询 CI 构建状态。注意这里刻意不做成万能 AGI只做高频场景覆盖目标非常明确。系统的核心组件拆分如下。模型层通过统一网关调用不同厂商的模型默认主力模型是可以支持复杂 function calling 的 Claude 系列也兼容 GPT 系列和国产模型统一封装在 LLMClient 里服务上层无感知。路由层在第一轮做一次意图分类将输入路由到知识问答子路径或任务助手子路径避免一个 Prompt 包打天下各自路径的稳定性能独立调优。工具集一共 6 个RAG 检索、创建任务 API、查 CI 状态、查询用户信息、发送群消息、周报生成每个都是独立函数。记忆层采用会话窗口裁剪加每 10 轮摘要压缩入向量库。编排层是 ReAct 循环最大 12 轮整体超时 60 秒创建任务这类副作用操作必须人工确认。部署层用 FastAPI 加 Docker Compose 单机部署Redis 做会话缓存。这个架构最大的特点是简单每个模块都能单独测试。因为它简单后来加功能才没有被一堆框架抽象绑架想加一个工具就是写一个函数再加一份描述想换模型就是改一个网关配置。我建议所有中小团队的第一版都往这个方向靠先把闭环搭稳。3.3 核心实现拆解工具 Schema、ReAct 循环、记忆与人工审批核心实现里最关键的是工具定义和调度循环。先看工具定义我用 Pydantic 的 JSON Schema 来定义创建任务接口from pydantic import BaseModel, Field class CreateTaskInput(BaseModel): title: str Field(..., description任务标题总结用户意图) assignee: str Field(..., description负责人邮箱) due_days: int Field(2, description截止天数默认2天) tools_schema [ { type: function, function: { name: create_task, description: 当用户需要创建内部研发任务时使用不用于普通知识问答。, parameters: CreateTaskInput.model_json_schema(), } } ]这一段看着简单但工具描述里的每一句话都直接影响模型是否在正确的时候调用它。我把不用于普通知识问答写进去就是因为一开始没写知识问答意图也会调这个工具浪费轮次。接下来是最核心的 ReAct 调度循环伪代码级别的 Python你可以直接移植到任何语言async def run_agent(user_query, session_id): messages load_history(session_id) messages.append({role: user, content: user_query}) for step in range(MAX_STEPS): response await llm.chat_with_tools( messagesmessages, toolstools_schema, ) messages.append(response.to_message()) if response.tool_calls: for call in response.tool_calls: result await execute_tool(call, usersession_user) messages.append(tool_result_message(call.id, result)) if call.name in SIDE_EFFECT_TOOLS: await notify_human_approval(call, result) else: # 模型已给出最终回答终止循环 return response.content return 已达到最大轮数请人工介入执行顺序值得你细看。副作用工具不会当场落库而是先进入待审批状态把已提交审批请等待返回给模型等人工确认后再真正执行。这样模型可以继续做后续步骤不会因为审批而卡死整个循环。execute_tool 内部还包了一层统一的超时处理每个工具最多跑 15 秒超时返回错误让模型换条路径走。这就是我在前面反复提的 Harness 思想不是限制模型能力而是保证它永远有退路。记忆接入代码不复杂但容易写歪。会话读取时我用最近 3 轮原始消息再加向量库拉到的历史摘要写入时每累积 10 轮触发一次 summarize把前面的对话压缩成一段 JSON存进 pgvector。记住我在 2.2 节强调的那句话摘要必须保留结构化字段。任务编号、用户 ID、当前审批状态一旦丢了后续轮次的模型决策就是空中楼阁。3.4 评测集设计三个指标、回放机制与迭代方式Agent 系统最难的不是写代码而是证明它好用。传统分类任务的准确率在这里不够用因为 Agent 的输出是过程性的模型可能最终答对了但过程中多调了 3 个没必要的工具。我做了一套三层评测思路。第一层是任务完成率判断最终结果是否达成用户的真实目标人工去打标。第二层是工具调用正确率每步调用是否合理也由人去标。第三层是无效循环率统计有多少轮是重复、卡死或者在两个工具之间来回横跳。配合一个 50 条任务的小评测集每条任务实录完整的对话日志和工具日志每次迭代完跑一遍全量对比三个指标的分数变化。只有三个指标同时提升我才敢说这次改动是正向的。更关键的是把评测做成视频回放而不是分数报告。我会写一个回放工具把 Agent 每一步输入输出全部渲染成时间线标出哪一步选错了工具、哪一步浪费了轮数、哪一步因为返回截断信息不足。回放做完你会惊讶地发现大部分失败不是模型不行而是工具描述写反了、返回结果截太狠、或者记忆摘要丢了关键字段。把这三类问题修掉任务完成率普遍能从 60% 拉到 85% 以上。这个现象让我形成了一个判断Agent 调优的精力分配大约七成在数据和工具侧只有三成在模型提示词上。4. 踩坑实录高频问题与排查技巧4.1 高频问题速查表按症状定位病因整理一个高频问题速查表。这张表里的内容全是我和周围的同事在不同项目里真实踩过的症状常见原因排查方法模型反复调用同一个工具工具描述没说清边界、返回结果信息不足检查返回是否含成功标志完善工具描述模型回答无法找到答案RAG 召回结果为空、结果被截断查检索日志调整 chunk 大小和 TopK上下文长度继续超限没有窗口裁剪、摘要没定期触发打开滑动窗口每 N 轮强制摘要Agent 长时间不返回最大轮数过大、工具超时未处理调低轮数给每个工具加独立 timeout多 Agent 互相推诿角色分工不清、公共状态缺失强化角色边界引入共享状态黑板API 费用异常暴增缺少配额与限流加全局 token 上限与预算告警有几个点必须展开强调。工具超时是最容易忽略的如果你的一个外部 HTTP 工具卡了 30 秒不返回模型会一直等整个会话就僵死在那里用户那边只看到一个永远不结束的 loading。所以执行层写一个统一的 timeout 包一层比任何花哨优化都管用。另一个点是 RAG 截断工具返回给模型的内容不是越多越好截断阈值太狠会丢掉关键证据太宽又引入噪声。我在这个项目里的经验是先按 2000 字符截断然后根据回放日志逐步调整到 2500 到 3000每个知识域的差异还挺大。4.2 三个值得长期投入的工程底座观测、配置回滚、持续评测代码跑通、指标达标只是第一环。如果你打算把这个 Agent 长期养下去接下来的工作重心不是加功能而是把工程底座做厚。我推荐最先投入三个方向。第一个是观测性。把每一次模型输入输出、token 消耗、工具调用参宿、延迟全部落到统一的 tracing 系统里。没有观测你排查问题时只能靠猜第二次事故的定位时间至少翻倍。OpenTelemetry 生态已经有成熟的 LLM tracing 方案FastAPI 中间件挂一下就能做到全链路。第二个是可回滚的配置。把 Agent 的 prompt、工具描述、记忆参数、RAG 参数全部抽成版本化配置文件上线后随时能回滚到任意历史版本。这能避免一个场景你想调一下 prompt 对线上的一次失败回复结果改完 prompt 又引发了另 10 个回归问题手忙脚乱改代码重发。第三是持续评测。把每个线上失败 case 都收进失败样本库每次迭代都重新跑一遍全量评测防止修了 A 问题又带出 B 问题的回归。我自己从第一个 Agent 生产项目开始第一天就会把这三件骨架搭好。它不会让你的第一个 Demo 更快甚至前期有点繁琐但它决定了这套东西能不能稳定活过三个月而不是在上线后的第三周就变成没人维护的玩具。4.3 想入行 Agent 的人该怎么学、怎么答面试最后聊点实际的。Agent 学习路线和面试题是最近的热门但市面上真没有标准教程。我建议按三层递进的方式补。第一层掌握 Prompt 工程和 Function Calling能用官方 SDK 写一个会调工具的原型。这一步筛掉一半人因为很多人只会聊天模板不会让模型结构化输出工具参数。第二层理解 ReAct、Plan-and-Execute、Reflexion 这些推理范式并且能在代码里实现一个最小循环思考、调用、观察、再思考。这一步验证的是你是否有工程手感而不只是懂概念。第三层动手部署一个带记忆、带沙箱、带评测的完整系统把权限控制、超时、限流、观测这些工程细节全部踩一遍。能走到第三层的人面试基本不用慌。面试被问如何设计一个 Agent 系统时不要上来背框架而是讲方法论。你可以先讲任务闭环拆解再讲目标、规划、记忆、工具、执行这五要素的分层取舍最后抛出一个真实案例的失败与修正。面试官最想听的不是框架 API 名称而是你在踩坑中形成的判断力比如为什么给工具加白名单、为什么摘要要保留结构化字段、为什么评测要做回放式分析。这些细节才区分了用过 Agent和做强过 Agent。回到我自己这个项目上我越来越觉得 Agent 系统的上限由模型决定下限由工程决定。模型决定它能多聪明工程决定它在混乱真实世界里多稳定。所谓混乱包括乱写的工具描述、超时的外部接口、丢字段的记忆摘要、缺失的审计日志。把这些细节一个一个磨平一个够用且稳定的 Agent 并不遥远。如果你读完能少踩几个坑这篇就算没白写。