去年我在客户现场演示一个 Agent 原型流程跑通的那一刻会议室里所有人都很兴奋。但紧接着客户问了一句“这个什么时候能上线”——整个房间安静了。那个 Demo 是我用两天时间搭出来的代码里塞满了硬编码的临时方案连报错都是直接抛给前端显示的字符串。这个问题其实非常普遍Agent 的 Demo 和 Agent 的生产系统之间隔着的不是“更多代码”而是整套架构思路的转换。这篇东西就是围绕这个转换过程来写的单智能体的核心循环怎么设计、多智能体到底怎么协作、从 Demo 到生产要过哪些坎以及我在这个过程中踩过的坑和总结出的排查技巧。适合正在做 Agent 原型、准备往生产推或者已经上了但被稳定性折磨的团队参考。1. 内容整体设计与思路拆解1.1 Agent 到底是什么先统一概念再谈架构先说清楚一个事很多人讨论 Agent 架构但说的根本不是同一个东西。有的团队管“调用大模型 API 并且带了 system prompt”就叫 Agent有的团队把“能自动调用外部工具的 workflow”叫 Agent还有的团队认为只有“能自主规划、拆解任务、多步决策”的系统才配叫 Agent。我自己的理解比较务实Agent 是一个以大模型为决策核心、能感知环境工具返回、用户输入、系统状态并采取行动调用工具、生成回复、修改状态的闭环系统。它的本质不是“更聪明的聊天机器人”而是“把大模型从‘生成文本’变成‘执行任务’的壳”。一个最小闭环长这样用户输入/任务触发 → 大模型推理结合上下文与可用工具信息 → 决定下一步动作调用工具 or 直接回复 → 执行动作调用API/查数据库/执行代码/发请求 → 观察结果 → 回到第二步直到任务完成或达到终止条件这个循环听起来简单但所有生产环境里让人头疼的问题——超时、token 失控、误调用高危工具、多轮后上下文爆炸——全都是这个循环在真实数据流下放大出来的。所以架构设计的第一件事不是选框架而是想清楚这个闭环在你业务里的具体形态。我见过最快的破产路线上来就整多智能体、事件总线、任务队列结果连单 Agent 的工具调用都经常超时。真没必要先跑通最小闭环再谈复杂度。1.2 为什么 Demo 架构不能直接搬到生产先盘点一下 Demo 阶段最常见的“将就”工具调用结果直接粗暴塞进上下文。Demo 时一份 20 页的 PDF 全文塞进去没问题生产环境里一个客户的数据报表可能几十 MB直接塞就等着 token 爆掉。没有超时和重试边界。Demo 时调的是虚构数据接口生产环境里任何一个外部服务抖动整个 Agent 就卡死在那。状态全存在内存里。Demo 一个会话无所谓生产环境一个会话可能持续几天、被多个服务节点路由状态丢一次就是事故。安全靠自觉。Demo 时可以允许大模型随意调删除接口生产环境一个误调用可能把客户配置清空。这些问题的根源只有一个Demo 验证的是“能不能”生产回答的是“稳不稳、准不准、安不安全、贵不贵”。1.3 架构设计的起点先定义边界再选技术我在动手写任何 Agent 架构之前会先回答四个问题Agent 的服务边界是什么是只处理对话还是要接管业务流程比如“只推荐商品”和“直接帮你下单”完全两种架构大模型在系统里是“决策者”还是“辅助者”所有关键步骤都让大模型拍板还是只在特定分支里让大模型生成文本失败的最低成本路径是什么调用失败了能不能降级成人工处理关键操作有没有二次确认成本预算在哪个量级每轮对话平均消耗多少 token超出怎么熔断这四个问题决定了架构是“轻编排”还是“重编排”。如果大模型只是辅助那架构可以很轻核心流程代码手写Agent 只负责填特定槽位如果大模型是决策者就要上完整的任务规划和执行框架并配备密集的校验点。注意这一步不能省。我见过太多团队直接套 LangChain 模板跑起来很顺但一上生产就发现根本不知道哪些环节会出问题——因为他们在设计阶段就没有定义过失败边界。2. 单智能体架构从核心循环到工程化2.1 核心循环的三个关键实现细节无论你用什么框架单 Agent 的核心循环都逃不过三件事推理Reasoning、动作Action、观察Observation也就是常说的 ReAct 模式。生产实现里三个细节决定成败第一动作空间要小而明确。大模型在一个 Prompt 里能感知的工具数量是有限的给 30 个工具让模型选它容易选错。我实测算过超过 10 个工具选择准确率明显下降超过 20 个工具 复杂任务描述幻觉式调用概率急剧上升。所以架构上要做工具分组——按任务域切分先让模型选组再选工具。第二观察结果要结构化。工具返回的数据不要直接塞给大模型完事而是做一个统一的 wrapper把结果处理成结构化的文本或 JSON。比如查数据库返回的原始结果里可能有一堆跟任务无关的列裁剪掉再喂给大模型既省 token 又减少干扰。第三终止条件要硬编码。大模型自己判断“任务完成”是不够可靠的。生产系统里必须设置硬性的循环上限比如最多调用 8 次工具同时结合外部条件判断比如用户主动确认、业务流程状态机到达终态。防止 Agent 在一个错误分支里反复打转把 token 烧光。2.2 上下文管理的工程化从“全塞进去”到“按需加载”Demo 阶段最常见的做法是把所有历史消息、工具返回、系统提示一股脑全放进 context。生产系统绝对不能这样干。我采用的方案是三层上下文管理固定层系统提示词 业务规则 Agent 的能力说明。这是每次请求都带上、相对稳定不变的部分。工作层当前任务相关的中间状态、最近几轮的工具调用结果。任务推进时会动态更新。检索层需要时才按需加载的历史信息——通过向量检索、结构化查询等方式拉取和当前问题相关的内容。这个设计解决了一个核心矛盾大模型上下文窗口是有限的但业务上下文是无限的。生产里不是所有信息都需要进模型而是按相关性做裁剪。实际参数上我给一个惯例参考固定层控制在 1500 token 以内能用口诀式描述就别写小作文工作层控制在 4000 token 以内只保留当前任务直接相关的信息检索层根据相关性打分只取 top 3-5 条记录进上下文。2.3 工具层设计给 Agent 装好“手脚”工具层是 Agent 架构里离业务最近的部分也是最容易出安全事故的部分。我的工具层设计遵循三个原则原则一工具即接口契约。每个工具都明确声明输入参数结构、输出结果结构、超时时间、调用权限、费用上限。这些信息不只是给开发者看的还要通过 function calling 的 schema 传给大模型——让模型知道什么能调、怎么调、调用后得到什么。原则二失败必须有兜底。每个工具都有三层兜底第一层是重试只对幂等操作做第二层是降级比如主数据源挂了切备用数据源第三层是明确报错告诉大模型“这个工具暂时不可用”而不是给它残缺数据让它瞎猜。原则三高风险操作要加确认环节。删除、修改、支付这类操作不能只靠大模型“自觉”。我会在工具层拦截大模型发出调用意图后系统先返回“确认请求”给用户用户点了确认才真正执行。2.4 状态管理的生产化会话状态与任务状态分离Demo 里一个 Agent 的状态就是一个内存字典生产里不够。我把状态拆成两层会话状态保存的是用户和 Agent 的交互上下文比如历史对话、当前用户设置、业务上下文。它对应的是数据库里的一张会话表有明确的过期策略。任务状态保存的是当前执行单元的进行状态比如任务拆解出来的子任务列表、每个子任务完成情况、当前执行到哪一步。这个状态要支持断点续跑——进程挂了重启后能从最近的检查点恢复。分离的核心原因会话是长生命周期的任务是短生命周期的。混在一起的话一个任务执行到一半用户新发来一句话状态就乱了。生产里我会把任务状态抽出来作为独立的工作单元记录任务完成后归档。3. 多智能体协作架构模式与关键权衡3.1 不是所有场景都需要多智能体先泼一盆冷水大部分业务场景用单 Agent 完善工具链就够了。多智能体引入的问题——协作开销、状态一致性、死锁、上下文隔离——比它的收益要隐蔽得多往往要到压测和生产流量下才暴露。那什么时候值得上多智能体我的判断标准有三个角色差异足够大且稳定。比如“分析师型 Agent”查数据、做计算和“写作型 Agent”生成文案技能栈完全不重叠一个 Agent 里强行塞两种角色Prompt 互相干扰。任务可以明确拆分且子任务相对独立。比如“市场调研 Agent”负责收集信息“竞品分析 Agent”负责整理报告最后由“汇总 Agent”整合。如果子任务之间频繁交叉依赖多 Agent 反而变成灾难。需要并行处理提升效率。比如同时查五个数据源再汇总单 Agent 串行要 5 倍时间多 Agent 并行可以压到 1 倍 汇总时间。如果这三个条件一个都不占老老实实单 Agent。3.2 三种主流协作拓扑选型多智能体协作的架构模式业界实践下来就三大类中心化编排Orchestrator-Worker一个主控 Agent 负责任务拆解和分配多个 Worker Agent 执行具体子任务。这个模式最接近人类项目管理可控性最好。主控 Agent 拆完任务后Worker 之间不直接通信所有消息都通过主控转发。优点是好排查问题所有决策路径都在主控那里缺点是主控容易成为瓶颈、也被大模型的单点能力限制——主控拆任务拆不好下面全白干。流水线Pipeline任务按固定顺序经过多个 Agent每个 Agent 只处理自己负责的那一段。生产里最常见比如“输入清洗 Agent → 意图识别 Agent → 业务处理 Agent → 结果生成 Agent”。优点是链路清晰、每个环节可以被替换和单独优化缺点是流程僵硬、不适合动态变化的任务。黑板模式Blackboard多个 Agent 共享一块“黑板”共享内存空间各自往上面写自己的发现或结果其他 Agent 看到后继续处理。学术界常用工业界用得少——因为调试困难、数据竞争风险高。我给的选型建议很直接95% 的生产场景直接选中心化编排流水线适合已经固化的流程黑板模式除非你是做研究否则别碰。3.3 多智能体通信协议与消息设计多 Agent 之间通信最错误的做法是直接“让一个 Agent 的完整输出作为另一个 Agent 的输入”。消息格式要结构化。我用的消息协议长得像这样{ task_id: task_20250101_001, from_agent: researcher, to_agent: writer, intent: provide_research_material, payload: { topic: Agent架构演进, findings: [...], source_links: [...], confidence: 0.85 }, metadata: { timestamp: ..., token_cost: 1520 } }三个设计要点intent 是必填的让接收方 Agent 清楚这个消息是“供参考”还是“请执行”还是“需要审核”。没有 intent 的消息就是大模型在瞎猜。payload 宁可结构化也不要长文本。能传 JSON 数组就传 JSON 数组不要传“我查了一下发现...”。结构化 payload 让接收 Agent 能精确提取信息而不是重新理解一段自然语言。metadata 里必须带 token_cost。这样才能做成本归因——哪个 Agent 环节烧了多少钱一查便知。3.4 多 Agent 状态一致性与死锁预防多 Agent 系统里最阴间的故障Agent A 在等 Agent B 的结果Agent B 在等 Agent A 的确认互相等整个流程卡死。单 Agent 里不存在这个问题多 Agent 必须主动预防。我总结了三板斧所有跨 Agent 的等待必须有超时。任何一个 Agent 等待别的 Agent 的结果超过阈值比如 60 秒直接走超时逻辑——降级、重试或者上报人工。宁可错杀不可卡死。引入任务依赖图。主控 Agent 拆完任务后先生成一个 DAG有向无环图标明每个子任务的前置依赖。只有前置依赖全部完成后续任务才允许启动。防止“循环等待”的出现。状态集中存储。所有 Agent 的任务状态都写到同一个状态存储Redis 或数据库而不是存在各自的内存里。这样任意一个 Agent 重启都能恢复状态而且排查问题时统一查询。4. 从 Demo 到生产系统关键改造与落地清单4.1 可观测性让每个决策过程都有迹可循Agent 生产化最容易被忽略的就是可观测性。Demo 可以不看日志生产系统必须知道“这个 Agent 当时为什么选了这条路”。我落地了一套 Agent 专属的观测体系Trace 贯穿一次完整任务从开始到结束记录每个步骤大模型输入了什么 prompt、输出了什么结果、调了哪个工具、工具返回了啥、花费多少 token、耗时多少。这不仅是排查问题的基础也是后续优化 Prompt 的数据来源。决策日志除了技术日志我还会额外记录“决策原因”。让大模型每次做关键选择时附带一句简要理由输出到日志里。比如“因为用户明确要求删除所以调用确认接口”——后面发现问题时能直接看到它的思维路径。成本监控按任务、按 Agent、按时段统计 token 消耗和 API 费用。设两个阈值日累计预算阈值和单任务成本阈值超过就告警或熔断。提示可观测性建设最忌讳“先上线再补”。系统一跑起来历史数据丢光了你永远不知道线上那些诡异的 agent 行为是怎么导致的。4.2 安全加固权限、沙箱与数据隔离Agent 生产化之后安全问题的暴露面变大。大模型生成的内容不可预测工具调用也可能钻空子。我做了以下几层加固权限最小化每个 Agent 有独立的服务账号只授予完成其任务所需的最小权限。比如数据查询 Agent 只要只读权限写操作一律没有。防止 Agent 被注入恶意指令时造成大面积破坏。内容过滤与数据脱敏所有进入大模型上下文的数据先过一道脱敏流程手机号、身份证、银行卡等敏感字段提前打码出模型的内容再过一道合规过滤防止大模型生成禁忌内容。工具沙箱凡是执行代码的工具比如“让 Agent 帮用户算一段 Python”都在沙箱环境里跑限 CPU、限内存、限网络访问。生产环境里最怕的就是 Agent 生成了一段恶意代码然后直接在你的服务器上执行。人工审批节点高权限操作删除数据、发送消息、创建订单统统加人工审批。技术上空出一层“待审批任务队列”用户在页面上点确认才放行。4.3 性能优化缓存、并行与容量预估Agent 服务的性能瓶颈跟传统 API 不一样——大头不在计算在“大模型推理耗时”和“外部工具响应耗时”。生产环境的性能优化围绕这两点语义缓存把大模型的常见请求结果做缓存。判断“用户后来说的话跟之前某个问题是不是同一件事”用 embedding 相似度算——相似度超过阈值直接返回上一次的结果不再调大模型。实测在客服场景里能节省 30% 左右的调用量。并行工具调用如果任务需要调用多个相互独立的工具不要串行地一个个调。利用大模型的并行 function call 能力比如一次响应里返回多个 tool call同时发起请求总耗时能压到一个工具耗时 汇总耗时。容量预估公式这里给一个实用的估算方法。单 Agent 平均每次任务调用大模型 N 次包含推理和工具反馈 单次调用平均耗时 T 秒 预估峰值请求量 Q TPS 则满足峰值所需的并发推理请求数 N × T × Q假设一个任务平均调 6 次大模型、单次 3 秒、峰值 5 TPS那并发推理请求数就是 6 × 3 × 5 90 个并发。拿这个数去对 API 服务的配额很清楚该买多少或者该不该上本地部署的推理服务。4.4 可靠性与降级策略从好到能用生产 Agent 系统必须回答一个问题当依赖全挂了你的系统怎么办我的降级设计是分层的轻度故障某个工具超时走单工具重试 容错Agent 换一个等价工具执行。比如主数据源挂了用缓存数据源。中度故障大模型 API 频繁报错整体降级为“有限能力模式”——Agent 不再做完整规划只做客服机器人的上下文回复工具调用功能直接关闭。重度故障整个 Agent 服务不可用降级为“人工客服兜底”——把用户请求转入工单系统由人来处理。这套降级策略要提前写好并在演练环境里压一遍。真到故障发生时现场编排一定会出错。另外流式输出在 Agent 场景里也值得做大模型推理本来就慢一次性返回用户得等 5-10 秒做流式返回用户 1 秒后就能看到第一个 token 在动了体感完全不同。5. 常见问题与排查技巧实录5.1 上下文污染Agent 答非所问的隐形元凶现象Agent 在长对话后表现越来越差甚至答非所问、忘记最初任务。排查思路先看 Trace 里每次请求的 prompt 实际包含什么。十次里有八次是上下文窗口里塞了太多无关内容——早期会话的闲聊、中间某个失败工具调用的错误输出、被裁剪不彻底的大段数据都在干扰当前推理。解决经验不要把全部历史消息无脑带上只保留与当前任务相关的部分工具调用失败时把完整报错堆栈替换成一句话摘要而不是原样塞回上下文上下文要设硬上限超过就做压缩摘要历史或丢弃最旧内容。5.2 多 Agent 任务挤压并行反而更慢现象上了多 Agent 之后总耗时反而比单 Agent 串行更长。排查思路观察任务依赖图。常见问题是主控 Agent 一次性把所有子任务都发出去大量子任务在一个工具或一个大模型接口上排队形成了“伪并行”——都在等同一个下游资源谁也没跑完。解决经验控制并发上限不能让 N 个子任务同时打同一个数据库按依赖关系分波次下发第一波只发没有前置依赖的任务对慢工具加独立超时和排队策略避免集团式阻塞。5.3 工具误调用的现场急救方案现象Agent 在没被明确要求的情况下调用了高风险操作或者调用错了工具。排查思路查看调度那一刻的 prompt 和模型输出。大多数情况是 prompt 里工具描述有歧义或者系统提示没有明确说“未经确认不得调用删除类工具”。解决经验工具描述里加否定性提示“此工具仅用于 XX 场景严禁用于删除或修改用户数据”高风险工具在 schema 里加上requires_confirmation: true字段代码层做拦截事后把误调用的案例收集起来定期复盘补进 prompt 的反例库。5.4 成本失控的紧急止血现象账单出来发现某天费用飙到正常水平的 10 倍。排查思路拉出成本监控按天、按任务维度看。90% 的情况是一个异常任务触发了无限循环——Agent 在某个错误分支里反复重试比如工具报错后它用一个错误参数反复调了 30 次。解决经验硬性单任务步数上限必须设置比如最多 8 步超过强制终止对同类错误连续出现 3 次直接中断任务上报人工而不是让 Agent 换个说法继续试价格告警阈值设置到单任务级别而不是只看日账单——日账单出了事已经晚了。5.5 踩坑速查表症状优先排查点常见根因应急操作Agent 回复越来越差最近 N 轮请求的上下文内容上下文堆积、关键信息被淹没清理上下文、开启摘要压缩任务卡死无响应任务状态存储Agent 等待死锁或超时未设置手动机任务终止、补超时逻辑账单异常飙升单任务 token 统计无限重试循环触发熔断、定位异常任务工具执行报错工具入参校验模型编造了不存在的参数加强 schema 校验、加参数白名单多 Agent 互相矛盾消息 intent 字段消息格式不结构化、接收方理解偏差规范消息协议、加决策日志6. 一些个人体会回头再看从 Demo 到生产这条路上最核心的变化不是技术复杂度而是把 Agent 当成一个普通服务来对待。普通服务要有的监控、限流、权限、降级、幂等Agent 一样都不能少普通服务不讲的故事比如“为什么这么决策”Agent 反而要多记录一层。第二点体会是多智能体不是架构的勋章是问题的解决方案。先跑通单 Agent把工具链、观测、成本控制都打磨好再看哪些环节真的需要独立角色。一上来就铺多 Agent 架构的后面八成是要回退重构的。最后说一个小技巧在 Agent 的 system prompt 里我永远会加一句“如果你对用户的意图不确定直接说出来不要猜。”这句话在生产环境里救过我很多次。Demo 里 Agent 大胆猜测会显得很“智能”生产里它猜错一次就可能捅出一个事故。让 Agent 学会“承认不确定”是它从玩具变成工具的分水岭。以上这些就是我在这类项目里反复走完“设计—开发—故障—修复”闭环之后真正沉淀下来的东西。希望对正在推进 Agent 落地的你有帮助。