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 模式：推理与行动交替进行
ReAct（Reasoning + 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 模式的难点不在"知道有哪些模式"，而在"知道什么时候该用哪种模式、什么时候该从简单模式升级到复杂模式"。很多项目失败不是因为模式选错了，而是因为过早引入了不必要的复杂度。先用最简单的方案跑通，遇到瓶颈再升级，这个原则在智能体开发里同样适用。
最后分享一个小技巧：给智能体加一个"决策解释"输出。让模型在每次决策时附带一句"为什么选这个工具/这个路径"。这不仅方便调试，还能在出问题时快速判断是模型理解错了，还是工具描述有歧义。这个习惯帮我省了大量排查时间。
