写 Agent 时最容易卡住的不是模型调不调得通，而是「我到底该用哪种结构」：单 Agent 加工具够不够、什么时候要拆多 Agent、记忆和规划放哪一层。这篇不讲概念史，直接按图给你几种常见架构的骨架、各自适用和不适用的情况，以及动手前该先量什么。
写 Agent 卡住人的地方，往往不是模型调不通，而是「我到底该用哪种结构」。单 Agent 加几个工具够不够，什么时候必须拆多 Agent，记忆和规划该塞进哪一层，这些问题光看概念解释没用，得有一张能对着抄的骨架图。
下面按图解的思路，把几种常见架构的骨架、适用场景和不适用的情况摆出来，再补一套「拿到别人的架构图该先看什么」的检查顺序。先量清楚自己的接口延迟和工具规模，再决定画哪张图，能省掉不少返工。
单 Agent + 工具循环：最省事，也最容易撑爆
骨架就一句话能画完：模型判断该用哪个工具，执行工具，把结果回填给模型，模型再判断下一步，直到可以给出答案。图上是一个模型框、一圈工具框、一条回到模型的箭头。适合任务步骤少、工具数量可控、不需要跨会话记东西的场景。
它撑不住的地方也很明确。工具多到一定程度之后，模型选错工具的概率会明显上去，这不是模型不行，是候选集太大。长链任务里中间结果一层层堆叠，上下文越来越长，每多一轮就多一份延迟和成本。
| 观察到的现象 | 大概率原因 | 先做什么 |
|---|---|---|
| 经常调用错工具 | 候选工具太多或描述太像 | 把工具按场景分组，或减少同时暴露的数量 |
| 轮次越多越慢 | 每轮都在重复传全量上下文 | 只回填必要字段，别整个响应塞回去 |
| 偶尔卡住不返回 | 循环没有退出条件 | 给最大轮数和一个兜底回复分支 |
- 动手前先量一遍接口延迟基线，循环几轮就慢到没法调的情况很常见；到 /tools/speed-test 量一遍更靠谱
- 工具描述写清楚「什么时候用」比写清楚「功能是什么」更影响选择准确率
- 加一个最大轮数和超时兜底，比事后猜为什么卡住省事
- 单轮任务别硬套循环，直接一次调用反而更稳
规划与执行拆开：让一个负责想、一个负责做
常见画法是两个框：Planner 先把任务拆成步骤清单，Executor 逐步执行，每步结果再回给 Planner 做修正。图上多出来一条从 Executor 回到 Planner 的边，这条边是这套架构的关键，没有它就成了开环执行。
好处是步骤可见、出错能定位到第几步，也方便在中间插入人工确认。代价是多一次甚至多次模型调用，成本和延迟都会上去，所以它适合步骤边界清楚、执行过程需要留痕的任务。
- Planner
- 只负责拆步骤和根据执行结果调整计划，不直接碰工具
- Executor
- 只负责按当前步骤调用工具，返回结果，不做全局判断
- 回边
- 执行结果反馈给 Planner 的通道，缺了它就无法修正计划
- 适用边界
- 任务本身一步到位时不要硬拆，拆了只是多一个失败点和一份账单
多 Agent 编排：谁调度、谁干活、谁验收
主流形态两种。一种是中心调度，一个主管 Agent 把任务分派给若干执行 Agent，结果汇总回主管；另一种是流水线，前一个 Agent 的输出就是后一个的输入。画在图上的区别很清楚：前者有一个汇聚节点，后者是一条链，没有回头。
不管选哪种，动手前先定三件事：共享状态由谁持有、某一步失败后重试算谁的责任、验收标准写在哪一层。这三件不定，图会越画越复杂，出问题也找不到责任边界。
- 先定状态归属明确共享上下文存在主管还是各 Agent 各存一份，验证方式是模拟一次中途失败，看恢复时读的是哪份数据
- 再定重试归属规定哪个节点负责重试、重试几次、失败后向上抛给谁，验证方式是故意让某个执行 Agent 报错，看流程是否按预期降级
- 最后定验收层验收标准放在主管还是独立检查节点，验证方式是给一个边界样例，看它是被拦住还是直接放过
不适用的情况也很实在：团队只有一两个人维护时，多 Agent 的调试成本常常高过收益。先把单链路跑通、把日志和状态看清楚，再决定要不要加第二个 Agent。
记忆与状态放哪：图里最容易被画漏的一层
短期上下文、会话记忆、长期知识库是三件不同的事，画架构图时建议分开成三个块，别挤在一个「Memory」框里。短期上下文跟着单次请求走，会话记忆跟着用户走，长期知识库跨用户共享。混在一起，后面每改一次都会牵动别处。
- 短期上下文：只保留本轮必要信息，超出的部分做摘要或丢弃
- 会话记忆：按用户或会话维度存，读的时候要有过期和清理策略
- 长期知识库：一般要外挂检索层，选型可对照 /stacks/vector-dbs 里的向量数据库目录
- 判断标准：任务跨会话、跨用户就必须显式设计记忆层；单次问答型产品可以先不做
# 检查记忆层是否真的被读写的粗略顺序
# 1. 发起两次同一用户的请求，看第二次是否带上了第一次的信息
# 2. 隔一段时间再发一次，确认清理策略生效、没有拿到过期数据
# 3. 换一个用户发同样的请求，确认没有串到别人的记忆里拿到一张 Agent 架构图，先看什么
不管图是谁画的、画得多漂亮，先按固定顺序扫三遍，能过滤掉大部分看着能用、实际上不了生产的图。
- 看环和出口先找图上有没有回路，每条回路有没有明确的退出条件，没有出口的循环就是死循环风险
- 看接口类型再看每个节点的输入输出是什么类型、什么字段，接口对不上说明这张图只是示意，不能直接落地
- 看失败路径最后看有没有重试、降级、人工接管的分支，一个都没有的图基本不能直接上生产
- 看数据流方向确认信息是从哪进、从哪出，中间有没有节点既当输入端又当输出端，这种节点最容易出隐性状态
常见问题
单 Agent 和多 Agent 到底怎么选？
先看任务能不能用一句话说清步骤。步骤固定且少的，单 Agent 加几个工具就够，调试也简单；只有任务需要并行处理、或者不同子任务要不同提示词和不同工具集时，多 Agent 才划算。团队人手少的话，别一上来就上多 Agent。
架构图画出来就一定能跑通吗？
不一定。图能帮你对齐模块边界，但节点之间的输入输出格式、超时和重试策略得另外定。建议先用一两个真实任务把最关键的链路走通，再往图里补其他分支，不然容易画出好看但跑不起来的图。
想对照现成的框架和接口再动手，去哪看？
框架和 SDK 可以到 /stacks/frameworks 翻一遍，接口清单在 /stacks/agent-apis，工具侧的选择可以看 /ai-nav/category/ai-agent。先把候选缩小到两三个，再用真实任务各跑一遍对比，比只读文档可靠。
