1. 从写提示词到设计智能体Agentic 模式到底在解决什么问题大多数人第一次接触智能体开发脑子里想的还是怎么把提示词写得更长更细。这个思路在单轮问答场景里没问题但一旦任务变成帮我调研三个竞品、整理成表格、再写一份对比分析你就会发现提示词再长也兜不住——因为任务本身需要多轮决策、动态调整路径、根据中间结果改变下一步动作。这就是 Agentic 设计模式要解决的核心问题把一次性生成变成有状态的、可循环的、能自我纠偏的任务执行流程。Ynuo Agent依诺这个项目从标题来看核心不是某个具体功能而是Agentic 设计模式详解。这意味着它关注的是一套架构层面的方法论一个智能体应该由哪些模块组成、模块之间怎么协作、状态怎么管理、工具怎么调用、失败怎么恢复。关键词虽然为空但从标题可以推断出几个核心概念Agentic、设计模式、智能体架构、任务规划、工具调用、状态管理。这篇文章适合谁看如果你已经写过一些基于大模型的调用代码但每次遇到复杂任务就变成if-else 堆砌 反复重试那这篇内容就是给你准备的。如果你刚开始接触智能体概念也没关系我会从最基础的设计动机讲起用生活化的类比把每个模式讲清楚再配上可直接参考的伪代码和实操建议。我自己的经验是智能体开发中最容易犯的错误不是模型选得不够强而是架构设计得太随意。很多人把智能体当成一个函数调模型结果任务一复杂就失控。Agentic 设计模式的价值就是给你一套经过验证的架构骨架让你在动手之前就知道这个任务该用哪种模式、状态该放在哪里、失败该在哪一层兜底。接下来我会按核心模块拆解 → 主流设计模式 → 状态与记忆管理 → 工具调用与容错 → 实操中的坑这条线展开每一部分都尽量给出可落地的思路而不是停留在概念层面。2. 依诺 Agent 的核心模块拆解一个智能体到底由什么组成2.1 感知层、决策层、执行层三层分离的必要性很多人写智能体习惯把所有逻辑塞进一个函数里读输入、拼提示词、调模型、解析输出、执行动作、返回结果。这种写法在 demo 阶段跑得通但一旦任务链路变长调试就变成噩梦——你根本不知道是哪一步出了问题。依诺 Agent 的设计思路我理解是把智能体拆成三个清晰的层次感知层Perception负责接收和预处理输入。包括用户指令解析、上下文加载、历史对话检索、外部信息获取。这一层的核心职责是把原始输入变成结构化、可决策的信息。决策层Decision负责规划下一步动作。包括任务分解、路径选择、工具选择、参数生成。这一层是智能体的大脑通常由大模型驱动但需要配合规则约束。执行层Execution负责实际调用工具、执行动作、返回结果。包括 API 调用、文件操作、数据查询、结果格式化。为什么要这样分因为每一层的失败模式完全不同分开之后才能针对性处理。感知层出问题通常是输入格式或上下文缺失决策层出问题通常是规划逻辑或提示词设计有缺陷执行层出问题通常是工具本身报错或参数不对。混在一起写你只能看到整个任务失败了分开之后日志一打就能定位到具体层次。提示三层分离不是强制要求但如果你做的智能体任务步骤超过 5 步强烈建议至少把决策和执行分开。这是我在多个项目里踩过坑之后总结出的最低要求。2.2 状态容器智能体的工作记忆该存什么智能体区别于普通函数调用的关键就是它有状态。状态容器里应该存什么我的经验是至少包含四类信息任务状态当前处于哪个阶段、已完成哪些子任务、还剩哪些待办。上下文状态用户原始指令、历史交互记录、当前对话摘要。工具状态已调用过哪些工具、返回了什么结果、哪些工具调用失败了。决策状态当前选择的策略、备选方案、决策依据。这四类信息不需要全部持久化但至少在单次任务执行周期内要保持可访问。依诺 Agent 如果采用 Agentic 模式状态容器大概率是一个结构化的对象或字典而不是简单的字符串拼接。我见过很多项目把状态直接塞进提示词里每次调用都重新拼一遍。这种做法在任务步骤少的时候没问题但步骤一多提示词会膨胀到模型无法有效处理。更好的做法是状态存在外部容器里每次只把当前决策需要的那部分状态注入提示词。这样既控制了 token 消耗也避免了模型被无关信息干扰。2.3 工具注册表为什么工具描述比工具本身更重要工具调用是 Agentic 模式的核心能力之一。但很多人只关注工具能不能调通忽略了模型能不能选对工具。这两件事的难度完全不在一个量级。工具注册表的设计要点要素说明常见错误工具名称简短、语义明确、避免歧义用缩写或内部代号模型无法理解功能描述一句话说清做什么和什么时候用描述太泛模型分不清相似工具参数说明每个参数的类型、含义、是否必填缺少示例值模型生成错误格式返回格式明确返回结构便于后续解析返回自由文本下游无法处理失败模式说明什么情况下会失败不写模型不知道要兜底我的实操心得是工具描述的质量直接决定智能体的决策准确率。如果你有两个功能相似的工具模型选错的概率会非常高。解决办法要么是合并工具要么在描述里明确写出什么时候用 A、什么时候用 B的边界条件。注意工具注册表不是写完就完了每次新增工具都要回头检查是否和已有工具产生语义重叠。我踩过的坑是加了三个查询数据的工具结果模型每次随机选一个任务成功率直接掉了一半。3. 四种主流 Agentic 设计模式及其适用边界3.1 ReAct 模式推理与行动交替进行ReActReasoning Acting是最经典的 Agentic 模式。核心思想是模型每一步先输出思考Reasoning再输出行动Action执行后获得观察Observation然后进入下一轮思考。这个模式的优点是透明、可调试。每一步的思考过程都可见出问题容易定位。缺点是token 消耗大、延迟高因为每一轮都要完整调用一次模型。适用场景任务步骤不确定、需要根据中间结果动态调整路径的场景。比如帮我查一下这个数据如果超过阈值就发通知否则记录日志——这种带条件分支的任务ReAct 模式很合适。不适用场景步骤固定、可预先编排的任务。这种任务用工作流模式更高效。3.2 Plan-and-Execute 模式先规划再执行这个模式把智能体分成两个阶段规划阶段先让模型生成完整的任务计划步骤列表执行阶段再逐步执行每个步骤。优点是规划一次、执行多次减少了模型调用次数整体效率更高。缺点是计划一旦生成就难以动态调整如果执行过程中发现计划有误需要额外的重规划机制。适用场景任务结构相对清晰、步骤可预先分解的场景。比如调研三个竞品 → 整理成表格 → 生成对比分析这种线性任务。我的经验是Plan-and-Execute 模式在实际项目中使用频率最高因为大多数业务任务都有相对固定的流程。但一定要加一个执行失败时触发重规划的兜底逻辑否则一个步骤卡住整个任务就废了。3.3 Reflexion 模式自我反思与迭代改进Reflexion 模式的核心是智能体执行完一个任务后对自己的输出进行反思找出问题然后带着反思结果重新执行。这个模式适合对输出质量要求高、允许多次迭代的场景。比如代码生成、文案撰写、方案设计。缺点是成本高因为每次反思都意味着额外的模型调用和可能的重新执行。实操中我通常会给 Reflexion 设置一个最大迭代次数比如 3 次避免无限循环。同时反思的提示词要具体不能只说你觉得哪里不好而要引导模型从特定维度检查如检查逻辑是否自洽、数据是否准确、格式是否规范。3.4 多智能体协作模式分工与协商当任务复杂到单个智能体难以处理时可以考虑多智能体协作。常见分工方式按角色分规划者、执行者、审核者。按领域分不同智能体负责不同知识领域。按阶段分不同智能体负责任务的不同阶段。这个模式的优点是每个智能体可以专注自己的职责提示词更精简、决策更准确。缺点是协调成本高智能体之间的通信协议、状态同步、冲突解决都需要额外设计。我的建议是不要一上来就搞多智能体。先用单智能体 多工具跑通确认瓶颈确实在单个智能体处理不了时再拆分成多智能体。我见过太多项目明明单智能体就能搞定非要拆成五个结果调试成本翻了十倍。模式核心思想适用场景主要代价ReAct推理行动交替动态路径、条件分支token 消耗大Plan-and-Execute先规划再执行流程清晰、步骤可分解计划调整困难Reflexion自我反思迭代质量要求高、允许多次尝试成本高、可能循环多智能体协作分工协商任务复杂、需要多角色协调成本高4. 状态与记忆管理智能体不失忆的关键设计4.1 短期记忆与长期记忆的分离智能体的记忆可以分成两类短期记忆当前任务执行周期内的状态任务结束就可以丢弃。长期记忆跨任务、跨会话需要保留的信息比如用户偏好、历史结论、领域知识。很多项目把两者混在一起结果要么是短期状态污染了长期记忆要么是长期记忆拖慢了短期决策。依诺 Agent 如果要做成可复用的框架记忆分离是必须的。短期记忆的实现相对简单一个字典或对象就够了。长期记忆则需要考虑存储方案向量数据库、关系数据库、文件系统各有适用场景。我的经验是如果只是存用户偏好和简单历史用结构化存储就够了如果需要语义检索再上向量数据库。不要为了看起来高级而引入不必要的组件。4.2 上下文压缩当历史记录太长怎么办任务步骤一多历史记录会迅速膨胀。直接全部塞进提示词不仅 token 成本高还会导致模型注意力分散。常见的压缩策略摘要压缩把历史记录定期总结成简短摘要。滑动窗口只保留最近 N 轮记录。关键信息提取只保留对当前决策有用的信息。分层存储近期记录详细存远期记录摘要存。我通常组合使用滑动窗口 关键信息提取。具体做法是保留最近 3-5 轮的完整记录更早的记录只保留结论性信息比如已确认用户需要 PDF 格式输出丢弃过程性信息。提示上下文压缩的时机很重要。不要等到超限了才压缩而是在每轮结束后判断当前上下文是否超过阈值提前处理。这样避免在关键决策时被迫截断。4.3 状态持久化任务中断后如何恢复如果智能体执行的是长任务比如需要几分钟甚至更久中途可能因为各种原因中断。状态持久化的意义在于中断后能从上次的进度继续而不是从头再来。实现要点每个步骤执行完后把状态写入持久化存储。恢复时先读取状态判断当前进度从下一个待办步骤继续。持久化的状态要包含足够的上下文确保恢复后能正确决策。这个机制在 demo 阶段容易被忽略但在生产环境里几乎是必须的。我踩过的坑是一个任务跑了 20 步第 19 步失败结果整个任务重跑前面 18 步的 API 调用全部浪费。加上状态持久化之后重跑只需要从第 19 步开始。5. 工具调用与容错让智能体在失败中继续前进5.1 工具调用的参数校验与重试策略模型生成工具调用参数时出错是常态而非例外。常见错误包括参数类型不对、必填参数缺失、参数值超出范围、格式不符合要求。处理策略分三层前置校验在调用工具前用代码检查参数是否符合 schema。不符合的直接拦截不浪费一次工具调用。自动修复对于常见错误如字符串数字转数字、日期格式转换尝试自动修复后再调用。重试机制调用失败后把错误信息返回给模型让模型重新生成参数。设置最大重试次数通常 2-3 次。我的实操心得是参数校验的 schema 要尽量严格但错误提示要尽量友好。严格是为了尽早发现问题友好是为了让模型能理解错误并修正。如果错误提示是参数错误模型不知道怎么改如果是参数 age 应该是整数当前值是字符串 25模型大概率能自己修对。5.2 工具失败后的降级与替代路径不是所有工具失败都能通过重试解决。有些失败是根本性的比如 API 下线、权限不足这时候需要降级或替代路径。降级策略示例主工具失败 → 尝试备用工具功能相似但实现不同。精确查询失败 → 降级为模糊查询。实时数据获取失败 → 使用缓存数据并标注数据可能不是最新。替代路径的设计需要在规划阶段就考虑。也就是说智能体在制定计划时应该为关键步骤准备备选方案。这增加了规划复杂度但显著提升了任务成功率。5.3 超时控制与资源限制智能体任务容易失控的一个原因是没有超时和资源限制。一个任务可能因为反复重试、无限循环而消耗大量资源。必须设置的限制单步超时每个工具调用设置最大等待时间。总任务超时整个任务设置最大执行时间。最大步骤数防止无限循环。最大 token 消耗控制成本。这些限制不是可选项而是必选项。我见过一个项目因为没有设置最大步骤数智能体陷入调用工具 → 失败 → 重试 → 再失败的循环一晚上烧掉了几百万 token。注意超时和限制触发后不要直接抛异常结束而应该走优雅降级路径——返回已完成的部分结果并说明哪些步骤未完成。这样至少用户能拿到部分价值。6. 实操中容易踩的坑与我的应对经验6.1 提示词膨胀导致决策质量下降这是最常见的问题。任务步骤一多提示词里塞满了历史记录、工具描述、状态信息模型反而抓不住重点。我的应对方法分层注入把提示词分成固定部分角色定义、工具描述和动态部分当前状态、最近记录动态部分尽量精简。优先级排序把最重要的信息放在提示词开头和结尾中间放次要信息。模型对首尾信息的注意力更高。定期清理每轮结束后检查提示词删除不再需要的信息。6.2 工具选择错误模型分不清相似工具前面提过相似工具会导致选择错误。除了合并工具和明确边界还有一个技巧在提示词里给出选择示例。比如当用户需要查询实时数据时用 A 工具当用户需要查询历史数据时用 B 工具配上具体例子模型的选择准确率会明显提升。6.3 状态不一致多步执行后状态错乱多步执行时状态可能在多个地方被修改导致不一致。比如决策层认为任务已完成但执行层还有未完成的操作。解决办法状态修改集中化。所有状态变更都通过统一的接口进行每次变更记录日志。这样出问题时可以回溯是哪一步改错了。6.4 过度依赖模型导致成本失控有些项目把所有决策都交给模型包括一些完全可以用规则处理的简单判断。这会导致不必要的模型调用。我的原则是能用规则解决的不要用模型。比如如果上一步返回为空则跳过下一步这种逻辑用代码判断就行不需要问模型。模型应该用在真正需要语义理解、模糊判断的地方。6.5 缺乏可观测性导致调试困难智能体执行过程如果不记录详细日志出问题根本没法调试。必须记录的信息每轮决策的输入和输出。每次工具调用的参数和结果。状态变更的前后对比。错误信息和堆栈。这些日志不需要一直保留但至少在调试阶段要完整记录。我的做法是开发阶段全量记录生产环境按采样率记录兼顾调试需求和存储成本。常见坑根本原因应对策略提示词膨胀历史记录无节制注入分层注入 定期清理工具选择错误工具描述边界模糊合并工具 选择示例状态不一致多处修改无统一管理状态修改集中化成本失控过度依赖模型决策规则优先 模型兜底调试困难缺乏可观测性全量日志 采样记录7. 从依诺 Agent 看 Agentic 模式的落地路径回到依诺 Agent 这个项目本身。从标题Agentic 设计模式详解来看它的定位应该是一个方法论层面的梳理和框架层面的参考而不是某个具体业务场景的实现。这类内容的价值在于让开发者在动手之前先建立正确的架构认知。如果让我给一个落地路径的建议我会这样排序第一步先用最简单的 ReAct 模式跑通一个完整任务。不要一上来就搞多智能体、搞复杂状态管理。先确认模型能理解任务、能选对工具、能根据结果调整这个基本闭环是通的。第二步加上状态管理和容错机制。任务能跑通之后再考虑失败了怎么办、中断了怎么办、成本怎么控制。这些是生产化的必要条件。第三步根据任务特点选择合适的模式。线性任务用 Plan-and-Execute动态任务用 ReAct质量敏感任务加 Reflexion复杂任务考虑多智能体。第四步持续优化提示词和工具描述。这是长期工作没有终点。每次发现决策错误都要回头检查是提示词问题还是工具描述问题。我个人在实际操作中的体会是Agentic 模式的难点不在知道有哪些模式而在知道什么时候该用哪种模式、什么时候该从简单模式升级到复杂模式。很多项目失败不是因为模式选错了而是因为过早引入了不必要的复杂度。先用最简单的方案跑通遇到瓶颈再升级这个原则在智能体开发里同样适用。最后分享一个小技巧给智能体加一个决策解释输出。让模型在每次决策时附带一句为什么选这个工具/这个路径。这不仅方便调试还能在出问题时快速判断是模型理解错了还是工具描述有歧义。这个习惯帮我省了大量排查时间。