画AI智能体架构图这件事看着不难翻车率却很高。前阵子帮一个小团队评审方案对方贴出一张图中间一个“LLM”的大框左边拖进来几个接口右边连着一个数据库就敢叫“AI智能体架构图”。我说这张图有个致命问题——它只回答了“系统用了哪些技术”完全没回答“这个系统到底怎么运转”。真正可用的AI智能体架构图必须能在10秒内让一个不了解项目的人看出三件事Agent的决策逻辑放在哪一层、它调用了哪些模型和工具、数据在各个环节之间怎么流动。这篇文章就围绕这三件事展开先拆解一条Agent系统的组成要素再给出我常用的四层绘制框架接着用一个具体例子走完画图的完整流程最后把看过的各种架构图里的坑整理成一份排查清单。适合正在做Agent开发、需要输出设计方案的人也适合准备做技术汇报、想让评审一眼看懂你系统的人。1. 先把一条Agent系统的组成拆清楚1.1 Agent架构图到底画的是什么我的理解比较朴素架构图是“用图形把系统在结构上怎么搭、在运行上怎么动的逻辑表达清楚”。对普通Web系统画清楚模块划分、接口关系、数据流向就差不多了。但对AI智能体系统这套经验不够用。Agent系统的核心特征是它有一条“感知-决策-行动-反思”的自主闭环。用户抛来一个问题系统要先做意图理解再决定调用哪个模型、要不要检索外部知识、需不需要调用某个工具然后拿到结果还要判断是否满足需求不满足就循环再来一遍。这个闭环是Agent区别于普通接口服务的关键。所以画Agent架构图不能只画模块堆叠必须把“决策循环”“工具调用链”“记忆读写”这几件Agent系统特有的动作显性表达出来。换句话说如果你画的架构图把Agent核心画成一个“LLM”框那这张图的价值就和一个普通的调用链示意图没什么区别。1.2 一套Agent系统的五个核心要素我从多个项目里总结下来无论多复杂的Agent系统拆到最后就是五个要素。交互入口用户怎么触达这个系统是聊天窗口、工单表单、语音指令还是外部API调用。入口层还承担身份鉴权、会话管理、输入预处理。协调编排核心这是Agent的“大脑皮层”。包含规划器、任务分解器、上下文管理器、状态机。它决定“下一步做什么”而不是“这句话什么意思”——后者是模型的事。模型接入层所有LLM相关的东西。包括模型供应商接口、多个模型之间的路由策略、超参配置、流式输出、降级方案。画图时要把“用什么模型”“怎么切换模型”体现出来。工具与能力层模型决定“要做什么”工具负责“真的做到”。包括检索器、计算器、代码解释器、第三方API、内部系统接口。这一层要画清楚工具注册表和权限边界。记忆与存储层短期上下文窗口、长期向量记忆、KV存储、对象存储。很多Agent系统画图时最容易漏掉记忆模块但记忆往往是体验差异最大的地方。传统软件架构图和Agent架构图的差异可以用一张表对比对比项传统服务架构图AI智能体架构图核心角色服务、数据库、网关Agent核心、模型、工具、记忆主要关系接口调用、数据流转决策循环、工具调用、上下文读写关键动作请求-响应规划-执行-反思-重试变量来源流量和数据量模型输出不确定性和工具副作用图的核心价值讲清模块边界和依赖讲清自主决策链路和闭环1.3 为什么很多架构图一眼看就是“死图”看过大量方案图之后我总结了四个高频死因。死因一只画结构不画行为。框和箭头都有但箭头没有语义看不出是同步调用、异步消息还是数据回流。死因二层与层混在一起。UI组件、业务逻辑、模型调用、数据库访问出现在同一层像一碗粥。死因三粒度不一致。有的框代表一个服务有的框代表一个函数看图的人被迫猜。死因四自嗨式命名。“智能处理模块”“AI能力中心”这种名字谁都看不懂边界。这四种问题归根结底是画图前没想清楚。架构图不是画出来的是想出来的。想不透彻工具用得再溜也白搭。2. 画图前先做这三件事别急着打开画图工具我见过太多人拿到需求直接拖框拉线画完一版改十版。正确顺序是先想清楚三件事再动手。2.1 先定边界这张图是画给谁看的同样一套Agent系统给三类人看的画法完全不同。给开发团队看重点画模块职责和接口关系。每个框要能对应到代码里的一个模块或服务每个箭头要能对应到一个接口或事件。这样讨论方案时可以直接指着某个框说“这里的状态转移不清晰”。给业务方或评委看重点画流程闭环和决策逻辑。技术细节要收起来比如“向量检索”可以画成一个“知识库查询”的框“多模型路由”可以画成“模型选择策略”。目的是让不懂技术的人也能顺着箭头看懂系统怎么工作。给自己复盘用想怎么画就怎么画但一定要诚实。很多团队的真实问题恰恰是在“自用图”里暴露出来的——比如画着画着发现某条链路根本走不通。2.2 再定粒度要画到多细粒度就是对“一个框代表什么”的约定。画图前不约定粒度画出来必然混乱。系统级粒度一个框代表一个完整系统或服务适合整体架构汇报。模块级粒度一个框代表一个子系统或核心模块适合方案设计评审。组件级粒度一个框代表一个类、一个函数、一条提示词模板适合详细设计和代码走查。我建议一张架构图只讲一种粒度。如果必须展示不同层级的细节就按C4 model的思路画多张图上下文图、容器图、组件图、代码图分开画。很多人一幅图里把“Agent运行时”和“prompt模板”画在同一个层级你可以试一下观众几乎一定会在提问环节问出同一个问题——“这两个框是一个量级的东西吗”2.3 最后列一份“组件清单”画图之前穷举所有组件。这份清单是画图的原材料也是查漏补缺的检查表。清单里的每一项至少包含组件名称、一句话职责、关键依赖、是否需要画进当前这张图。举个例子一个智能客服工单分类Agent清单可能是这样入口网关接收用户提交的工单解析出标题和正文工单预处理做敏感信息脱敏、文本长度裁剪编排调度器判断是否需要检索历史工单、是否需要调用模型意图识别模型判断工单属于“咨询、投诉、退换货”哪一类知识库检索器从历史工单和知识库里召回相似案例分类决策模型结合检索结果输出分类和置信度工单系统API把分类结果回写业务系统会话缓存存储当前工单的处理状态审计日志记录每一次模型调用和工具调用这份清单列完哪些组件要画、哪些可以合并、哪些依赖关系必须连线基本一目了然。我认识的几个画图高手其实都把大量时间花在这个环节而不是软件操作上。3. 一套我自己常用的四层绘制框架画了几年架构图我习惯把Agent系统拆成四层用户交互层、决策与编排层、模型接入层、工具与数据层。这套分法不算什么新理论但胜在通用和好讲适合作为画图的骨架。3.1 第一层用户交互层这一层画所有用户入口包括Web界面、移动端、命令行、企业微信/钉钉这类IM机器人、开放API。为什么要把入口单独一层因为Agent系统的交互形态比普通系统更复杂。用户可能先发一条消息中途补充一个文件隔天又来追问同一个任务。交互层要处理多轮会话的挂起与恢复还要把“用户的模糊意图”转成“系统能处理的结构化请求”这跟普通HTTP接口的简单转发完全不是一回事。画这一层时我会额外标注两类组件会话管理器负责多轮上下文绑定和输入处理器负责格式校验、敏感词过滤、文件转文本。如果不画这两个交互层就只是一个空壳。3.2 第二层决策与编排层这是整张架构图的心脏。Agent之所以是Agent而不是一个普通模型接口封装全靠这一层。决策与编排层通常包含规划器Planner、任务分解器Task Decomposer、执行器Executor、反思与重试逻辑Reflector、上下文管理器Context Manager。规划器的职责是决定完成目标需要几步、每一步用什么手段。任务分解器把大任务拆成可执行的小步骤。执行器负责调用模型或工具并汇总结果。反思器判断当前结果是否满足原始目标不满足就重新规划形成循环。画这一层时我强烈建议把“决策循环”画成一个显式的环或循环箭头。这个循环是Agent系统的灵魂。如果图上没有一个圈读者大概率会把Agent理解成一个“输入文本-输出文本”的普通模型接口。3.3 第三层模型接入层这一层画所有模型相关的能力。包括模型网关、模型路由、多模型适配、提示词模板管理、流式输出适配、上下文窗口压缩策略、模型降级与熔断。为什么要把模型单独抽一层而不是直接画在编排层旁边因为模型是外部依赖会变的。今天用A模型明天换B模型后天可能同时接三个模型做路由。如果模型和其他组件混画在一起每次换模型就要动架构图非常麻烦。模型路由值得重点标注。我在实际项目里见过两种路由一种是按任务类型路由比如“简单问答走小模型复杂推理走大模型”另一种是按质量兜底路由比如“主模型超时或失败自动切换备选模型”。架构图上画清楚路由策略能把“为什么系统选这个模型”这个问题前置回答很多次。3.4 第四层工具与数据层最后这层画的是Agent的“手脚”和“外脑”。工具包括函数调用工具、代码执行沙箱、搜索API、内部业务系统API、第三方SaaS接口。数据层包括短期会话存储、长期向量库、关系数据库、日志系统。画这一层最容易出现的状况是工具框画了一堆但没画“工具注册表”和“权限边界”。工具注册表是Agent能感知到哪些工具存在的唯一来源权限边界决定了每个工具在什么条件下可以被调用。这两件事不画清楚图里就只有工具的名字没有工具治理的规则。模型输出可能产生副作用比如真实地删除一条数据权限边界是兜底安全机制架构图上应该留出位置即使只是一个小框。4. 一步步把架构图画出来的实操记录理论基础说完了下面用“智能客服工单分类Agent”这个具体例子记录我画图时的完整实操过程。4.1 工具选型我用哪一类画图工具画架构图不需要追新顺手最重要。我按使用场景把工具分成三类在线协作画板适合方案讨论和多人实时编辑拖拽方便缺点是复杂图容易乱。开源绘图工具适合精细化绘制支持图层、模板和版本管理导出SVG效果很好。代码生成方案适合版本管理爱好者用文本描述生成图改起来方便缺点是绘制复杂布局时调整成本高。我的建议是方案讨论用在线协作画板正式文档用开源绘图工具长期维护的架构图尽量考虑代码生成方案因为图跟代码一样需要版本管理。工具不重要能让你愿意反复改的就是好工具。4.2 从中心往外画六个具体步骤第一步画系统边界。先拉一个大框左上角写“智能客服工单分类Agent”这个框就是整张图的边界框外的东西都是外部依赖。第二步画四层泳道。在大框里横向分四个泳道从上到下依次是用户交互层、决策与编排层、模型接入层、工具与数据层。泳道让层级关系一目了然是最省力的分层表达方式。第三步从编排层开始放核心组件。先在“决策与编排层”泳道里放三个框编排调度器、任务分解器、反思与重试控制器。这三个框先画好因为它们定义了整个Agent的主流程。第四步填充周边组件。交互层放“入口网关”“会话管理器”模型层放“模型网关”“多模型路由器”工具层放“知识库检索器”“工单系统API”“审计日志存储”。第五步画连接线。这是最需要耐心的一步。我用三种线条实线箭头表示同步调用虚线箭头表示异步事件或消息粗线箭头表示数据流。用户发来工单入口网关→会话管理器→编排调度器用实心箭头编排调度器→任务分解器用实心箭头任务分解器→模型网关用实心箭头模型网关→多模型路由器→外部模型API用实心箭头检索器从向量库召回数据用粗线箭头因为它代表数据流动而不是调用指令。第六步走查闭环。沿着图走一遍完整请求流用户提交工单→预处理→编排器判断要不要检索→检索器召回→编排器把结果交给模型→模型输出分类→编排器解析结果→调用工单系统API回写→记录日志→返回用户。每一步在图里都能找到对应的框和箭头走不通就说明漏画了。4.3 连接线与图例的规范做法连接线是架构图里最容易失控的部分我见过一张图上五种箭头六种颜色谁也看不懂。我现在的规则很简单实线箭头同步调用/请求-响应虚线箭头异步消息/事件通知双线或粗线大批量数据流动回环曲线决策循环/反思重试颜色不要超过四种。我常用蓝色表示模型相关调用绿色表示工具/API调用灰色表示数据读写橙色表示异常或重试路径。颜色一旦超过四种看图成本直线上升。图片角落必须画图例。这句话我重复无数遍也不嫌多。图例不是摆设是对线的语义的定义。没有图例的架构图就像没有变量名的代码作者自己三天后都未必看懂。5. 不同场景下的三种架构图变体同一个Agent系统在不同场合需要不同的图。不要试图用一张图打天下。5.1 概念架构图给业务方和评审看概念架构图的特点是大逻辑清晰、技术细节隐去、信息量少。它只回答三个问题系统有哪些主要模块、用户的输入从哪进、结果从哪出、中间经过哪些关键环节。拿工单分类Agent举例概念架构图只需要画用户→智能客服平台→工单分类Agent里面画三个子框意图识别、知识检索、分类决策→工单系统。不需要画具体的模型网关、多模型路由器、会话缓存。这张图的使命是让业务方在30秒内认可你的产品逻辑而不是秀技术肌肉。5.2 部署架构图给运维和工程落地看部署架构图回答的是每个组件跑在哪台机器/容器/进程上网络边界在哪里什么调用是内网的什么调用要过公网或专线。部署架构图要在逻辑架构上叠加部署信息。比如入口网关跑在K8s集群边缘节点Agent编排服务跑在业务容器组模型网关对外访问LLM供应商API需要走代理向量库单独部署只允许内网访问。这些信息在逻辑架构图上出现会很噪杂在部署图上出现则刚刚好。5.3 时序协作图给代码落地和排障看架构图画的是“空间的静态结构”时序图画的是“时间上的动态协作”。当架构图画完、评审通过、进入编码阶段后最常用的其实是时序协作图。时序图用横向泳道表示角色用纵向箭头表示消息顺序。画一次完整请求的链路用户→入口网关→编排器→检索器→模型网关→外部模型→编排器→工单API→审计日志。每一步标上输入/输出的核心内容写代码时照着这个图填实现就可以。排查问题时也是先在时序图上定位“哪一步没走通”再去翻日志。三种变体如何选择我整理成一张判断表场景推荐图型信息重点受众方案立项汇报概念架构图闭环流程、核心价值业务方、评审组详细设计评审四层架构图模块职责、交互关系、边界开发团队、架构师部署上线部署架构图节点、网络、进程、依赖运维、工程负责人编码阶段时序协作图消息顺序、输入输出开发同学6. 绘制过程中的常见问题与排查技巧画图次数多了遇到的坑也趋同。我把高频问题整理成了一个速查表每一条都是我实际踩过或帮别人排查过的。常见问题根本原因解决方式图里全是框和线但看不懂逻辑只有结构没有行为箭头没语义给所有连线定义类型加图例走查一条完整请求流分层混乱UI和数据库画在一排没有先规划抽象层级用泳道强制分层一层一个泳道一个框代表服务一个框代表函数粒度没有提前约定画图前列组件清单标注每个组件的粒度完全没有Agent特征把Agent画成了普通CRUD架构显式画出决策循环、记忆读写、工具调用链一张图塞了所有信息想一张图解决所有问题拆分概念图、架构图、部署图、时序图图例缺失改两版后看不懂自己画的图没有维护图例和命名规范图例写进图面命名统一用“动词名词”模型框画了一个但系统实际接了三个模型抽象层级不够模型层没有单独画补模型网关和多模型路由把模型抽象成资源而不是组件还有一个值得单独说的经验画图要接受“丑图先行”。我从不追求一次画对第一版通常又乱又难看但线条乱没关系逻辑对了就行。先让所有组件和连接都出现在画布上再一步步对齐、分组、删冗余。如果你一边画一边纠结对齐和配色思路很容易被视觉细节打断。另外建议给架构图做版本管理。方案阶段的V1、评审修改后的V2、落地后的V3放在同一个目录下方便回溯。架构图的演化历史就是系统设计的演化历史这个价值常常被低估。7. 最后分享两个小习惯画了这么多年的架构图我最大的体会是一张好的Agent架构图本质上是把对系统设计的理解压缩成一张可以随时被解码的图。画图的过程不是“把想好的东西画出来”而是“在画的过程中把系统想清楚”。很多人在画到决策循环那一层时才意识到自己还没有想清楚Agent卡住时应该重试还是直接交还用户——这种发现本身就是画架构图最大的价值。最后分享两个小习惯我一直觉得非常管用。第一个习惯是画完图后找一个人讲一遍讲不通的地方就是图需要改的地方。第二个习惯是每次新画架构图之前先去翻一遍旧图看看当时画下的依赖和边界现在是否还成立。架构图不是交付物是思考的脚手架只要还在改动它就还活着。