这两年只要打开任何技术社区满屏都是AI Agent可你真要让人去画一张Agent的架构图大部分人只能画朵云中间写个大模型。我自己最早也是这么干的结果项目一上真实场景就翻车。后来我反复拆解了几轮主流Agent技术架构再结合自己做过的几个完整项目总算把智能体到底由哪些部件组成、这些部件之间怎么协作这件事捋顺了。这篇文章不做概念科普只做架构拆解把一张有代表性的Agent技术架构图从上到下剥开每一层的职责、数据流向、选型依据、踩坑点都会说到适合已经开始写Agent但整体设计还比较模糊的开发者。1. Agent为什么是现在这个形态从自动化脚本到大模型决策体很多人把AI Agent理解成ChatGPT加个工具这个理解最多对了一半。Agent之所以叫Agent核心在于它具备目标导向的自主行为而不仅仅是对话。想看懂架构图先得搞明白它为什么演化成今天这个结构。1.1 传统自动化和智能体的分水岭传统的RPA或者规则脚本本质上是把人的操作流程固化下来遇到符合预期的输入就执行遇到预期外的输入就崩。它的决策逻辑写在if-else里每加一种新情况就要加一条分支。Agent的逻辑不是这样决策不再由人写死而是由大模型根据当前目标、历史记忆、工具返回结果实时生成。我用一个很实在的类比来解释传统自动化是一台自动售货机你按某个按钮它掉某样商品按钮和商品的关系是出厂定死的Agent更像一个店员你告诉他要给客户准备一份带预算表的PPT他自己琢磨该怎么拆步骤、该打开哪个工具、做完之后再检查一遍是否符合要求。这里的关键变化是决策权从代码转移到了模型推理上。代码只负责提供工具、管好状态和权限至于下一步做什么由模型按当时的上下文来推理。就是这个变化让Agent能应对开放式的、不可预判的任务也让Agent架构多出了大量过去自动化系统没有的组件。1.2 从LLM直接输出到感知-决策-行动闭环最早的LLM应用只是对话机器模型读入用户的输入生成一段文本回答。问题在于回答不需要接受现实检验编错了也不知道。Agent把这个问题补上了架构上就多出了三个环节感知接收任务相关的输入信息包括用户指令、环境状态、工具返回结果、外部数据源内容。决策基于当前目标、已有记忆、工具能力列表推理出下一步动作可能是调用工具也可能是产出最终答案。行动把决策转化为真实动作执行工具调用、改写状态、触发外部流程并把执行结果反馈回感知层。这三者形成一个持续循环直到任务完成或达到终止条件。这张循环图其实就是Agent架构里最底层的主干数据流后面讲的所有组件都是挂在这条闭环上的插件。1.3 架构图上必须先画出环境这一环我发现新手最容易省略的部分是架构图外面的环境边界。Agent不是悬空运行的它一定存在于某个具体环境里要么是用户可以对话的界面要么是能操作API的外部系统要么是一堆文件和工具的沙盒环境。环境的作用是提供执行上下文和反馈信号。Agent在环境中执行某个工具环境会返回结果结果又会影响Agent下一轮的判断。如果你在架构图里没有把环境和边界画出来很容易犯一个错误把Agent当成输入文本、输出文本的单向漏斗而忽略了它实际是一个与环境反复交互的回路。我在画自己的Agent参考架构时第一笔永远是画环境边界左边是用户右边是外部工具和数据源下面是执行沙盒。边界画清楚了后面设计记忆放哪、工具权限管到哪、日志在哪采集才不会糊在一起。2. 大脑的中枢设计规划、推理、决策循环怎么搭Agent的大脑是架构图正中间那块也是最容易失控的部分。现在的Agent大脑并不是单一模型调用而是一组决策机制组合出来的闭环推理、规划、执行、反思四个动作交替出现。2.1 ReAct循环是当前Agent决策的主干线ReAct模式解决的核心问题是让模型把思考和行动交替起来而不是一次生成最终回答。它的循环是这样跑的模型根据当前任务和已有的观察结果产出一条推理思路Reasoning解释现在需要解决什么问题。模型判断需要获取哪些外部信息或执行什么操作输出一个工具调用请求Act。框架执行工具把结果作为观察Observation返回给模型。模型基于新观察继续推理或者决定任务完成输出最终回答。循环的价值在于每一步行动都是可观测、可追溯的模型不需要一次性生成完美答案它可以在环境中试探、获得反馈、纠正方向。这非常像人类解决复杂问题的过程先查资料、再动手、再根据结果调整。2.2 规划器与执行器的职责分离任务一复杂只靠单次ReAct循环是不够的模型很容易在长链路里忘记初始目标或者被中间结果带偏。业界比较成熟的解法是把规划和执行拆成两个模块。规划器的职责是拆解任务把用户的目标拆成一棵子任务树每个子任务包含目标、需要的输入、期望输出、依赖关系。执行器的职责是落实子任务针对每个子任务选择合适的工具、解析参数、处理返回结果。两者之间通过一个任务列表来同步进度。这个拆分带来几个实打实的好处一是可以控制上下文长度规划器不需要把每个工具的详细返回都灌进模型只需要读取执行器提交的精简结果二是可以局部重试子任务失败时不用整个任务从头再来三是职责清晰之后每个模块的Prompt可以单独调优不会互相干扰。2.3 反思机制让Agent拥有回头检查的能力只靠规划-执行还不能解决低级错误问题模型经常自信地给出一个错误答案自己还发现不了。反思机制就是在这里加一道阀门。我现在搭架构时执行完一轮结果之后会加一个独立的评估环节用一个Critic角色去审视执行结果是否满足原始目标检查维度包括有没有偏离任务主目标、有没有遗漏必要条件、工具返回的数据有没有被错误解读。如果评估不通过就把问题描述和当前结果一起送回推理循环让Agent重新规划或重试。这个机制的本质是给Agent增加一条负反馈回路。没有反思机制的Agent行为像开环控制输出错了也没人纠正加了反思之后系统会在内部先把关能明显降低低质量的最终输出。代价是会增加模型调用次数和延迟所以反思也不能无限制跑我会给反思设置上限次数比如最多两轮避免陷入无限循环。3. 记忆系统不是伪需求短期、长期与工作记忆的分层设计架构图里与大脑并列的另一个核心板块是记忆。做Agent项目之前我觉得记忆没什么大不了就是把对话历史拼在一起塞进Prompt真正做之后才知道记忆的结构直接决定Agent能接住多复杂的任务。3.1 三层记忆各自管什么Agent的记忆可以拆成三层对应不同生命周期和作用方式短期记忆当前会话内正在处理的信息基本就是模型上下文窗口里的内容包括用户最近说的话、最近几次工具调用和观察结果。它的特点是存取快但容量小且不会保留到下一次会话。工作记忆任务执行过程中产生的中间状态比如子任务进度、临时变量、当前方案的候选清单。它存在于某次任务执行期间任务结束就丢弃。工作记忆通常用结构化对象维护不一定全部塞进模型上下文。长期记忆跨会话保留下来的事实和偏好比如用户的业务背景、历史项目的关键结论、常用工具的使用经验。长期记忆一般落在外部存储里需要时按相关性取回。三层记忆体系的组合本质上是在信息保留的全面性和模型上下文的有限性之间做平衡。如果所有信息都无条件堆进Prompt上下文很快就会爆炸如果完全不保留Agent对业务上下文的理解就会非常浅。3.2 记忆的写入与取回才是真正考验功力记忆系统的实现一脚深一脚浅——不是怎么存的问题而是该记什么和怎么取出来的问题。写入侧我不建议把Agent每步执行的原始日志都丢进长期记忆那只会成为检索噪声。比较可靠的做法是增加一层记忆提炼从一段对话或执行过程中抽取出关键实体、结论、待办事项做一次摘要压缩再决定是否值得写入。值得写的内容通常有三个特征与用户目标相关、有跨会话复用价值、内容短小且表达明确。取回侧核心是语义检索加相关性过滤。先把历史记忆文本做嵌入向量化用户每次发起新任务时把当前目标也转成向量用相似度检索出最相关的记忆片段。但向量检索的初筛结果往往带噪声我会再加一道重排或规则过滤把记忆范围收窄到真正能指导当前决策的内容避免无关记忆污染模型判断。3.3 记忆系统最常见的败笔踩过的坑里最典型的是把一整份超长文档直接塞进上下文当记忆。模型能读完和能读好是两回事长文档塞进去之后关键信息被淹没模型反而用里面的次要信息做出错误判断。另外一个常见败笔是取回太多太杂。把检索top-k设成20、30结果取回来的内容五花八门模型为了兼顾所有片段生成的回答反而变得空泛。我的做法是控制初始取回量比如top-k取5到8条让重排模型做第二轮筛选宁可少取不要错取。然后还要考虑遗忘不是所有记忆都永远有用我会给长期记忆做时间衰减超过一定时间且没有被访问过的条目权重降低或进入归档避免系统越跑越慢、越跑越偏。4. 工具调用的工程化Agent的手和脚没有工具调用的Agent只是高级聊天机器人。工具模块在架构图里承担的是手和脚的功能但实现起来比看起来复杂得多因为涉及到模型输出解析、参数校验、权限管理和执行反馈等一堆工程问题。4.1 Function Calling的真正逻辑第一步要理解模型怎么使用工具。现在的主流大模型基本支持函数调用能力开发者把工具的名称、功能描述、参数结构通过结构化Schema告诉模型模型在回答时如果认为需要用到某个工具会返回一段包含函数名和参数值的结构化JSON框架拿到这段JSON后去真实环境里执行对应函数把执行结果再喂回模型。理解这个链路很关键模型其实没有能力直接操作外部系统它只是生成了一段我要调用某工具、带上这些参数的文本真正执行的是框架代码。所以架构上必须有一个调用解析层负责把模型输出转成实际函数调用同时做容错。如果模型返回的JSON格式不规范要能修复如果参数缺了关键字段要能补全或者返回给模型让它重新生成。4.2 工具描述写不好Agent就变成幻觉生成器工具调用能不能成功很大程度上不取决于模型本身而取决于你怎么描述工具。描述写得含糊模型就猜比如一个工具叫query_data描述是查询数据模型完全不知道什么场景该用它、参数怎么填这时候幻觉就来了。我在实际项目里总结了一套工具描述规则名称要直白按动词加名词组织比如search_sales_by_city不要叫什么get_info。描述里写清楚什么场景用、什么时候不用明确边界比罗列参数更重要。每个参数的说明要包含格式、取值范围、是否必填、典型示例。必要时配置工具的反面约束也就是明确告诉模型如果条件不符合不要调用它直接说无法完成。工具描述本质上是给模型的操作说明书说明书质量越高模型按正确姿势调用工具的概率就越高幻觉风险就越低。4.3 执行安全与权限控制给Agent一把好刀也装好刀鞘让Agent去操作数据库、发邮件、调支付接口听起来效率很高但一旦判断失误后果也比聊天跑题严重得多。我负责的Agent架构里工具执行层永远是夹在中间的一道闸门。执行层至少要管三件事权限校验确认当前任务是否有权调用这个工具校验可以基于用户角色、任务类型、Agent自身权限级别参数校验工具执行前在代码层判断参数是否合法不合法直接拦截人工放行高风险的写操作、删除操作、对外发送操作设计成需要用户确认后才真正执行。这一步是架构设计里最容易省的地方因为省掉它看起来Agent跑得更顺畅但真出了问题再补就晚了。尤其是涉及外部动作的工具宁可多一次人工确认也不要让Agent在无人监督的情况下做不可逆操作。5. 多Agent协作架构从单兵作战到团队配合单Agent做到一定程度一定会遇到两个天花板上下文有限脑子塞不下太多中间状态职责过杂模型在目标理解、工具选择、结果质检等不同角色之间切换容易互相干扰。这时很多人会转向多Agent协作事实上多Agent架构不是银弹它是一套需要精心设计的分布式协作系统。5.1 多Agent到底解决了什么问题多Agent架构的核心收益不是让多个大模型一起思考而是把复杂的任务目标拆给多个专职Agent让每个Agent负责自己最擅长的一段。各Agent的上下文可以保持相对精简每个Agent的Prompt和工具列表也更好针对性调优。举个例子一个内容生产系统里我可以让一个Agent专门做资料搜集它的工具列表里只有搜索类工具另一个Agent专做写作它拿到归纳好的资料和大纲专注生成内容第三个Agent专做校对用不同的角色设定去检查事实和逻辑漏洞。比让一个Agent既搜索又写作又检查整个流程的质量和可控性都有明显提升。5.2 三种主流协作模式与选型依据多Agent的协作拓扑有很多种我实际用下来最常见的是三种协作模式结构特征适合场景主要代价主从模式主Agent拆解任务后分发给多个子Agent统一收集结果任务颗粒度明确、可并行处理主Agent容易成为瓶颈协商模式多个Agent各提出方案互相评审和反驳最后汇总高难度决策、需要多角度验证调用数量大延迟高流水线模式前一个Agent的输出成为后一个Agent的输入逐级加工流程固定、顺序依赖强的任务单环节出错会向后传导选型的依据不是哪个技术更高级而是任务本身的依赖结构。任务能拆成独立子任务优先用主从模式并行处理任务需要多轮权衡判断考虑协商模式任务本来就是固定流程流水线模式最节省token。5.3 我对多Agent的真实看法先单后多如果让我给刚接触Agent的人一个直接建议我会说不要一开始就设计多Agent。很多场景下一个Agent加上精心设计的工具链、可靠的记忆系统、反思机制已经能解决大部分问题。多Agent带来的通信开销、状态一致性问题、上下文传递损耗都是要在项目里实际付钱的。我自己是在单Agent架构跑通、明确碰到单一上下文和角色冲突的瓶颈之后才逐步把部分能力拆成独立Agent。拆的粒度也不是越多越好而是什么时候单Agent明显扛不住什么时候才拆。这个原则帮我少走了很多弯路。6. 把架构图落到纸上一套可复用的Agent参考架构现在把前面的讨论汇总成一张完整的参考架构图。这张图不是从某个现成产品抄来的而是我把多次项目实践抽象之后沉淀出来的通用形态你可以把它作为自己项目设计的起点。用户 / 环境 │ ▼ ┌──────────────────────────────────────────────┐ │ 入口编排层 │ │ 意图识别 / 任务启动 / 会话与上下文管理 │ └──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────┐ │ 决策中枢 │ │ 规划器(目标拆解) 执行器(子任务执行) │ │ ReAct循环 反思评估模块 │ └──────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ 记忆系统 │ │ 工具调用 │ │ 安全与权限 │ │ 短期/长期│ │ 函数解析/ │ │ 授权校验/参数 │ │ 工作记忆 │ │ 执行封装 │ │ 检查/人工复核 │ └─────────┘ └──────────┘ └──────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────┐ │ 观察链路 │ │ 日志采集 / Trace追踪 / 执行结果反馈 │ └──────────────────────────────────────────────┘ │ ▼ 用户 / 外部工具 / 数据库 / 业务API6.1 逐层拆解这张架构图从下往上看。最底层是观察链路也是Agent的回音壁所有工具执行结果、运行日志、token消耗、延迟都要在这里汇总。它不是可选项而是你排障时的眼睛。没有这一层的Agent出了错只能黑盒猜非常折磨人。上一层是安全与权限模块它横插在决策中枢和工具之间。这层必须独立出来不能在业务代码里随手写几行校验就完事。涉及敏感操作时它要能拦住执行流转人工确认。工具调用层承接决策中枢发来的工具请求做函数解析、参数修复、真实执行。它返回的结果需要经标准化处理不仅是原始数据还要带上执行状态、耗时、错误码、截断摘要这样决策中枢不需要读取全部原始数据就能继续推理。记忆系统在架构图里和工具调用平行它同时服务决策中枢的规划与反思。决策中枢在开始任务前先从长期记忆取回相关背景在任务中把中间状态写入工作记忆任务结束后提炼值得沉淀的信息写入长期记忆。再往上是决策中枢包括规划器、执行器、ReAct循环和反思模块。它接收入口编排层传来的用户目标结合记忆和工具能力循环执行推理-行动-观察-反思直到产出结果。最上面是入口编排层。它负责识别用户意图、决定启动哪类Agent、维护会话上下文。这一层要处理的脏活比你想象得多用户输入要不要被格式化、任务被复制时深拷贝还是引用、多个并发任务的上下文怎么隔离。在许多项目里入口编排层的代码量甚至超过决策中枢。6.2 关键配置项与选型依据参考架构落地时核心配置项选择我给出一个基础清单配置项推荐基础值选择的理由模型温度0.1到0.3工具调用和结构化输出需要低随机性太高会编造参数记忆向量维度取决于嵌入模型输出匹配嵌入模型即可不需要昂贵的高维向量库记忆取回top-k5到8太少可能漏关键信息太多会引入噪声工具调用超时10到30秒根据工具响应特性设定避免卡死整个循环反思最大轮数2到3轮防止反思机制陷入无限自我修正会话上下文窗口控制在实际模型窗口的50%以内剩余窗口要留给工具返回结果和下次输入有一个原则不要把模型的上下文窗口当作无限内存。我实际开发时通常会把内部估算的上下文用量控制在模型窗口的50%以内剩下的一半预留给工具结果、系统指令、反思维度。超过这个水位就要想办法压缩历史内容或提前归档。6.3 数据流一帧帧走一遍架构图是静态的数据流是动态的。我举个例子假设用户提交了一个任务整理这个季度的销售数据并生成一份包含结论的摘要。第一帧入口编排层接收输入做意图识别判断这是一个数据查询加分析任务于是启动对应的Agent流程并读取该用户的长期记忆中关于数据源、报表偏好的历史记录。第二帧决策中枢的规划器收到目标和记忆背景拆出三个子任务定位销售数据表结构、按季度维度聚合数据、对结果做结论提炼。第三帧执行器开始执行第一个子任务调用工具调用层去检索数据源的元数据。工具真实返回了表名和字段说明观察链路把结果压缩成一段简短描述送回执行器。第四帧执行器根据字段说明发起聚合查询。返回的数据量比较大在送入模型之前做了一次摘要和截断只保留季度汇总、环比、异常标记等关键字段。模型基于这些信息生成数据分析并围绕结论写出摘要。第五帧反思模块对输出做一轮质检发现结论里提到了环比增长但原始数据并没有给出去年同期的参照值于是判定存在推理不严谨把问题反馈回决策中枢。第六帧执行器重新调用工具补充查询去年同期的数据模型修正结论后再次生成摘要。反思模块通过质检结果交给入口编排层返回给用户。这一整套流程走下来每一步都有明确归属出了问题能迅速定位到具体模块。我觉得这就是画架构图的意义不是画给别人看而是让系统中的每个环节都有清晰的责任边界出了问题你能快速找到是谁的锅。7. 实操中的坑与我的调试心得就算架构图画得再完整Agent落地的过程还是会有一堆烂事。我把自己踩过的几次比较典型的坑写出来希望能帮你省几个晚上的调试时间。7.1 翻车现场一上下文污染第一次做Agent工具调用时我让Agent去查一个交易系统的用户列表工具返回了一千多条记录。我原本只想要一个统计信息结果把全部记录原样塞进上下文模型看着看着就开始分析某条具体记录的特点完全偏离了原始的分析任务。后来我总结出的规矩是工具返回结果必须经过压缩层再进模型。压缩层的职责是把大段数据转成摘要、统计量、分级信息只有在模型明确需要一个具体条目时才允许它发起二次查询取明细。这个改动之后Agent跑偏的概率明显下降。7.2 翻车现场二工具幻觉模型有时会凭空捏造一个不存在的工具或者给某个真实工具填上完全不存在的参数名。第一次遇到时我以为是模型版本太旧后来排查发现是我某个工具的参数描述写得太模糊模型理解不了怎么用就开始自己猜测。修复分两步一是把同类模糊的参数说明全部重写补上取值范围、格式、示例二是在工具调用层加兜底校验发现参数不在定义范围内时不直接报错而是带着错误信息返回给模型让它自己修正。加了这个闭环之后工具幻觉问题大幅缓解。7.3 翻车现场三递归循环反思机制加多了也会出事。一次调优时我把反思触发条件设得过于严格Agent执行完一轮之后发现自己还有一点点不完美就重新规划、重新执行结果是彻底停不下来了直到token耗尽才被强制终止。这个问题其实是对反思机制的约束不到位。后来我加了两重限制一是反思的最大轮数硬编码超过立即终止并把当前最优结果输出二是反思只针对关键偏差可以定义一些评分规则只在这里卡壳时触发重试不因为轻微措辞问题反复循环。7.4 让Agent变成可控系统的调试三板斧我现在的Agent项目调试方法基本固定为三板斧结构化日志、Trace追踪、Mock工具。结构化日志不是简单print每个关键环节都要输出包含任务ID、环节、模型调用次数、工具名、执行耗时、token消耗的JSON日志这样能按任务还原完整路径。Trace追踪比日志更细一个层次每一步模型输入输出、每一步工具入参出参都能回放排查模型在这个节点为什么做这个选择非常有用。Mock工具更简单——在本地开发时把外部API全部替换成返回预制结果的假实现这样能脱离外部系统限制专注调试决策逻辑本身。另外一定要维护一套最小复现样本集。每次线上出现奇怪行为我会把输入和对应轨迹存下来回归测试时反复跑。Agent项目调的不是某一个函数而是整套决策逻辑没有样本集做回归你每次改Prompt都像在蒙着眼睛调音。根据我个人的经验最开始写Agent代码之前先花几个小时把架构图认真画一遍把每个模块的输入、输出、边界、异常路径都标清楚后面整个开发周期都会顺很多。架构图的每一处修改往往都对应一次深夜排障的教训。它不只是一张图而是你和这个复杂系统之间达成的共识契约。
这两年只要打开任何技术社区满屏都是AI Agent可你真要让人去画一张Agent的架构图大部分人只能画朵云中间写个大模型。我自己最早也是这么干的结果项目一上真实场景就翻车。后来我反复拆解了几轮主流Agent技术架构再结合自己做过的几个完整项目总算把智能体到底由哪些部件组成、这些部件之间怎么协作这件事捋顺了。这篇文章不做概念科普只做架构拆解把一张有代表性的Agent技术架构图从上到下剥开每一层的职责、数据流向、选型依据、踩坑点都会说到适合已经开始写Agent但整体设计还比较模糊的开发者。1. Agent为什么是现在这个形态从自动化脚本到大模型决策体很多人把AI Agent理解成ChatGPT加个工具这个理解最多对了一半。Agent之所以叫Agent核心在于它具备目标导向的自主行为而不仅仅是对话。想看懂架构图先得搞明白它为什么演化成今天这个结构。1.1 传统自动化和智能体的分水岭传统的RPA或者规则脚本本质上是把人的操作流程固化下来遇到符合预期的输入就执行遇到预期外的输入就崩。它的决策逻辑写在if-else里每加一种新情况就要加一条分支。Agent的逻辑不是这样决策不再由人写死而是由大模型根据当前目标、历史记忆、工具返回结果实时生成。我用一个很实在的类比来解释传统自动化是一台自动售货机你按某个按钮它掉某样商品按钮和商品的关系是出厂定死的Agent更像一个店员你告诉他要给客户准备一份带预算表的PPT他自己琢磨该怎么拆步骤、该打开哪个工具、做完之后再检查一遍是否符合要求。这里的关键变化是决策权从代码转移到了模型推理上。代码只负责提供工具、管好状态和权限至于下一步做什么由模型按当时的上下文来推理。就是这个变化让Agent能应对开放式的、不可预判的任务也让Agent架构多出了大量过去自动化系统没有的组件。1.2 从LLM直接输出到感知-决策-行动闭环最早的LLM应用只是对话机器模型读入用户的输入生成一段文本回答。问题在于回答不需要接受现实检验编错了也不知道。Agent把这个问题补上了架构上就多出了三个环节感知接收任务相关的输入信息包括用户指令、环境状态、工具返回结果、外部数据源内容。决策基于当前目标、已有记忆、工具能力列表推理出下一步动作可能是调用工具也可能是产出最终答案。行动把决策转化为真实动作执行工具调用、改写状态、触发外部流程并把执行结果反馈回感知层。这三者形成一个持续循环直到任务完成或达到终止条件。这张循环图其实就是Agent架构里最底层的主干数据流后面讲的所有组件都是挂在这条闭环上的插件。1.3 架构图上必须先画出环境这一环我发现新手最容易省略的部分是架构图外面的环境边界。Agent不是悬空运行的它一定存在于某个具体环境里要么是用户可以对话的界面要么是能操作API的外部系统要么是一堆文件和工具的沙盒环境。环境的作用是提供执行上下文和反馈信号。Agent在环境中执行某个工具环境会返回结果结果又会影响Agent下一轮的判断。如果你在架构图里没有把环境和边界画出来很容易犯一个错误把Agent当成输入文本、输出文本的单向漏斗而忽略了它实际是一个与环境反复交互的回路。我在画自己的Agent参考架构时第一笔永远是画环境边界左边是用户右边是外部工具和数据源下面是执行沙盒。边界画清楚了后面设计记忆放哪、工具权限管到哪、日志在哪采集才不会糊在一起。2. 大脑的中枢设计规划、推理、决策循环怎么搭Agent的大脑是架构图正中间那块也是最容易失控的部分。现在的Agent大脑并不是单一模型调用而是一组决策机制组合出来的闭环推理、规划、执行、反思四个动作交替出现。2.1 ReAct循环是当前Agent决策的主干线ReAct模式解决的核心问题是让模型把思考和行动交替起来而不是一次生成最终回答。它的循环是这样跑的模型根据当前任务和已有的观察结果产出一条推理思路Reasoning解释现在需要解决什么问题。模型判断需要获取哪些外部信息或执行什么操作输出一个工具调用请求Act。框架执行工具把结果作为观察Observation返回给模型。模型基于新观察继续推理或者决定任务完成输出最终回答。循环的价值在于每一步行动都是可观测、可追溯的模型不需要一次性生成完美答案它可以在环境中试探、获得反馈、纠正方向。这非常像人类解决复杂问题的过程先查资料、再动手、再根据结果调整。2.2 规划器与执行器的职责分离任务一复杂只靠单次ReAct循环是不够的模型很容易在长链路里忘记初始目标或者被中间结果带偏。业界比较成熟的解法是把规划和执行拆成两个模块。规划器的职责是拆解任务把用户的目标拆成一棵子任务树每个子任务包含目标、需要的输入、期望输出、依赖关系。执行器的职责是落实子任务针对每个子任务选择合适的工具、解析参数、处理返回结果。两者之间通过一个任务列表来同步进度。这个拆分带来几个实打实的好处一是可以控制上下文长度规划器不需要把每个工具的详细返回都灌进模型只需要读取执行器提交的精简结果二是可以局部重试子任务失败时不用整个任务从头再来三是职责清晰之后每个模块的Prompt可以单独调优不会互相干扰。2.3 反思机制让Agent拥有回头检查的能力只靠规划-执行还不能解决低级错误问题模型经常自信地给出一个错误答案自己还发现不了。反思机制就是在这里加一道阀门。我现在搭架构时执行完一轮结果之后会加一个独立的评估环节用一个Critic角色去审视执行结果是否满足原始目标检查维度包括有没有偏离任务主目标、有没有遗漏必要条件、工具返回的数据有没有被错误解读。如果评估不通过就把问题描述和当前结果一起送回推理循环让Agent重新规划或重试。这个机制的本质是给Agent增加一条负反馈回路。没有反思机制的Agent行为像开环控制输出错了也没人纠正加了反思之后系统会在内部先把关能明显降低低质量的最终输出。代价是会增加模型调用次数和延迟所以反思也不能无限制跑我会给反思设置上限次数比如最多两轮避免陷入无限循环。3. 记忆系统不是伪需求短期、长期与工作记忆的分层设计架构图里与大脑并列的另一个核心板块是记忆。做Agent项目之前我觉得记忆没什么大不了就是把对话历史拼在一起塞进Prompt真正做之后才知道记忆的结构直接决定Agent能接住多复杂的任务。3.1 三层记忆各自管什么Agent的记忆可以拆成三层对应不同生命周期和作用方式短期记忆当前会话内正在处理的信息基本就是模型上下文窗口里的内容包括用户最近说的话、最近几次工具调用和观察结果。它的特点是存取快但容量小且不会保留到下一次会话。工作记忆任务执行过程中产生的中间状态比如子任务进度、临时变量、当前方案的候选清单。它存在于某次任务执行期间任务结束就丢弃。工作记忆通常用结构化对象维护不一定全部塞进模型上下文。长期记忆跨会话保留下来的事实和偏好比如用户的业务背景、历史项目的关键结论、常用工具的使用经验。长期记忆一般落在外部存储里需要时按相关性取回。三层记忆体系的组合本质上是在信息保留的全面性和模型上下文的有限性之间做平衡。如果所有信息都无条件堆进Prompt上下文很快就会爆炸如果完全不保留Agent对业务上下文的理解就会非常浅。3.2 记忆的写入与取回才是真正考验功力记忆系统的实现一脚深一脚浅——不是怎么存的问题而是该记什么和怎么取出来的问题。写入侧我不建议把Agent每步执行的原始日志都丢进长期记忆那只会成为检索噪声。比较可靠的做法是增加一层记忆提炼从一段对话或执行过程中抽取出关键实体、结论、待办事项做一次摘要压缩再决定是否值得写入。值得写的内容通常有三个特征与用户目标相关、有跨会话复用价值、内容短小且表达明确。取回侧核心是语义检索加相关性过滤。先把历史记忆文本做嵌入向量化用户每次发起新任务时把当前目标也转成向量用相似度检索出最相关的记忆片段。但向量检索的初筛结果往往带噪声我会再加一道重排或规则过滤把记忆范围收窄到真正能指导当前决策的内容避免无关记忆污染模型判断。3.3 记忆系统最常见的败笔踩过的坑里最典型的是把一整份超长文档直接塞进上下文当记忆。模型能读完和能读好是两回事长文档塞进去之后关键信息被淹没模型反而用里面的次要信息做出错误判断。另外一个常见败笔是取回太多太杂。把检索top-k设成20、30结果取回来的内容五花八门模型为了兼顾所有片段生成的回答反而变得空泛。我的做法是控制初始取回量比如top-k取5到8条让重排模型做第二轮筛选宁可少取不要错取。然后还要考虑遗忘不是所有记忆都永远有用我会给长期记忆做时间衰减超过一定时间且没有被访问过的条目权重降低或进入归档避免系统越跑越慢、越跑越偏。4. 工具调用的工程化Agent的手和脚没有工具调用的Agent只是高级聊天机器人。工具模块在架构图里承担的是手和脚的功能但实现起来比看起来复杂得多因为涉及到模型输出解析、参数校验、权限管理和执行反馈等一堆工程问题。4.1 Function Calling的真正逻辑第一步要理解模型怎么使用工具。现在的主流大模型基本支持函数调用能力开发者把工具的名称、功能描述、参数结构通过结构化Schema告诉模型模型在回答时如果认为需要用到某个工具会返回一段包含函数名和参数值的结构化JSON框架拿到这段JSON后去真实环境里执行对应函数把执行结果再喂回模型。理解这个链路很关键模型其实没有能力直接操作外部系统它只是生成了一段我要调用某工具、带上这些参数的文本真正执行的是框架代码。所以架构上必须有一个调用解析层负责把模型输出转成实际函数调用同时做容错。如果模型返回的JSON格式不规范要能修复如果参数缺了关键字段要能补全或者返回给模型让它重新生成。4.2 工具描述写不好Agent就变成幻觉生成器工具调用能不能成功很大程度上不取决于模型本身而取决于你怎么描述工具。描述写得含糊模型就猜比如一个工具叫query_data描述是查询数据模型完全不知道什么场景该用它、参数怎么填这时候幻觉就来了。我在实际项目里总结了一套工具描述规则名称要直白按动词加名词组织比如search_sales_by_city不要叫什么get_info。描述里写清楚什么场景用、什么时候不用明确边界比罗列参数更重要。每个参数的说明要包含格式、取值范围、是否必填、典型示例。必要时配置工具的反面约束也就是明确告诉模型如果条件不符合不要调用它直接说无法完成。工具描述本质上是给模型的操作说明书说明书质量越高模型按正确姿势调用工具的概率就越高幻觉风险就越低。4.3 执行安全与权限控制给Agent一把好刀也装好刀鞘让Agent去操作数据库、发邮件、调支付接口听起来效率很高但一旦判断失误后果也比聊天跑题严重得多。我负责的Agent架构里工具执行层永远是夹在中间的一道闸门。执行层至少要管三件事权限校验确认当前任务是否有权调用这个工具校验可以基于用户角色、任务类型、Agent自身权限级别参数校验工具执行前在代码层判断参数是否合法不合法直接拦截人工放行高风险的写操作、删除操作、对外发送操作设计成需要用户确认后才真正执行。这一步是架构设计里最容易省的地方因为省掉它看起来Agent跑得更顺畅但真出了问题再补就晚了。尤其是涉及外部动作的工具宁可多一次人工确认也不要让Agent在无人监督的情况下做不可逆操作。5. 多Agent协作架构从单兵作战到团队配合单Agent做到一定程度一定会遇到两个天花板上下文有限脑子塞不下太多中间状态职责过杂模型在目标理解、工具选择、结果质检等不同角色之间切换容易互相干扰。这时很多人会转向多Agent协作事实上多Agent架构不是银弹它是一套需要精心设计的分布式协作系统。5.1 多Agent到底解决了什么问题多Agent架构的核心收益不是让多个大模型一起思考而是把复杂的任务目标拆给多个专职Agent让每个Agent负责自己最擅长的一段。各Agent的上下文可以保持相对精简每个Agent的Prompt和工具列表也更好针对性调优。举个例子一个内容生产系统里我可以让一个Agent专门做资料搜集它的工具列表里只有搜索类工具另一个Agent专做写作它拿到归纳好的资料和大纲专注生成内容第三个Agent专做校对用不同的角色设定去检查事实和逻辑漏洞。比让一个Agent既搜索又写作又检查整个流程的质量和可控性都有明显提升。5.2 三种主流协作模式与选型依据多Agent的协作拓扑有很多种我实际用下来最常见的是三种协作模式结构特征适合场景主要代价主从模式主Agent拆解任务后分发给多个子Agent统一收集结果任务颗粒度明确、可并行处理主Agent容易成为瓶颈协商模式多个Agent各提出方案互相评审和反驳最后汇总高难度决策、需要多角度验证调用数量大延迟高流水线模式前一个Agent的输出成为后一个Agent的输入逐级加工流程固定、顺序依赖强的任务单环节出错会向后传导选型的依据不是哪个技术更高级而是任务本身的依赖结构。任务能拆成独立子任务优先用主从模式并行处理任务需要多轮权衡判断考虑协商模式任务本来就是固定流程流水线模式最节省token。5.3 我对多Agent的真实看法先单后多如果让我给刚接触Agent的人一个直接建议我会说不要一开始就设计多Agent。很多场景下一个Agent加上精心设计的工具链、可靠的记忆系统、反思机制已经能解决大部分问题。多Agent带来的通信开销、状态一致性问题、上下文传递损耗都是要在项目里实际付钱的。我自己是在单Agent架构跑通、明确碰到单一上下文和角色冲突的瓶颈之后才逐步把部分能力拆成独立Agent。拆的粒度也不是越多越好而是什么时候单Agent明显扛不住什么时候才拆。这个原则帮我少走了很多弯路。6. 把架构图落到纸上一套可复用的Agent参考架构现在把前面的讨论汇总成一张完整的参考架构图。这张图不是从某个现成产品抄来的而是我把多次项目实践抽象之后沉淀出来的通用形态你可以把它作为自己项目设计的起点。用户 / 环境 │ ▼ ┌──────────────────────────────────────────────┐ │ 入口编排层 │ │ 意图识别 / 任务启动 / 会话与上下文管理 │ └──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────┐ │ 决策中枢 │ │ 规划器(目标拆解) 执行器(子任务执行) │ │ ReAct循环 反思评估模块 │ └──────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ 记忆系统 │ │ 工具调用 │ │ 安全与权限 │ │ 短期/长期│ │ 函数解析/ │ │ 授权校验/参数 │ │ 工作记忆 │ │ 执行封装 │ │ 检查/人工复核 │ └─────────┘ └──────────┘ └──────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────┐ │ 观察链路 │ │ 日志采集 / Trace追踪 / 执行结果反馈 │ └──────────────────────────────────────────────┘ │ ▼ 用户 / 外部工具 / 数据库 / 业务API6.1 逐层拆解这张架构图从下往上看。最底层是观察链路也是Agent的回音壁所有工具执行结果、运行日志、token消耗、延迟都要在这里汇总。它不是可选项而是你排障时的眼睛。没有这一层的Agent出了错只能黑盒猜非常折磨人。上一层是安全与权限模块它横插在决策中枢和工具之间。这层必须独立出来不能在业务代码里随手写几行校验就完事。涉及敏感操作时它要能拦住执行流转人工确认。工具调用层承接决策中枢发来的工具请求做函数解析、参数修复、真实执行。它返回的结果需要经标准化处理不仅是原始数据还要带上执行状态、耗时、错误码、截断摘要这样决策中枢不需要读取全部原始数据就能继续推理。记忆系统在架构图里和工具调用平行它同时服务决策中枢的规划与反思。决策中枢在开始任务前先从长期记忆取回相关背景在任务中把中间状态写入工作记忆任务结束后提炼值得沉淀的信息写入长期记忆。再往上是决策中枢包括规划器、执行器、ReAct循环和反思模块。它接收入口编排层传来的用户目标结合记忆和工具能力循环执行推理-行动-观察-反思直到产出结果。最上面是入口编排层。它负责识别用户意图、决定启动哪类Agent、维护会话上下文。这一层要处理的脏活比你想象得多用户输入要不要被格式化、任务被复制时深拷贝还是引用、多个并发任务的上下文怎么隔离。在许多项目里入口编排层的代码量甚至超过决策中枢。6.2 关键配置项与选型依据参考架构落地时核心配置项选择我给出一个基础清单配置项推荐基础值选择的理由模型温度0.1到0.3工具调用和结构化输出需要低随机性太高会编造参数记忆向量维度取决于嵌入模型输出匹配嵌入模型即可不需要昂贵的高维向量库记忆取回top-k5到8太少可能漏关键信息太多会引入噪声工具调用超时10到30秒根据工具响应特性设定避免卡死整个循环反思最大轮数2到3轮防止反思机制陷入无限自我修正会话上下文窗口控制在实际模型窗口的50%以内剩余窗口要留给工具返回结果和下次输入有一个原则不要把模型的上下文窗口当作无限内存。我实际开发时通常会把内部估算的上下文用量控制在模型窗口的50%以内剩下的一半预留给工具结果、系统指令、反思维度。超过这个水位就要想办法压缩历史内容或提前归档。6.3 数据流一帧帧走一遍架构图是静态的数据流是动态的。我举个例子假设用户提交了一个任务整理这个季度的销售数据并生成一份包含结论的摘要。第一帧入口编排层接收输入做意图识别判断这是一个数据查询加分析任务于是启动对应的Agent流程并读取该用户的长期记忆中关于数据源、报表偏好的历史记录。第二帧决策中枢的规划器收到目标和记忆背景拆出三个子任务定位销售数据表结构、按季度维度聚合数据、对结果做结论提炼。第三帧执行器开始执行第一个子任务调用工具调用层去检索数据源的元数据。工具真实返回了表名和字段说明观察链路把结果压缩成一段简短描述送回执行器。第四帧执行器根据字段说明发起聚合查询。返回的数据量比较大在送入模型之前做了一次摘要和截断只保留季度汇总、环比、异常标记等关键字段。模型基于这些信息生成数据分析并围绕结论写出摘要。第五帧反思模块对输出做一轮质检发现结论里提到了环比增长但原始数据并没有给出去年同期的参照值于是判定存在推理不严谨把问题反馈回决策中枢。第六帧执行器重新调用工具补充查询去年同期的数据模型修正结论后再次生成摘要。反思模块通过质检结果交给入口编排层返回给用户。这一整套流程走下来每一步都有明确归属出了问题能迅速定位到具体模块。我觉得这就是画架构图的意义不是画给别人看而是让系统中的每个环节都有清晰的责任边界出了问题你能快速找到是谁的锅。7. 实操中的坑与我的调试心得就算架构图画得再完整Agent落地的过程还是会有一堆烂事。我把自己踩过的几次比较典型的坑写出来希望能帮你省几个晚上的调试时间。7.1 翻车现场一上下文污染第一次做Agent工具调用时我让Agent去查一个交易系统的用户列表工具返回了一千多条记录。我原本只想要一个统计信息结果把全部记录原样塞进上下文模型看着看着就开始分析某条具体记录的特点完全偏离了原始的分析任务。后来我总结出的规矩是工具返回结果必须经过压缩层再进模型。压缩层的职责是把大段数据转成摘要、统计量、分级信息只有在模型明确需要一个具体条目时才允许它发起二次查询取明细。这个改动之后Agent跑偏的概率明显下降。7.2 翻车现场二工具幻觉模型有时会凭空捏造一个不存在的工具或者给某个真实工具填上完全不存在的参数名。第一次遇到时我以为是模型版本太旧后来排查发现是我某个工具的参数描述写得太模糊模型理解不了怎么用就开始自己猜测。修复分两步一是把同类模糊的参数说明全部重写补上取值范围、格式、示例二是在工具调用层加兜底校验发现参数不在定义范围内时不直接报错而是带着错误信息返回给模型让它自己修正。加了这个闭环之后工具幻觉问题大幅缓解。7.3 翻车现场三递归循环反思机制加多了也会出事。一次调优时我把反思触发条件设得过于严格Agent执行完一轮之后发现自己还有一点点不完美就重新规划、重新执行结果是彻底停不下来了直到token耗尽才被强制终止。这个问题其实是对反思机制的约束不到位。后来我加了两重限制一是反思的最大轮数硬编码超过立即终止并把当前最优结果输出二是反思只针对关键偏差可以定义一些评分规则只在这里卡壳时触发重试不因为轻微措辞问题反复循环。7.4 让Agent变成可控系统的调试三板斧我现在的Agent项目调试方法基本固定为三板斧结构化日志、Trace追踪、Mock工具。结构化日志不是简单print每个关键环节都要输出包含任务ID、环节、模型调用次数、工具名、执行耗时、token消耗的JSON日志这样能按任务还原完整路径。Trace追踪比日志更细一个层次每一步模型输入输出、每一步工具入参出参都能回放排查模型在这个节点为什么做这个选择非常有用。Mock工具更简单——在本地开发时把外部API全部替换成返回预制结果的假实现这样能脱离外部系统限制专注调试决策逻辑本身。另外一定要维护一套最小复现样本集。每次线上出现奇怪行为我会把输入和对应轨迹存下来回归测试时反复跑。Agent项目调的不是某一个函数而是整套决策逻辑没有样本集做回归你每次改Prompt都像在蒙着眼睛调音。根据我个人的经验最开始写Agent代码之前先花几个小时把架构图认真画一遍把每个模块的输入、输出、边界、异常路径都标清楚后面整个开发周期都会顺很多。架构图的每一处修改往往都对应一次深夜排障的教训。它不只是一张图而是你和这个复杂系统之间达成的共识契约。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
