很多朋友学AI Agent最困惑的一个点是网上教程一抓一大把但讲为什么这样设计的少。我也是从把Agent当成加强版聊天机器人开始踩坑过来的直到把架构层的逻辑理顺才真正把Agent从demo推到能稳定跑业务的形态。这一篇就专门聊核心原理和架构属于整个教程系列的地基部分。看完你会搞清楚三件事Agent内部到底在循环什么、主流架构有哪些取舍、以及你自己动手搭一套最小架构时该把代码写在哪些位置。1. 先把Agent拆开看它和普通LLM到底差在哪1.1 从问一句答一句到目标驱动的任务闭环先说个最直观的区别。你直接用ChatGPT或者调用一个纯LLM接口本质上是请求-响应模式用户问一句模型答一句对话结束。这个模式在处理单点问题、文本生成、知识问答时非常够用因为需求本身是明确的——写一封请假邮件就是写一封不需要拆解。但Agent面对的需求往往是模糊的、多步骤的。比如帮我调研一下市场上主流的向量数据库输出一份对比报告这句话里其实藏了至少五个子任务确定调研范围、收集各家产品的关键参数、做性能对比、分析适用场景、整理成结构化文档。纯粹靠一次LLM调用完成不了因为模型没有执行能力它只能描述怎么做而不能真正去做。Agent的核心价值就在这里它把LLM从一个会说话的API变成了一个能自己做事的系统。这个系统内部有一个目标驱动的闭环大致是接收一个目标用户给的或者上游系统传过来的把目标拆解成可执行的步骤执行每一步必要时调用外部工具搜索引擎、数据库、代码解释器等观察执行结果判断是否达成目标没达成继续循环达成了输出最终结果你把这个循环转起来之后LLM才真正成为你业务中的一个数字员工而不是一个问答窗口。1.2 核心四要素感知、决策、行动、记忆理解Agent架构之前必须先记住四个核心要素所有Agent系统不管多复杂拆到底都是这四样东西的变体感知PerceptionAgent获取外界信息的通道。包括用户输入、系统事件、工具返回的结果、其他Agent发来的消息。感知层的设计决定了Agent能看到什么也就决定了它能在多大范围内做决策。很多Agent表现笨不是模型不行而是感知层给的上下文太少。决策DecisionAgent根据当前状态和目标决定下一步做什么。这一层是LLM的主场——说人话就是模型在下一步行动这个选择题上给出答案。决策不是一次性的而是嵌在循环里、每执行一步都要做一次。行动ActionAgent实际执行决策的能力。LTMLong-Term Memory长期记忆负责跨会话存储知识和经验STMShort-Term Memory短期记忆就是当前任务里的上下文工作区。记忆层是Agent区别于每次对话都失忆的普通LLM调用的关键。这四要素不是孤立存在的架构就是把这些要素组织起来、让它们高效配合的那张设计图。2. Agent核心原理深度解读2.1 LLM不是大脑它只是一台推理引擎很多人把LLM称作Agent的大脑这个说法有误导性。按我的理解大脑这个说法暗示LLM应该什么都干但实际上LLM是一个非常纯粹的推理引擎——你不给它上下文它什么都干不了你给它的上下文质量差它给你的决策质量就烂。在Agent架构里LLM承担的是根据当前状态历史记忆目标推断出最合理的下一步这件事。它只负责决定做什么不负责记住所有事情那是记忆模块的活也不负责真正把事情做完那是工具和代码的活。这个认知很重要因为它直接决定了你怎么设计Agent。如果你觉得Agent能力弱先去查你的检索和上下文组装质量别急着换更大的模型。我在实际项目中见过的案例很多Agent变聪明了的反馈其实是把Prompt优化和记忆管理做好了模型根本没换。2.2 ReAct模式把思考和行动绑在一起ReActReasoning and Acting是目前Agent领域最普及的原理框架几乎所有主流的Agent框架LangChain、AutoGPT、BabyAGI这一系底层都能看到它的影子。它的核心思路极其朴素让模型在推理和行动之间交替前进每走一步都留下思考轨迹。传统的LLM调用流程是用户提问 - 模型生成回答 - 结束ReAct的流程是用户提问 - 模型思考我现在需要什么信息 - 模型决定行动搜索X - 观察结果 - 模型再思考还缺什么 - 再行动 - ... - 模型判断目标达成 - 生成最终回答这个思考-行动-观察的循环就是Agent的核心运转方式。ReAct最巧妙的一点是它把思考过程也作为Prompt的一部分传给模型让模型在已经想到哪一步的基础上继续推理而不是每次从零开始。这既解决了多步骤任务的连贯性问题也给开发者留出了调试空间——你随时打开日志就能看到Agent现在是卡在推理还是卡在执行。2.3 Planner-Executor拆分复杂任务不再一步走到黑ReAct适合中等复杂度的任务但任务再复杂一点比如帮我把季度销售数据做清洗、分析、出图表、生成PPT大纲如果还靠ReAct一步一循环Agent很容易在前面几步就迷失方向因为它没有一个全局规划。这时候就有了Planner-Executor架构。核心思想是把规划和执行拆成两个角色。Planner的角色是拿到目标先做全局拆解生成一份任务清单比如1. 读取数据- 2. 清洗数据- 3. 统计分析- 4. 生成图表- 5. 组装PPT大纲。这份清单不一定是最终执行顺序但它给了Agent一张地图。Executor的角色是按照清单逐项执行每执行完一项就标记完成遇到阻塞就返回状态。这个架构的好处特别明显规划变得可审核你能看到Agent打算怎么做而不是黑盒执行可中断某个子任务失败不影响全局可并行清单里的独立任务可以交给不同的执行器并行跑实际工程中Planner和Executor可以都是LLM驱动的也可以Planner用LLM、Executor用固定代码逻辑。比如那些流程极其固定的场景取数、清洗、出报表Executor用代码写死反而更稳定、更省钱。2.4 工具调用与Function Calling机制Agent的手从哪来Agent和普通聊天机器人的另一个分水岭是能不能调用工具。没有工具的Agent只能动嘴有了工具的Agent才能动手。而工具调用在技术实现上主流就是Function Calling机制。这个过程可以简化为三步第一步你把工具的函数签名函数名、参数、功能描述以结构化JSON格式传给LLM第二步LLM根据用户的请求在它的知识里判断该不该调用某个工具、参数填什么然后返回一个结构化的调用指令比如调用search_web参数是{query: 2025年向量数据库排名}第三步你的代码解析这个指令、实际执行对应函数、把结果回传给LLMLLM再基于结果继续推理关键点在这个循环上工具不是LLM自己跑的是你的代码跑的。LLM只负责决定调用实际执行权永远在你手里。这个设计给了开发者一个非常强的控制点——你可以审查工具调用的合理性、加权限校验、做成本控制、甚至在某些场景下直接拦截掉不安全的操作。我在实操中强烈建议每个工具的语义描述要写清楚包括什么时候用、什么时候别用、参数格式什么样。这个细节直接影响LLM的调用准确率比你在Prompt里反复强调请谨慎使用工具有效得多。3. 主流架构盘点单Agent、多Agent、LLMAPI、微服务3.1 单Agent架构简单直接入门首选单Agent架构就是一个Agent实例独立处理目标任务内部包含完整的感知、决策、行动、记忆闭环。这种架构是入门阶段的首选也是理解Agent原理的最佳载体。单Agent架构最适合三类场景任务边界清晰比如自动回复邮件定时抓取网页生成摘要工具调用链比较固定Agent基本按既定路径走你需要快速验证一个Agent idea是否可行单Agent的局限性在复杂场景里也很明显一是上下文容易膨胀Agent在长流程里不断把中间结果塞进上下文很快就会撞到窗口上限二是职责耦合一个Agent既要规划又要执行还要管记忆代码逻辑复杂后维护成本直线上升三是单点故障Agent任何一个环节卡死整个任务就废了。3.2 多Agent协作架构角色分工与通信多Agent架构是现在行业里最火热的方向之一核心思路是不再造一个全能的超人Agent而是让多个专精的Agent各管一摊再通过某种协作机制把任务搞定。最常见的实现是主控-执行模式Orchestrator-Workers。主控Agent负责理解用户意图、拆分任务、分发给各个执行Agent然后收集结果、汇总输出。每个执行Agent只负责自己的领域一个专门写代码、一个专门读文档、一个专门做搜索。多Agent架构的核心问题不是怎么造Agent而是Agent之间怎么通信。我见过三种通行方式直接调用主控Agent通过函数调用的方式直接调用子Agent最简单但耦合度高消息队列Agent之间通过队列传递消息解耦好适合异步场景但延迟高共享黑板Blackboard所有Agent往一个共享空间里写中间结果、读需要的信息适合复杂任务的协作但需要设计好数据结构多Agent架构还有一个隐藏成本Token消耗。每多一个Agent就多一个LLM实例在推理Token费用几乎是线性增长。我见过一个四Agent的项目一次完整任务的Token消耗是同任务单Agent做法的3到4倍。性能和智能化之间的性价比必须在架构选型时算清楚。3.3 LLMAPI轻量架构不改造现有业务也能接入Agent很多团队一开始容易掉进一个误区上Agent就要上重框架非要搞复杂的编排系统。其实有一种被严重低估的架构LLMAPI轻量架构或者叫内嵌式Agent。这在实操里大概长这样你原本有一个业务系统比如工单系统系统里已经有现成的API——创建工单、查询用户信息、更新状态。你把这些API封装成Agent可调用的工具然后在业务系统里嵌入一个LLM决策模块让它根据对话内容决定调哪个API、参数是什么。这就是一个限定域Agent。轻量架构最大的优点一是风险低Agent只在你的业务闭环里活动不会乱跑二是见效快可能两周就能出一个可演示的版本三是成本可控因为领域窄、Prompt短Token消耗不大。我见过不少传统软件团队就是从这种架构开始接触Agent的他们反馈说这句话最贴切不是我们上了Agent而是我们把Agent嵌进了业务里。3.4 微服务与分布式Agent架构规模化之后的必经之路当Agent的应用范围从一个任务扩张到一个平台时上面这些单体式架构就hold不住了。这时候就需要考虑微服务化和分布式。微服务架构的思路是把Agent系统按职责切成独立的服务每个服务可以独立开发、独立部署、独立扩容。比如我把记忆服务单独拎出来做成一个可以供多个Agent共享的向量检索服务我把工具执行器拆成独立服务在并发大的时候单独做弹性伸缩。分布式Agent架构更进一步它要解决的是三个问题多实例水平扩展让同一个Agent跑多个副本实现高并发状态同步多个Agent副本之间共享记忆和状态避免各说各话容错与恢复某个节点挂了任务能被其他节点接管这个层面的架构需要引入消息队列比如Kafka、RabbitMQ、分布式存储Redis、向量数据库集群、任务调度框架Celery、Temporal这些基础设施。技术栈会复杂不少但它支撑的是完全不同的量级——如果说单体Agent能处理每天几百个任务分布式的目标是每天几百万个。3.5 架构选型对照表为了让你在选型的时候心里有数我把几种架构放到一个表里做一个直接对照架构类型适用阶段典型场景优点主要代价单AgentMVP验证个人助手、单一自动化任务开发快、理解简单、易调试上下文易膨胀、职责耦合、无容错多Agent协作功能扩展复杂项目、多角色协作职责清晰、可并行、扩展性好Token成本高、通信设计复杂LLMAPI轻量业务内嵌工单系统、CRM、客服辅助风险低、见效快、成本可控只适用于限定领域通用性弱微服务化平台化初期多Agent共享基础设施利于独立扩容、技术异构运维复杂、链路长分布式规模化生产高并发、海量任务平台高可用、强扩展基础设施复杂、调试成本高我的建议是不要为了架构而架构。你的Agent业务还没验证就跑去做分布式大概率浪费一两个月时间。大部分人的正确路径是先用单Agent跑通核心价值然后再根据瓶颈决定往哪个方向演进。4. 实操从零搭一个Agent最小架构4.1 先定义骨架状态、记忆、工具清单纸上谈兵了这么多下面进入实操环节。我会用伪代码和Python风格示例带你搭一个最小的Agent骨架。这个骨架不依赖任何Agent框架纯粹用LLM API就能工作目的就是让你看清架构的运转逻辑。第一步定义Agent的结构体。一个Agent至少要包含三块状态当前任务进度、记忆历史上下文、工具清单可调用函数列表。代码大致长这样class MinimalAgent: def __init__(self, llm, tools): self.llm llm # LLM推理引擎 self.tools tools # 工具注册表 {name: function} self.memory [] # 短期记忆存放(思考/行动/观察)历史 self.state { task: None, # 当前目标 step: 0, # 已执行步数 done: False, # 是否完成 }这个结构看着简单但它已经把四要素里的决策llm、行动tools、记忆memory、状态state都装进去了。4.2 ReAct循环的代码级实现Agent的核心运转就是那个ReAct循环。要把这个循环写成代码其实就是一段简单的while逻辑def run(self, task): self.state[task] task self.memory.append({role: user, content: task}) while not self.state[done] and self.state[step] self.max_steps: # 1. 让LLM基于当前记忆和工具清单决定下一步 response self.llm.chat( messagesself.memory, toolsself.tool_schemas, # 工具的函数签名描述 tool_choiceauto ) # 2. 如果模型说要调用工具 if response.tool_calls: for call in response.tool_calls: # 执行工具 result self.tools[call.function.name](**call.function.arguments) # 把结果写回记忆供下一轮推理使用 self.memory.append({ role: tool, content: str(result), tool_call_id: call.id }) else: # 3. 如果模型没有要求工具就认为任务完成输出最终答案 self.state[done] True return response.content self.state[step] 1这段代码你仔细看就四件事调LLM - 有工具调用就执行 - 把结果写回记忆 - 循环。这就是整个Agent原理的核心了。很多商业框架里跑到神乎其神的编排拆开看也无非是把这个循环加上各种增强更好的记忆管理、更多的上下文处理器、更复杂的工具定义。4.3 给Agent接上手工具定义与权限校验上面代码里给LLM传了一个tool_schemas这个就是工具描述。以搜索工具为例大致长这样{ type: function, function: { name: web_search, description: 在互联网上搜索给定关键词返回相关网页标题和摘要, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词尽量精简} }, required: [query] } } }这里的description非常关键。LLM是靠这段描述来理解什么时候该用这个工具的描述写得太笼统模型就会在不需要搜索的时候也去搜索。我自己的经验是描述要回答三个问题这个工具干什么、什么时候用、什么时候别用。权限校验是另一个很容易被忽略的点。Agent在真实业务里能调用工具就意味着能产生真实影响我在上一家公司就因为Agent自动执行了一个生产环境脚本差点出事故。从那之后我给自己定了两条铁律所有工具调用必须过一层校验逻辑可以是白名单、敏感操作二次确认、或频率限制所有高风险工具删除、写入、支付类默认禁止Agent直接执行。4.4 可观测性没有日志的Agent就是定时炸弹这一点必须单独拿出来说因为Agent和普通程序调试完全不同。普通程序报错会告诉你哪行代码出了问题Agent出问题是模型莫名其妙开始重复某个行为或者明明任务已经完成却还在继续调用工具。没有日志你根本无迹可寻。我的做法是给每一步循环都打结构化日志格式大致是[Agent][Step 2] 决策调用工具 web_search [Agent][Step 2] 参数{query: 2025向量数据库} [Agent][Step 3] 观察返回7条结果前3条相关 [Agent][Step 4] 决策生成最终回答此外还要记录Token消耗和耗时这两个指标是评估Agent效率的关键。有些Agent任务做完只需要5步有些绕了30步——多出来的25步就是纯浪费通过记录每步日志能清楚地看到卡点在哪。5. 常见问题与排查实录5.1 Agent陷入死循环怎么办这是被问得最多的一个问题Agent反复做同样的操作、就是不结束。原因通常是三种目标不够明确、工具返回结果不够好、最大步数限制设得太宽松甚至没设。我在项目里的兜底方案有三个给循环加max_steps硬限制宁可任务完不成也不能无限空转在Prompt里加避免重复执行相同操作的约束虽然效果有限但聊胜于无检测重复模式如果模型连续三次输出同样的思考内容和工具调用直接主动打断并把历史摘要发给模型让它换路径5.2 模型乱调工具尤其是调了不该调的怎么防模型不听话是常态它可能在你只让它查数据的时候顺手调了写操作的工具。这个问题的根治方法不是祈祷模型更聪明而是从架构上隔离。我的做法是把工具分成三等只读工具搜索、查询、业务操作工具创建工单、发消息、高风险工具删除、修改生产数据。Agent默认只能调前两类。第二类如果要调需要显式的用户确认第三类直接在工具注册阶段就不给它看到。在最新版的Function Calling机制里你甚至可以对不同工具分别设置权限级别这在多租户场景下尤其有用。5.3 多Agent通信踩过坑直接互相调用的坑做多Agent协作项目时我走过弯路一开始图省事把所有Agent放在同一个进程里直接在代码层面互相调用。等任务量上来后发现两个问题一个Agent卡住整个调用链都等它另一个是消息历史在Agent之间来回传递同一段信息重复存储上下文膨胀得很厉害。后来换成了消息队列方案每个Agent独立部署、通过队列收发任务消息。虽然多了中间件但整个系统的稳定性提升了不止一个档次。一个Agent挂了其他Agent继续工作主控Agent只需要在超时后重发任务或者走降级方案。教训就是多Agent系统的通信架构设计宁可一开始复杂一点也不要图省事。5.4 架构演进节奏什么时候该从单体切到微服务很多人焦虑我的Agent架构是不是太简单了要不要早点上微服务。我见过一个非常典型的案例一个团队花了两周时间把本来单体运行的Agent改成微服务结果线上故障率不降反升。我现在的判断标准很简单出现以下三个信号之一再考虑切某个模块的负载明显不均比如记忆服务的QPS是其他模块的十倍需要多个团队协作开发同一个Agent系统单体代码冲突太频繁Agent的某个组件需要独立的技术方案比如记忆要用向量数据库但主服务还是PostgreSQL最后聊两句我的个人体会做了这么久的Agent项目我最深的感受是Agent架构的复杂度不是来自技术本身而是来自不确定性。传统软件的每个分支都是确定的Agent的每个分支都是模型现场生成的。这意味着架构越是复杂、链路越长出问题的面就越大。所以我自己的实践准则一直是用最简架构托住当前规模留好演进接口。你能看到很多商业Agent平台上的成功案例多半不是因为他们用了多牛的技术架构而是他们把某一个单Agent场景打磨到了极致。下一次动手搭Agent之前不妨先问自己一句我的Agent最核心的那个循环我能清晰地画出来吗画不出来先去补基础画得出来再考虑往上堆架构。
很多朋友学AI Agent最困惑的一个点是网上教程一抓一大把但讲为什么这样设计的少。我也是从把Agent当成加强版聊天机器人开始踩坑过来的直到把架构层的逻辑理顺才真正把Agent从demo推到能稳定跑业务的形态。这一篇就专门聊核心原理和架构属于整个教程系列的地基部分。看完你会搞清楚三件事Agent内部到底在循环什么、主流架构有哪些取舍、以及你自己动手搭一套最小架构时该把代码写在哪些位置。1. 先把Agent拆开看它和普通LLM到底差在哪1.1 从问一句答一句到目标驱动的任务闭环先说个最直观的区别。你直接用ChatGPT或者调用一个纯LLM接口本质上是请求-响应模式用户问一句模型答一句对话结束。这个模式在处理单点问题、文本生成、知识问答时非常够用因为需求本身是明确的——写一封请假邮件就是写一封不需要拆解。但Agent面对的需求往往是模糊的、多步骤的。比如帮我调研一下市场上主流的向量数据库输出一份对比报告这句话里其实藏了至少五个子任务确定调研范围、收集各家产品的关键参数、做性能对比、分析适用场景、整理成结构化文档。纯粹靠一次LLM调用完成不了因为模型没有执行能力它只能描述怎么做而不能真正去做。Agent的核心价值就在这里它把LLM从一个会说话的API变成了一个能自己做事的系统。这个系统内部有一个目标驱动的闭环大致是接收一个目标用户给的或者上游系统传过来的把目标拆解成可执行的步骤执行每一步必要时调用外部工具搜索引擎、数据库、代码解释器等观察执行结果判断是否达成目标没达成继续循环达成了输出最终结果你把这个循环转起来之后LLM才真正成为你业务中的一个数字员工而不是一个问答窗口。1.2 核心四要素感知、决策、行动、记忆理解Agent架构之前必须先记住四个核心要素所有Agent系统不管多复杂拆到底都是这四样东西的变体感知PerceptionAgent获取外界信息的通道。包括用户输入、系统事件、工具返回的结果、其他Agent发来的消息。感知层的设计决定了Agent能看到什么也就决定了它能在多大范围内做决策。很多Agent表现笨不是模型不行而是感知层给的上下文太少。决策DecisionAgent根据当前状态和目标决定下一步做什么。这一层是LLM的主场——说人话就是模型在下一步行动这个选择题上给出答案。决策不是一次性的而是嵌在循环里、每执行一步都要做一次。行动ActionAgent实际执行决策的能力。LTMLong-Term Memory长期记忆负责跨会话存储知识和经验STMShort-Term Memory短期记忆就是当前任务里的上下文工作区。记忆层是Agent区别于每次对话都失忆的普通LLM调用的关键。这四要素不是孤立存在的架构就是把这些要素组织起来、让它们高效配合的那张设计图。2. Agent核心原理深度解读2.1 LLM不是大脑它只是一台推理引擎很多人把LLM称作Agent的大脑这个说法有误导性。按我的理解大脑这个说法暗示LLM应该什么都干但实际上LLM是一个非常纯粹的推理引擎——你不给它上下文它什么都干不了你给它的上下文质量差它给你的决策质量就烂。在Agent架构里LLM承担的是根据当前状态历史记忆目标推断出最合理的下一步这件事。它只负责决定做什么不负责记住所有事情那是记忆模块的活也不负责真正把事情做完那是工具和代码的活。这个认知很重要因为它直接决定了你怎么设计Agent。如果你觉得Agent能力弱先去查你的检索和上下文组装质量别急着换更大的模型。我在实际项目中见过的案例很多Agent变聪明了的反馈其实是把Prompt优化和记忆管理做好了模型根本没换。2.2 ReAct模式把思考和行动绑在一起ReActReasoning and Acting是目前Agent领域最普及的原理框架几乎所有主流的Agent框架LangChain、AutoGPT、BabyAGI这一系底层都能看到它的影子。它的核心思路极其朴素让模型在推理和行动之间交替前进每走一步都留下思考轨迹。传统的LLM调用流程是用户提问 - 模型生成回答 - 结束ReAct的流程是用户提问 - 模型思考我现在需要什么信息 - 模型决定行动搜索X - 观察结果 - 模型再思考还缺什么 - 再行动 - ... - 模型判断目标达成 - 生成最终回答这个思考-行动-观察的循环就是Agent的核心运转方式。ReAct最巧妙的一点是它把思考过程也作为Prompt的一部分传给模型让模型在已经想到哪一步的基础上继续推理而不是每次从零开始。这既解决了多步骤任务的连贯性问题也给开发者留出了调试空间——你随时打开日志就能看到Agent现在是卡在推理还是卡在执行。2.3 Planner-Executor拆分复杂任务不再一步走到黑ReAct适合中等复杂度的任务但任务再复杂一点比如帮我把季度销售数据做清洗、分析、出图表、生成PPT大纲如果还靠ReAct一步一循环Agent很容易在前面几步就迷失方向因为它没有一个全局规划。这时候就有了Planner-Executor架构。核心思想是把规划和执行拆成两个角色。Planner的角色是拿到目标先做全局拆解生成一份任务清单比如1. 读取数据- 2. 清洗数据- 3. 统计分析- 4. 生成图表- 5. 组装PPT大纲。这份清单不一定是最终执行顺序但它给了Agent一张地图。Executor的角色是按照清单逐项执行每执行完一项就标记完成遇到阻塞就返回状态。这个架构的好处特别明显规划变得可审核你能看到Agent打算怎么做而不是黑盒执行可中断某个子任务失败不影响全局可并行清单里的独立任务可以交给不同的执行器并行跑实际工程中Planner和Executor可以都是LLM驱动的也可以Planner用LLM、Executor用固定代码逻辑。比如那些流程极其固定的场景取数、清洗、出报表Executor用代码写死反而更稳定、更省钱。2.4 工具调用与Function Calling机制Agent的手从哪来Agent和普通聊天机器人的另一个分水岭是能不能调用工具。没有工具的Agent只能动嘴有了工具的Agent才能动手。而工具调用在技术实现上主流就是Function Calling机制。这个过程可以简化为三步第一步你把工具的函数签名函数名、参数、功能描述以结构化JSON格式传给LLM第二步LLM根据用户的请求在它的知识里判断该不该调用某个工具、参数填什么然后返回一个结构化的调用指令比如调用search_web参数是{query: 2025年向量数据库排名}第三步你的代码解析这个指令、实际执行对应函数、把结果回传给LLMLLM再基于结果继续推理关键点在这个循环上工具不是LLM自己跑的是你的代码跑的。LLM只负责决定调用实际执行权永远在你手里。这个设计给了开发者一个非常强的控制点——你可以审查工具调用的合理性、加权限校验、做成本控制、甚至在某些场景下直接拦截掉不安全的操作。我在实操中强烈建议每个工具的语义描述要写清楚包括什么时候用、什么时候别用、参数格式什么样。这个细节直接影响LLM的调用准确率比你在Prompt里反复强调请谨慎使用工具有效得多。3. 主流架构盘点单Agent、多Agent、LLMAPI、微服务3.1 单Agent架构简单直接入门首选单Agent架构就是一个Agent实例独立处理目标任务内部包含完整的感知、决策、行动、记忆闭环。这种架构是入门阶段的首选也是理解Agent原理的最佳载体。单Agent架构最适合三类场景任务边界清晰比如自动回复邮件定时抓取网页生成摘要工具调用链比较固定Agent基本按既定路径走你需要快速验证一个Agent idea是否可行单Agent的局限性在复杂场景里也很明显一是上下文容易膨胀Agent在长流程里不断把中间结果塞进上下文很快就会撞到窗口上限二是职责耦合一个Agent既要规划又要执行还要管记忆代码逻辑复杂后维护成本直线上升三是单点故障Agent任何一个环节卡死整个任务就废了。3.2 多Agent协作架构角色分工与通信多Agent架构是现在行业里最火热的方向之一核心思路是不再造一个全能的超人Agent而是让多个专精的Agent各管一摊再通过某种协作机制把任务搞定。最常见的实现是主控-执行模式Orchestrator-Workers。主控Agent负责理解用户意图、拆分任务、分发给各个执行Agent然后收集结果、汇总输出。每个执行Agent只负责自己的领域一个专门写代码、一个专门读文档、一个专门做搜索。多Agent架构的核心问题不是怎么造Agent而是Agent之间怎么通信。我见过三种通行方式直接调用主控Agent通过函数调用的方式直接调用子Agent最简单但耦合度高消息队列Agent之间通过队列传递消息解耦好适合异步场景但延迟高共享黑板Blackboard所有Agent往一个共享空间里写中间结果、读需要的信息适合复杂任务的协作但需要设计好数据结构多Agent架构还有一个隐藏成本Token消耗。每多一个Agent就多一个LLM实例在推理Token费用几乎是线性增长。我见过一个四Agent的项目一次完整任务的Token消耗是同任务单Agent做法的3到4倍。性能和智能化之间的性价比必须在架构选型时算清楚。3.3 LLMAPI轻量架构不改造现有业务也能接入Agent很多团队一开始容易掉进一个误区上Agent就要上重框架非要搞复杂的编排系统。其实有一种被严重低估的架构LLMAPI轻量架构或者叫内嵌式Agent。这在实操里大概长这样你原本有一个业务系统比如工单系统系统里已经有现成的API——创建工单、查询用户信息、更新状态。你把这些API封装成Agent可调用的工具然后在业务系统里嵌入一个LLM决策模块让它根据对话内容决定调哪个API、参数是什么。这就是一个限定域Agent。轻量架构最大的优点一是风险低Agent只在你的业务闭环里活动不会乱跑二是见效快可能两周就能出一个可演示的版本三是成本可控因为领域窄、Prompt短Token消耗不大。我见过不少传统软件团队就是从这种架构开始接触Agent的他们反馈说这句话最贴切不是我们上了Agent而是我们把Agent嵌进了业务里。3.4 微服务与分布式Agent架构规模化之后的必经之路当Agent的应用范围从一个任务扩张到一个平台时上面这些单体式架构就hold不住了。这时候就需要考虑微服务化和分布式。微服务架构的思路是把Agent系统按职责切成独立的服务每个服务可以独立开发、独立部署、独立扩容。比如我把记忆服务单独拎出来做成一个可以供多个Agent共享的向量检索服务我把工具执行器拆成独立服务在并发大的时候单独做弹性伸缩。分布式Agent架构更进一步它要解决的是三个问题多实例水平扩展让同一个Agent跑多个副本实现高并发状态同步多个Agent副本之间共享记忆和状态避免各说各话容错与恢复某个节点挂了任务能被其他节点接管这个层面的架构需要引入消息队列比如Kafka、RabbitMQ、分布式存储Redis、向量数据库集群、任务调度框架Celery、Temporal这些基础设施。技术栈会复杂不少但它支撑的是完全不同的量级——如果说单体Agent能处理每天几百个任务分布式的目标是每天几百万个。3.5 架构选型对照表为了让你在选型的时候心里有数我把几种架构放到一个表里做一个直接对照架构类型适用阶段典型场景优点主要代价单AgentMVP验证个人助手、单一自动化任务开发快、理解简单、易调试上下文易膨胀、职责耦合、无容错多Agent协作功能扩展复杂项目、多角色协作职责清晰、可并行、扩展性好Token成本高、通信设计复杂LLMAPI轻量业务内嵌工单系统、CRM、客服辅助风险低、见效快、成本可控只适用于限定领域通用性弱微服务化平台化初期多Agent共享基础设施利于独立扩容、技术异构运维复杂、链路长分布式规模化生产高并发、海量任务平台高可用、强扩展基础设施复杂、调试成本高我的建议是不要为了架构而架构。你的Agent业务还没验证就跑去做分布式大概率浪费一两个月时间。大部分人的正确路径是先用单Agent跑通核心价值然后再根据瓶颈决定往哪个方向演进。4. 实操从零搭一个Agent最小架构4.1 先定义骨架状态、记忆、工具清单纸上谈兵了这么多下面进入实操环节。我会用伪代码和Python风格示例带你搭一个最小的Agent骨架。这个骨架不依赖任何Agent框架纯粹用LLM API就能工作目的就是让你看清架构的运转逻辑。第一步定义Agent的结构体。一个Agent至少要包含三块状态当前任务进度、记忆历史上下文、工具清单可调用函数列表。代码大致长这样class MinimalAgent: def __init__(self, llm, tools): self.llm llm # LLM推理引擎 self.tools tools # 工具注册表 {name: function} self.memory [] # 短期记忆存放(思考/行动/观察)历史 self.state { task: None, # 当前目标 step: 0, # 已执行步数 done: False, # 是否完成 }这个结构看着简单但它已经把四要素里的决策llm、行动tools、记忆memory、状态state都装进去了。4.2 ReAct循环的代码级实现Agent的核心运转就是那个ReAct循环。要把这个循环写成代码其实就是一段简单的while逻辑def run(self, task): self.state[task] task self.memory.append({role: user, content: task}) while not self.state[done] and self.state[step] self.max_steps: # 1. 让LLM基于当前记忆和工具清单决定下一步 response self.llm.chat( messagesself.memory, toolsself.tool_schemas, # 工具的函数签名描述 tool_choiceauto ) # 2. 如果模型说要调用工具 if response.tool_calls: for call in response.tool_calls: # 执行工具 result self.tools[call.function.name](**call.function.arguments) # 把结果写回记忆供下一轮推理使用 self.memory.append({ role: tool, content: str(result), tool_call_id: call.id }) else: # 3. 如果模型没有要求工具就认为任务完成输出最终答案 self.state[done] True return response.content self.state[step] 1这段代码你仔细看就四件事调LLM - 有工具调用就执行 - 把结果写回记忆 - 循环。这就是整个Agent原理的核心了。很多商业框架里跑到神乎其神的编排拆开看也无非是把这个循环加上各种增强更好的记忆管理、更多的上下文处理器、更复杂的工具定义。4.3 给Agent接上手工具定义与权限校验上面代码里给LLM传了一个tool_schemas这个就是工具描述。以搜索工具为例大致长这样{ type: function, function: { name: web_search, description: 在互联网上搜索给定关键词返回相关网页标题和摘要, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词尽量精简} }, required: [query] } } }这里的description非常关键。LLM是靠这段描述来理解什么时候该用这个工具的描述写得太笼统模型就会在不需要搜索的时候也去搜索。我自己的经验是描述要回答三个问题这个工具干什么、什么时候用、什么时候别用。权限校验是另一个很容易被忽略的点。Agent在真实业务里能调用工具就意味着能产生真实影响我在上一家公司就因为Agent自动执行了一个生产环境脚本差点出事故。从那之后我给自己定了两条铁律所有工具调用必须过一层校验逻辑可以是白名单、敏感操作二次确认、或频率限制所有高风险工具删除、写入、支付类默认禁止Agent直接执行。4.4 可观测性没有日志的Agent就是定时炸弹这一点必须单独拿出来说因为Agent和普通程序调试完全不同。普通程序报错会告诉你哪行代码出了问题Agent出问题是模型莫名其妙开始重复某个行为或者明明任务已经完成却还在继续调用工具。没有日志你根本无迹可寻。我的做法是给每一步循环都打结构化日志格式大致是[Agent][Step 2] 决策调用工具 web_search [Agent][Step 2] 参数{query: 2025向量数据库} [Agent][Step 3] 观察返回7条结果前3条相关 [Agent][Step 4] 决策生成最终回答此外还要记录Token消耗和耗时这两个指标是评估Agent效率的关键。有些Agent任务做完只需要5步有些绕了30步——多出来的25步就是纯浪费通过记录每步日志能清楚地看到卡点在哪。5. 常见问题与排查实录5.1 Agent陷入死循环怎么办这是被问得最多的一个问题Agent反复做同样的操作、就是不结束。原因通常是三种目标不够明确、工具返回结果不够好、最大步数限制设得太宽松甚至没设。我在项目里的兜底方案有三个给循环加max_steps硬限制宁可任务完不成也不能无限空转在Prompt里加避免重复执行相同操作的约束虽然效果有限但聊胜于无检测重复模式如果模型连续三次输出同样的思考内容和工具调用直接主动打断并把历史摘要发给模型让它换路径5.2 模型乱调工具尤其是调了不该调的怎么防模型不听话是常态它可能在你只让它查数据的时候顺手调了写操作的工具。这个问题的根治方法不是祈祷模型更聪明而是从架构上隔离。我的做法是把工具分成三等只读工具搜索、查询、业务操作工具创建工单、发消息、高风险工具删除、修改生产数据。Agent默认只能调前两类。第二类如果要调需要显式的用户确认第三类直接在工具注册阶段就不给它看到。在最新版的Function Calling机制里你甚至可以对不同工具分别设置权限级别这在多租户场景下尤其有用。5.3 多Agent通信踩过坑直接互相调用的坑做多Agent协作项目时我走过弯路一开始图省事把所有Agent放在同一个进程里直接在代码层面互相调用。等任务量上来后发现两个问题一个Agent卡住整个调用链都等它另一个是消息历史在Agent之间来回传递同一段信息重复存储上下文膨胀得很厉害。后来换成了消息队列方案每个Agent独立部署、通过队列收发任务消息。虽然多了中间件但整个系统的稳定性提升了不止一个档次。一个Agent挂了其他Agent继续工作主控Agent只需要在超时后重发任务或者走降级方案。教训就是多Agent系统的通信架构设计宁可一开始复杂一点也不要图省事。5.4 架构演进节奏什么时候该从单体切到微服务很多人焦虑我的Agent架构是不是太简单了要不要早点上微服务。我见过一个非常典型的案例一个团队花了两周时间把本来单体运行的Agent改成微服务结果线上故障率不降反升。我现在的判断标准很简单出现以下三个信号之一再考虑切某个模块的负载明显不均比如记忆服务的QPS是其他模块的十倍需要多个团队协作开发同一个Agent系统单体代码冲突太频繁Agent的某个组件需要独立的技术方案比如记忆要用向量数据库但主服务还是PostgreSQL最后聊两句我的个人体会做了这么久的Agent项目我最深的感受是Agent架构的复杂度不是来自技术本身而是来自不确定性。传统软件的每个分支都是确定的Agent的每个分支都是模型现场生成的。这意味着架构越是复杂、链路越长出问题的面就越大。所以我自己的实践准则一直是用最简架构托住当前规模留好演进接口。你能看到很多商业Agent平台上的成功案例多半不是因为他们用了多牛的技术架构而是他们把某一个单Agent场景打磨到了极致。下一次动手搭Agent之前不妨先问自己一句我的Agent最核心的那个循环我能清晰地画出来吗画不出来先去补基础画得出来再考虑往上堆架构。
