上个月我在团队内部做了一次Agent用例的结构审计翻遍了各个项目里的Agent实现结论很扎心同样一个查资料—归纳—出报告的需求有的开发者把全部工具逻辑塞进一大段system prompt有的用三层if-else硬编码工具调度还有的干脆不做记忆、每次对话都从零开始。效果时好时坏代码风格则完全没法互相接手。后来我把团队里沉淀的Ynuo Agent依诺那套Agentic设计模式梳理成文就是为了还清这笔设计债——让Agent开发不再靠个人手感而是有一套可以按图索骥的模式地图。这篇文章会从Ynuo Agent落地过程中最常踩的坑出发拆解几类核心Agentic设计模式的原理、适用边界和工程化细节。适合正在做Agent应用、想提升多步骤任务稳定性的开发者也适合那些已经把Agent跑通demo、却在生产环境里反复翻车的团队参考。我会尽量少讲空泛的概念多给能直接抄走的思考路径和代码骨架。1. 别急着堆代码先搞清Agentic设计模式到底在解决什么问题1.1 Agent不是函数它最大的特点就是不可控的中间过程传统软件开发里我们写一个函数输入确定、输出可预期。但Agent不一样它通过大模型在每一步自主决定下一步干什么中间存在大量不确定性今天模型会选择调工具A明天可能就调工具B后天可能在同一个工具上给出完全不同的参数。这种不确定性放在demo里没所谓一旦要上生产问题就来了——不可复现、不好排查、没法灰度。我见过很多团队一上来就追求万能Agent希望一个系统能做所有事。结果prompt越写越长工具越挂越多模型在超长上下文中逐渐迷失最终表现连单一用途的小脚本都不如。Ynuo Agent的经验恰好相反先把业务流程拆成明确的阶段每个阶段用哪种设计模式去承载再动手写代码。Agentic设计模式的核心价值就是给这种不可控的中间过程套上可控的结构骨架让模型在框架划定的轨道里做选择而不是在无限可能性里裸奔。1.2 Ynuo Agent的定位规范先于框架Ynuo Agent并不是一个全新的Agent框架它更像是一套设计约定加上薄薄的封装层。我们刻意避免了框架万能论因为底层模型迭代太快绑定太深反而会拖慢演进。我们的做法是把团队实践里验证过的高频套路提炼成三类模式库——单Agent循环、多Agent协作、带状态的长时间任务然后围绕这三类模式补齐工具层和记忆层的接口规范。这样做最大的好处是新人上手快只要理解了几种模式的适用场景就能读懂系统里任何一个Agent在干什么新功能开发时也只需要选择匹配的模式而不是从零设计一套结构。后面我会逐个模式展开讲先给一张全貌表模式适用场景核心难点Ynuo Agent里的落地形态ReAct循环短流程、工具调用频繁、目标单一工具结果如何反馈给模型单Agent推理-行动-观察循环Plan-and-Execute长任务、多阶段、需要整体规划计划如何生成与动态修正计划器执行器分离状态机检查点任务随时可能中断、需要续跑状态如何持久化与恢复阶段状态机存储快照多Agent协作角色分离、对抗校验、专业分工通信协议与结果汇合主控-执行者-观察者1.3 模式不是越多越好先建立最小可用循环很多团队上来就搞多Agent编排几个人物角色互相聊天看着很热闹实际吞吐量低、成本高、问题还难排查。Ynuo Agent在做模式选型时有一条铁律能用一个Agent解决的绝不用两个。模式的复杂度要跟着问题的复杂度走而不是跟着技术兴奋度走。先跑通最小可用循环遇到明确的瓶颈再升级模式这个顺序非常重要。2. ReAct循环让Agent想一步、走一步、看一步2.1 推理-行动-观察的闭环究竟是怎么工作的ReActReasoning Acting是目前最基础也最高频的Agentic设计模式。它的思路特别朴素把Agent的决策过程拆成交替出现的思考、行动和观察。模型先根据当前上下文推理现在该做什么然后输出一个具体的行动通常是调用某个工具工具执行返回结果后这个结果再作为观察回到上下文里供模型进行下一轮推理。用伪代码看非常清晰def react_cycle(user_request, tools, max_steps8): context [{role: user, content: user_request}] for step in range(max_steps): # 推理让模型决定下一步 response llm_call(context) action parse_action(response) # 行动执行工具调用 if action.type final_answer: return action.content observation execute_tool(action, tools) # 观察把结果放回上下文 context.append({ role: assistant, content: response }) context.append({ role: tool, content: observation }) raise MaxStepsExceeded()这个循环看似简单但工程化之后几乎每个环节都有细节。比如行动解析模型输出的格式不稳定是最先遇到的问题。我们用结构化约束而不是正则来兜底要求模型输出严格的JSON格式字段里包含thought、action、action_input三部分解析失败就重试一次重试还失败就把你的格式不对作为观察结果塞回去引导模型自纠。实测下来这种做法比纯正则硬匹配的容错率高很多因为模型能看到自己的错误输出并主动修正。2.2 Ynuo Agent里工具调用的三个关键设计第一个关键设计是工具描述要写成触发条件使用说明二元结构。只写这个工具可以做某事远远不够模型在推理时最需要的是判断当前这个场景到底应不应该用你。我们在工具描述里加了一个use_when字段用一两句话说明典型触发场景比如当用户提到本周的销售数据时使用模型命中率提升非常明显。第二个关键设计是参数Schema必须严格校验不合法就不执行。工具返回缺少必填参数这样的错误远比让工具内部抛一个诡异异常更好排查。第三个关键设计是工具结果要设置上限大结果集必须截断。模型窗口是有限的你一次塞回10万字的工具返回模型基本就废了。我们通常保留摘要或关键字段必要时单独提供二次查询入口。这三个设计听起来都不难但它们决定了ReAct循环能否在真实场景里稳定运转。没有这几层保护循环大概率会在第三步就陷入格式错误或上下文溢出。2.3 工具失败时怎么办把错误本身当作观察这是ReAct模式里最容易被忽略的部分。很多初版实现里工具一旦抛异常整个循环就终止了。这在demo里无所谓生产环境里工具超时、接口限流、参数非法是常态。Ynuo Agent的做法是把工具错误捕获后结构化地塞回上下文让模型基于错误信息决定下一步是修参数重试、换一个工具还是直接放弃并告诉用户。这种做法有一个额外收益模型逐渐学会识别不可恢复的错误而不是盲目重试。我们设定最多重试两次第二次失败就必须降级处理——要么切换到兜底方案要么明确告知用户当前能力不足。没有这个上限ReAct很容易变成死循环烧钱一次长任务烧掉几百次调用最后结果还是错的。3. Plan-and-Execute长任务不再是走一步看一步3.1 什么时候必须放弃纯ReActReAct模式有一个天然局限它只盯着当前这一步缺乏全局视野。一个6步任务模型每一步都做得合理但第4步基于第3步的中间结果做了一个局部最优决策可能导致第6步整体偏离最初目标。短流程里这种偏差还能容忍一旦超过5步ReAct的输出质量就会明显下降。我们在处理从十几个数据源收集信息然后按指定维度整理成报告这类任务时最初坚持用ReAct结果经常做到一半跑偏——模型会沉浸在某个数据源的细节里完全忘了最终要产出什么。后来我们引入了Plan-and-Execute模式先让模型把大目标拆解成子任务清单然后逐项执行。这个拆解动作看起来多了一层调用但对长任务的稳定性提升是质的飞跃。3.2 Ynuo Agent的计划数据结构与动态修正机制计划本身也需要一套结构。Ynuo Agent里计划描述为一个步骤列表每个步骤带依赖关系dataclass class PlanStep: step_id: str description: str dependencies: list[str] status: str # pending / running / completed / failed result: str | None None dataclass class Plan: goal: str steps: list[PlanStep]这里有一个很关键的设计决策计划生成之后是可以被改的而不是一次定死。我们允许执行过程中通过重规划触发器来局部调整计划。触发条件包括三条某一子任务连续失败超过阈值执行结果与预期假设明显不符步骤数量超出预估太多。触发后我们不会让模型重新生成整份计划而是只对失败步骤之后的部分做修正尽量保留已完成工作的成果。动态修正机制在工程上如何实现我们在每次步骤执行完成后提取已完成步骤摘要失败原因剩余目标组织成一段重规划上下文发给模型重新输出后续步骤。这比全量计划重新生成便宜得多也更稳定。实测中有一个重要发现重规划最好只允许在特定检查点触发而不是每一步都允许。否则模型会频繁推翻自己的计划导致收敛困难。3.3 计划器与执行器分离避免互相污染Plan-and-Execute模式的关键工程决策是把生成计划的大模型调用和一步步执行的大模型调用彻底隔离开两者使用不同的上下文窗口。计划器只需要看到整体目标、历史摘要、当前已完成的步骤结果执行器只需要看到当前步骤的目标和相关上下文。这么做的原因很实际如果同一个上下文既装计划又装执行中间结果窗口很快会被撑爆而且模型容易在规划模式和执行模式之间切换时表现不稳。分离之后两个环节都可以做针对性优化——计划器的prompt强调全局性、完整性、依赖关系合理性执行器的prompt强调聚焦、精确、不被无关信息干扰。4. 状态机与检查点Agent记忆如何不丢4.1 为什么Agent天然容易失忆很多人误以为只要把历史消息存下来Agent就有记忆了。实际上上下文窗口有限一旦对话轮次变多早期的关键信息会被挤出窗口模型就会失忆。更麻烦的是长任务执行过程中如果出现进程崩溃、接口超时、手动中断整个任务的中间状态可能全丢。这也是Agent上生产后最常见的故障类型任务跑了一小时中途崩了所有进度归零。Ynuo Agent从一开始就把状态持久化当作一等公民对待。我们没有把Agent做成无状态的一次性调用而是用状态机把任务阶段显式管理起来。每一个任务实例都有一条生命周期created → planning → executing → finalizing → done以及一系列异常状态waiting_retry、failed、aborted。状态流转必须显式记录不允许静默跳跃。4.2 检查点快照记录什么、什么时候记录我们的检查点快照包含四层内容任务基本信息、当前阶段状态、上下文摘要、已完成的中间结果引用。这里有一个经验完整上下文不值得全量存。因为上下文很快会膨胀全量序列化存到数据库里恢复时重新灌给模型成本极高且大部分内容都是冗余。我们改为存上下文摘要由单独的摘要节点在每次检查点创建时生成极简版历史恢复时拿摘要加上最近的原始轮次作为新上下文启动。检查点的创建时机也有讲究。我们配置了三种触发方式每完成一个子任务就记录运行时长超过阈值时记录检测到工具异常时记录。第三种最重要因为工具异常往往意味着接下来要进入重试逻辑此时的状态丢失代价最高。4.3 从检查点续跑幂等设计与至少一次语义状态恢复的工程难点在于重复执行的安全性。如果Agent在步骤3崩溃恢复后重新执行步骤3而步骤3是一个发送通知之类的有副作用的操作那就可能造成重复发送。Ynuo Agent的解法是给每个步骤设计幂等键工具层记录已执行的操作标识重复调用时直接返回之前的结果而不触发副作用。对于没有天然幂等能力的外部系统我们做了个妥协接受至少一次语义但保证每个外部调用都带唯一请求ID供外部系统去重。这一步在实际部署里帮了大忙很多第三方API不支持幂等带请求ID至少能让对方有能力识别重复。没有这套设计任何长时Agent任务都无法安全地加入自动重试。5. 多Agent协作主控、执行者、观察者的拆分配置5.1 单Agent的瓶颈与多Agent的引入时机单Agent模式在两类场景里会撞墙一是任务需要多个专业领域知识上下文里混杂不同知识体系会让模型决策混乱二是结果必须经过批判性审查让同一个模型既当选手又当裁判天然存在自我强化偏差。Ynuo Agent引入多Agent协作不是跟风而是被这两类问题逼出来的。我们的经验是多Agent的第一版优先采用主控-执行者架构一个主控Agent负责拆解任务、调度子任务、汇合结果多个执行者Agent各管一块具体工作。引入时机取决于失败模式——只有当单Agent方案下输出内容被误采纳或领域知识互相干扰的问题反复出现时才值得上多Agent。否则先保持简单往往更划算。5.2 主控-执行者架构里通信协议怎么设计多Agent之间通信不推荐让Agent直接对话。直接对话看着灵活但不可控性爆炸两个模型来回拉扯可能10轮以后还在原地打转。Ynuo Agent的通信协议本质上是一个任务黑板模型主控Agent把子任务写成结构化工单发布到任务队列执行者Agent消费工单完成后把结果写回指定槽位主控Agent在检查点收集全部槽位结果。Agent之间的对话退化为对同一块黑板数据的读写。工单结构长这样dataclass class WorkOrder: order_id: str task_type: str input_data: dict priority: int status: str result: dict | None None这样做有三个好处每个Agent只依赖数据契约不依赖其他Agent的prompt实现细节任务全过程可观测任何时候都能看到工单到了谁手里、完成了没有失败隔离很干净某个执行者反复失败时主控可以直接换一个执行者而不用处理复杂的对话历史。5.3 观察者Agent最容易被忽略的质检角色执行者输出结果后直接汇入最终答案是危险的。我们在实践里加入了观察者Agent它不直接参与生产而是对执行者结果做独立校验。校验维度主要有三个与原始需求的对齐程度、内部逻辑自洽性、是否存在幻觉性断言。观察者返回的校验结论会作为附加信息送回主控由主控决定是采纳、退回重做还是降级处理。这里有一个成本控制的建议观察者的模型可以比执行者低一档但它的prompt必须更严格。我们发现性能更小的模型在挑错这件事上表现往往很好尤其是在事实一致性检查上反而比大模型更苛刻。把质检单独剥离出来尽管多了一次调用却显著提高了最终输出的可信度——这个交易非常划算。6. 生产环境下的模式取舍与调优经验6.1 模式选型的四步决策法总结Ynuo Agent的实践经验面对一个新需求我推荐按顺序做四个判断任务步数评估预估需要几步完成。小于3步直接单次调用即可连ReAct都嫌重3到8步ReAct模式足够超过8步或步骤数量不确定考虑Plan-and-Execute。失败代价评估某个步骤失败后是重新执行该步骤就行还是会导致前面步骤前功尽弃如果是前者ReAct足够如果是后者必须在关键节点加检查点。领域耦合度评估任务是不是需要从多个差异很大的知识领域取信息如果是多Agent按领域拆分比单Agent硬扛更稳定。结果审查评估最终产出被直接使用还是经过人工复核如果直接被下游系统消费强烈建议加观察者Agent做独立校验。这套决策法看起来简单但真正按它执行能避免至少一半的过度设计问题。6.2 可观测性建设Agent运行时日志该记什么Agent的调试难度比传统程序高一个量级因为中间决策来自模型无法用断点单步调试。Ynuo Agent为此设计了专门的结构化日志。我们在每个Agent的每次决策循环里固定记录step_id、thought、action_type、action_input、observation_summary、token_cost、latency七个字段。这些字段单看都不起眼组合起来能回答一个核心问题这个Agent当时为什么做出这个选择。除了决策日志还需要一个全局轨迹视图。多个Agent协作时单独看每个Agent的日志无法理解整体任务为什么卡住。我们按照订单ID聚合所有Agent的决策轨迹形成时间线视图。排查问题时先在时间线上找到卡点再下钻对应Agent的单步决策日志。实测下来这套组合让平均问题定位时间从小时级降到了分钟级。6.3 守住回归底线用最小评估集防止修好东墙倒西墙Agent系统最折磨人的是非确定性回归——改了一版prompt核心场景跑通了三个没注意的方向却悄悄变差了。解决这个问题只有一个土办法维护一个小而准的评估集。Ynuo Agent的评估集不大大约二十条覆盖典型场景、边界场景和失败恢复场景的任务用例每次改动后全量跑一遍对比输出质量。评估不能只看最终答案对不对还要看中间过程是否合理。我们把评估拆成两个指标任务完成率和决策有效率。决策有效率指模型的行动里有多少是实际有价值的这个指标对排查模型的无效绕弯特别敏感。如果一次改动后任务完成率没变但决策有效率明显下降说明模型开始走弯路了需要尽快调整。这个指标我们维护了一年是判断系统健康度最可靠的一把尺。最后再分享一点个人体会Agentic设计模式的本质不是让你能搭出多炫酷的智能体而是让你在智能体不可控的行为里找到秩序。Ynuo Agent这套东西未必适合所有团队直接照搬但先定模式、再写代码、预设失败路径这三个原则我认为适用于任何一个认真做Agent落地的项目。如果你的Agent也正在生产环境里反复翻车不妨先停下来给当前的实现画一张模式图——你可能会发现问题根本不在模型不够强而是结构在裸奔。