这两年“AI Agent”这个词被聊得太多但真正能讲清楚一张Agent架构图的人其实很少。很多人拿着一张画得花花绿绿的架构图告诉你这是“规划模块”、那是“记忆模块”但你要追问他这些模块之间传输的数据结构是什么失败重试的机制在哪里多Agent的上下文边界怎么切分他自己也开始含糊。原因很简单多数架构图是在画“名词”没在画“关系”和“约束”。这篇内容我想彻底把Agent架构图拆一遍。基于我实际落地过几个项目的心得从最经典的智能体闭环开始到记忆、规划、工具调用、多Agent编排再到真正画图时要避开的五个坑尽量讲成可以直接给团队做技术评审用的那种深度。1. 看懂架构图的起点Agent到底比模型多出了哪一样东西1.1 裸模型与Agent的本质区别不在模型本身先达成一个共识Agent不是某种更强的模型不是GPT-5或者别的什么新版本而是一种围绕模型搭起来的运行时系统。裸的LLM拿到一个问题它只能做一件事基于训练参数和输入上下文推算下一个token。它不能自己去查数据库不能调用接口不能等到外部事件也没有“这步做完了下一步做什么”的概念。所谓Agent本质上是给模型加了一套外部循环模型在这个循环里扮演推理和决策的中枢但真正干活的、拿数据的、验证结果的是循环里的其他模块。我常用的一个类比LLM是大脑Agent是整个人。大脑光会想没用得有手、有脚、有感知系统还要有个“小脑”负责协调动作的先后顺序。架构图里画的所有模块本质上就是在给这个“人”配置器官。所以看一张Agent架构图第一眼看的不应该是某个模块多高级而是这个循环是否完整——感知、决策、行动、观察反馈能不能绕成一个圈。绕不起来的画得再好看也只是个“增强版Prompt包装器”。1.2 最小闭环是判断架构图是否专业的分水岭我见过不少团队的Agent架构图画得特别大有十几个模块什么“语义缓存”“意图识别”“记忆提炼”“安全审计”但仔细看核心循环断掉了。常见的有三种断法决策之后没有行动层模型输出一段话就算完根本没有调用任何工具行动之后没有反馈回路工具结果没有回流到模型上下文里Agent做完了不回头看结果反馈回路有但全塞在同一段Prompt里没有状态管理和退出条件。对比之下真正能落地的Agent架构图无论画得多复杂中间一定有一条清晰的主干循环用户输入进入模型规划规划结果转成工具调用工具结果回到模型模型判断是否还要继续直到满足结束条件。这条路径上任何一环缺失Agent就退化成聊天机器人或者变成一条“单次任务链”。所以我在评审架构图时第一个动作永远不是看它用了什么新技术而是拿荧光笔把主干循环描一遍。描不出来说明设计者自己都没想清楚。2. 一张合格的Agent架构图通常有哪四层2.1 感知与输入层别把所有输入都塞进Prompt架构图最底层或者最左侧通常是输入层。但这一层往往被画得过于简单一个“用户输入”框就完了。实际工程里输入层要做的事情远比想象中多。至少有三类输入需要区别对待第一类是显式指令比如用户说“帮我把这份报告总结成PPT”这种直接进入规划层处理第二类是环境状态比如当前系统时间、用户所在时区、近期订单状态这些不一定需要模型实时感知可以通过工具按需获取第三类是事件触发比如定时任务触发、外部Webhook推送、数据库变更通知这决定了Agent是主动运行还是被动响应。很多架构图把三种输入混在一根线里直接灌进Prompt这是很典型的错误。后果就是上下文被大量无用信息填充模型注意力被稀释token成本暴涨。正确的画法应该是明确哪些输入走“长期记忆检索”哪些输入走“工具按需拉取”哪些输入直接进上下文。输入层是架构图的入口也是第一道过滤网。2.2 规划与决策层这里藏着Agent的“智商”规划层是架构图里最容易被画成玄学的部分。有些图直接写“大模型推理”有些图写“ReAct”有些图写“任务规划器”但你得知道这些名词背后对应的是不同的机制。规划层实际要做的事情有两件第一把大任务拆成可执行的小步骤第二在每一个循环节拍里决定下一步动作。前者是宏观的任务分解后者是微观的动作选择。任务分解目前有两大类典型实现。一种是文章里常见的“一次性规划”模型根据目标直接生成一串步骤清单然后逐个执行另一种是“动态规划”模型不一次性拆完走一步看一步每次循环只决定“下一步做什么”。两种没有绝对的优劣一次性规划对短链路任务效率高但对长链路容错差前面错一步后面全废动态规划灵活但更容易陷入循环。成熟的架构图会明确标注当前采用的是哪种规划策略并画上对应的“循环终止条件”。2.3 记忆层短期、长期和工作记忆不能混为一谈记忆层是Agent架构图里最被低估的一块。很多人以为记忆就是“把历史对话存起来”根本没意识到记忆层真正解决的是一个矛盾的诉求模型上下文窗口是有限的但任务可能需要依赖很久之前的某个细节。我习惯把Agent记忆拆成三个池子架构图上至少画出其中两个工作记忆就是当前上下文窗口里实时存在的信息包括用户指令、中间推理、工具结果。这个池子的特点是快、但小。长期记忆存在外部存储里的历史信息可能是向量数据库里的语义索引也可能是结构化数据库里的用户偏好。这个池子大但需要通过“检索”才能调到工作记忆里。情景记忆关于“上次某个任务是怎么做的”的经验类信息很多Agent系统把它归到长期记忆里但严谨的架构设计会单独区分因为它的更新频率和一致性要求完全不一样。架构图上最容易出的问题是不画记忆的写入路径。很多图画了“向量数据库”但没画清楚什么东西在什么时机被写进去。是每轮对话结束后自动提炼还是任务完成之后做一次总结归档还是用户在明确说“记住这个”的时候才写入这三者的效果差别非常大。我踩过的坑就是前期没设计写入策略结果向量库里全是垃圾检索召回的质量一塌糊涂。2.4 行动与工具层Agent的手和脚行动层是Agent区别于“只会说”的模型的关键。这层的架构图核心是工具注册表、调用路由和结果规范化。架构图上至少要体现Agent如何知道有哪些工具可用工具的参数结构是怎样的工具调用失败后怎么处理当前主流实践是采用Function Calling结构模型输出一个结构化的工具调用意图系统负责真实地发起调用。你在架构图上应该看到一条清晰的路径规划层产出“需要查询A城市的天气”这样的意图然后通过工具路由到天气API获取结果再转成统一的文本或结构化格式回到上下文。这一层还有两个常被忽略的角色一个是工具描述信息也就是给模型看的说明书决定模型能不能在正确时机选择正确工具另一个是工具返回值的安全与大小控制一个接口返回5万行数据全塞进上下文再强的模型也扛不住。成熟的架构会加一层返回值的摘要模块只把关键信息塞回上下文。3. 架构图里的箭头比盒子更能暴露设计水平3.1 数据流每根线都要能说出数据格式很多架构图里盒子与盒子之间的箭头只是“有关系”的意思这不行。一张能指导开发的架构图每根线上都应该能标注出核心数据结构和传输方向。一个简单可行的强迫症做法画完架构图之后给每条连线标注数据内容。比如“用户请求”这根线标注“JSON{query, session_id, timestamp}”“工具调用”这根线标注“结构化意图{tool_name, arguments}”“工具结果回传”这根线标注“JSON{status, content_summary}”。标不出来的箭头就是没想清楚的箭头。这里有个很实际的原因Agent开发本来就是一个跨模块调试的活模型输出格式不稳定工具返回结构不一致如果架构图上连数据长什么样都定义不了到联调阶段就会变成灾难。我在一个模拟项目里就经历过规划层输出的工具参数偶尔是字符串、偶尔是数组、偶尔是JSON字符串套JSON就是因为最初的架构图里根本没定义这层协议。3.2 控制流Agent的循环到底循环在哪比数据流更要命的是控制流。Agent最核心的控制逻辑是“循环”。但循环套在哪儿不同架构图画出来完全不一样。有的Agent套的是“大循环”模型推理一次工具调用一次结果再反馈给模型再来一轮直到模型说“我完成了”。这是最经典的ReAct式循环。但生产级架构图里循环往往不止一条。我建议至少画三条控制路径主循环路径规划-行动-观察-再规划这是Agent的节拍器。终止条件路径什么时候跳出循环是模型判断“完成”还是达到最大步数还是外部超时。异常处理路径工具报错、模型输出格式非法、上下文过长怎么中断和恢复。我经常看到的是只画了主循环没画终止条件。这就导致一个现象线上Agent“永不认输”绕来绕去或者压根不退出。这类问题在架构评审阶段如果画出了终止条件路径是可以提前暴露的。3.3 工具结果反馈路径人是怎么“看”到结果并决定下一步的工具结果返回给模型之后架构图上还应该有一个关键的“消化”环节。多数人想得很简单模型看到工具结果直接决定下一步。实际上工具结果往往不能直接丢给模型。原因在于原始结果不可靠。一个搜索接口可能返回了大量噪声一个数据库可能返回的是表象数据一个爬虫拿到的网页可能有脏数据。所以在架构图上工具执行之后通常会加一个“结果处理”节点——做校验、清洗、摘要。这个节点是人写的代码不是模型。很多团队把结果处理直接交给模型“自己看着办”等于把可靠性建立在概率上。我的建议是工具返回后先走一层确定性代码做格式校验过滤明显异常值再做一个长度控制最后才把处理后的结果送回上下文。这个环节画在架构图上意味着你这个Agent的每一步行动都是有据可依的。4. 从架构图到实弹演练单Agent与多Agent的编排差异4.1 单Agent场景一张图能装下但别贪心对于大多数业务场景单Agent就足够了。所谓单Agent就是一条闭环处理所有用户的请求。它的架构图通常是输入过滤器 → 上下文组装 → 模型规划 → 工具调用 → 结果回流 → 输出。单Agent架构的优劣很清晰优势是链路短、调试容易、状态管理简单token消耗相对可控。劣势是所有能力都挤在一个上下文里当任务横跨多个专业领域、需要完全不同的工具集和评估标准时单Agent会被上下文拖垮。而且单Agent的Prompt越来越长维护成本极高。如果一个Agent要同时处理“查天气、订机票、写旅行攻略、分析酒店评价”这四件事硬塞在一起模型非常容易在规划阶段把工具参数搞混。这时要么加一个“意图路由”要么就考虑多Agent拆分。4.2 多Agent编排三种主流拓扑全部看懂才算入门多Agent架构是架构图最复杂也最容易被过度设计的方向。我觉得至少得看懂三种拓扑串行流水线模式Agent A处理完传给Agent B。适合流程固定、阶段清晰的任务比如“文档解析Agent → 信息抽取Agent → 报告生成Agent”。缺点是一环出错直接中断。路由分发模式最上层一个超管Agent或者确定性路由器判断请求属于哪类然后分发给对应的专业Agent拿结果返回。适合技能边界清晰、各Agent独立迭代的场景。这是目前落地最多、也最稳妥的模式。协作模式/黑板模式多个Agent共享一块信息空间各自读写共同完成一个目标。这个听起来很酷但实现难度最大因为需要设计一套共享数据规范还要解决“谁负责最终整合”的问题。我对这类架构的态度是除非团队有很强的工程能力否则别一开始就上协作模式。4.3 多Agent架构图必须单独画出来的三个元素很多多Agent架构图只画了若干个Agent框和连线缺少三个关键元素第一个是共享上下文规范。Agent与Agent之间传什么是整个对话历史还是任务摘要还是结构化中间产物不定义规范Agent之间就是鸡同鸭讲。第二个是协调者/调度策略。谁来决定任务给哪个Agent是模型做路由还是代码做路由很多系统号称“智能路由”实际上是靠关键词匹配架构图上应该画清楚这个策略的类型。第三个是全局状态存储。多Agent跑同一个任务用户取消之后当前进度存在哪Agent崩溃了状态怎么恢复没有全局状态多Agent就是多个单机各跑各的根本不是体系。5. 画架构图请避开的五个典型坑几乎每个团队都踩过5.1 把Prompt模板画进架构图这是逻辑错误不是细节问题一些架构图会在“规划模块”里直接写上大段Prompt文本。这暴露的问题是设计者把“架构”和“配置”混为一谈。Prompt是运行时读取的配置不是架构组件。如果把Prompt写死在架构图里微调一次Prompt所有文档全要改。更好的做法是架构图只画“提示词模板管理组件”和“上下文组装器”说明它负责在运行时拼接系统提示、工具描述、历史记忆。具体Prompt内容放到代码仓库里管理。5.2 “人人都是Agent”式的过度拆分很多团队一搞多Agent第一反应是让每个员工角色对应一个Agent“财务Agent”“HR Agent”“销售Agent”。这是把组织架构搬到了Agent架构上完全没有从任务复杂度出发。过度拆分最直接的后果是token成本成倍上涨和响应变慢。本来一个Agent能完成的简单问答硬要路由两个Agent协作中间的调度、上下文传递、结果汇总全都要烧token。我的经验是一个任务如果能用一个Agent加几个工具完成绝不上多Agent。多Agent是解决问题的不是用来显摆架构复杂度的。5.3 忘记画失败路径我见过太多架构图每根线都指向成功。没有超时、没有重试、没有降级。实际操作中工具调用失败率远比想象中高——网络超时、接口限流、返回格式变化、权限不足。架构图上应该为每一个外部依赖画一条失败分支失败后是重试还是换工具还是调用“兜底Agent”给用户一个可接受的说明。隐藏失败路径的架构图到了线上绝对会漏底。5.4 把上下文窗口当成无限内存有些架构图把“记忆模块”画成“上下文扩容”在架构上没有任何机制只是祈祷模型窗口变大。这是思路错误。窗口再大也装不下真实业务里的长期知识的量级。正确的做法是承认上下文窗口是稀缺资源让记忆模块承担筛选和压缩的职责。架构图上一定要体现“检索→排序→截断→注入”这一段处理流程而不是简单一条线连到模型。这个设计决定了Agent能不能在低成本下处理长周期任务。5.5 没有安全边界Agent的安全不是一句“加了提示词”就够了。它分为两层基础安全和业务安全。基础安全包括输入信息过滤、输出内容合规检测防止恶意注入防止Agent被诱导调用危险工具业务安全包括工具执行的权限控制、敏感数据脱敏、操作审计日志。架构图上至少要画一个“审批/授权”节点夹在决策和行动之间。比如Agent要执行“删除服务器上的文件”这种高危操作应当经过权限校验或者要人工确认而不是直接放行。我实际踩过坑测试环境里Agent接到一句“帮我把临时目录清掉”结果工具权限配得太宽差点把别的目录也处理了。自那以后所有Agent架构图里工具执行权限一定单独画一层。6. 怎么画一张能真正指导开发的Agent架构图6.1 分层与编号让图可以被讨论我自己画Agent架构图有一个固定套路大致可以分为六个横向分层交互接入层面向用户或外部系统的入口负责接收请求与返回结果控制编排层Agent的核心循环、规划器、调度器决定“下一步做什么”上下文管理层负责组装当前上下文包括Prompt模板、工具描述、短期工作记忆记忆存储层长期记忆、向量检索、缓存、归档工具集成层模型可通过工具能力入口访问外部系统统一工具协议、安全校验、限流降级基础设施层模型网关、日志、链路追踪、监控告警。这样分了层之后评审架构图就变成了逐层评审控制编排层是否形成闭环上下文管理层和记忆存储层之间是否有清晰的读写路径工具集成层是否有鉴权和失败兜底6.2 先用文字描述一条主线再动笔画图我的另一个习惯是动笔画图之前先写一段100字左右的主线文字。比如“用户请求进入交互层经过基础校验上下文管理层将历史摘要与工具说明注入模型控制编排层循环执行规划—调工具—观察结果直到满足终止条件所有工具调用经过工具集成层统一鉴权返回内容经过摘要后回写上下文结束后记忆存储层提炼长期记忆条目。”如果这段文字写得出来架构图就非常容易画了。如果这段文字都写不清楚比如“然后Agent智能地处理”那画出来一定也是一团浆糊。这套方法帮我在好几个模拟项目的初期阶段就推翻了有问题的设计省了大量重构时间。6.3 架构图的版本管理图要和代码一起演进最后一个建议架构图不是一次性交付物它是活文档。我见过太多团队架构图画完之后就再也没更新过三个月后代码已经面目全非架构图还挂着第一版。我的做法是把架构图文件放进代码仓库和代码一起走版本管理每次涉及跨模块流程变更必须同步更新架构图并写一段变更说明。在评审Merge Request时架构图的变更也是审查项之一。这样做的好处不仅仅是文档新鲜更重要的是倒逼开发者在动代码前先想清楚组件之间的关系。架构图是否跟上代码演进其实反映了这个团队对系统设计的敬畏程度。最后再分享一个近期干活时最直接的体会Agent架构图的复杂度和工程质量成正比但和实际落地效果不一定成正比。有些项目架构图画得极美一到线上就崩因为最基础的数据流都没定义清楚反过来有些项目只有一张手绘草图反而跑得极稳因为设计者对每一条路径、每个边界条件都了然于胸。我现在的习惯是无论多小的Agent项目都会在动手写代码之前花几个小时把最小闭环画出来逼着自己把“用户说什么→系统怎么处理→模型怎么规划→工具怎么执行→结果怎么回流→任务怎么结束”这一整条路走通。架构图不是为了给谁看而是给自己画一幅“不能出错的地图”。如果这篇文章能帮你把Agent架构图从“画模块”提升到“画关系、画约束、画边界”就没白写。