agent-architecture-lens

Agent 架构视角

使用此技能来审查 Agent 的控制流、状态和故障处理结构。ReAct 循环——推理、行动、观察、重复——是每个 Agent 的基本单元，而且是正确的。但它并不完整：随着运行时间变长、过程变得更加复杂，它不会以某种戏剧性的故障形式崩溃，而是会悄然变得不再够用。

循环是一个只有一个节点、且有一条边指回自身的图。主导原则是架构应与任务的形态和持续时间相匹配——而不是追求图表的优雅。

每次审查都由两个核心原则锚定。图并不代表升级：结构是对实际遇到的需求的响应，因此没有此类需求的任务应保留循环，并在审查中明确说明。以台账为准，而非记录稿：必须经得起任何情况的进度，都应保存在持久化产物中，而不是模型希望自己能记住的消息历史中。审查时要明确说出这两点。

第一轮：六个信号

在建议任何结构之前，按编号说明六个信号中哪些触发了：

1. 状态超出一个上下文窗口。 运行需要跟踪的信息超出了模型工作记忆的容量。
2. 运行必须能从崩溃中恢复。 执行过程中丢失进度不可接受——可能损失数分钟工作、实际 API 开销，或让用户一直等待。
3. 运行中需要人工审批。 Agent 继续执行前必须由人审核，而审核可能需要数小时。
4. 工作流存在并行分支。 存在真正独立、且不应串行执行的子任务。
5. 多个模型或 Agent 必须协作。 不同步骤需要不同的模型、工具或权限。
6. 执行必须可重放且可审计。 事后会有人追问“这次运行具体发生了什么？”

没有信号触发 → 建议保留循环并停止。要直截了当地说："没有信号触发；继续使用循环——图并不代表升级。" 在此处增加结构只会带来延迟和测试负担，却没有任何收益。

有一个或多个信号触发 → 每个信号都指出设计必须提供的具体机制，以下检查只验证这些机制。不要引入其他内容。

逐级升级

结构按以下顺序增加，因为每一级的代价都高于前一级。每一级都必须由实际触发的信号来证明其必要性。

1. 外置状态。 将运行必须记住的信息从消息列表中移出，存入具有命名字段和声明默认值的类型化结构中。收益最高、成本最低——模型不必再翻找自己之前的推理，才能找到六步前生成的值。
2. 添加检查点。 每步执行后写入状态，以便崩溃后恢复，而不是从头开始。这才是真正从循环转向图的变化。
3. 将职责拆分为命名步骤。 当步骤需要不同的模型、工具、权限或错误处理方式时，就进行拆分。一步一职。
4. 分支并行化。 放在最后，且只用于真正独立的工作或真正不同的执行路径。

信号 1 和 6 通常在第 1 级就能满足。信号 2 和 3 需要第 2 级。信号 5 需要第 3 级。只有信号 4 需要第 4 级。

实现审视

按顺序检查以下五个方面。跳过未触发相应信号的方面。

状态

检查运行会记住什么、信息存放在哪里、由谁写入，以及状态增长的代价。

请问：

1. 哪些值必须在当前上下文窗口结束后继续保留，哪些是真正的临时信息？
2. 每个持久化字段是否都有类型、默认值，以及两个步骤同时写入该字段时的处理规则？
3. 如果状态丢失，能否从持久化输入中重建，还是它是唯一副本？
4. 大型数据负载是内嵌在状态中，还是存放在外部存储中并通过 ID 引用？
5. 有什么机制限制消息历史的增长——例如达到令牌阈值时执行摘要步骤，还是完全没有限制？

重试

模型绝不能决定是否重试。 将重试次数写在模型的推理过程中，会导致两种失败模式：对已失效的端点尝试 15 次，以及只尝试 1 次后就编造结果。

请问：

1. 尝试次数是否记录在某处，供下一次执行读取，还是每次都从记忆中重新推导？
2. 计数器是否在尝试之前递增？如果在尝试过程中崩溃，这次尝试仍必须计入。
3. 达到次数上限时的备用路径是什么——明确指定的升级处理，还是无人处理的死胡同？
4. 重试步骤是否能区分暂时性故障和永久性故障，还是对两者一概重试？
5. 是否存在某条路径，使失败的工具可以在没有外部次数上限的情况下再次调用？

终止

每次运行都需要三个退出条件：成功、重试次数耗尽，以及硬性上限——最大步数、最大令牌数、支出上限或截止时间。三者中只有两项，就等于给无界运行披上了停止条件的外衣。

请问：

1. 哪个条件会让本次运行成功结束？它是一个状态值，还是模型认为自己已经完成？
2. 如果工作无法完成，会发生什么——有明确的失败退出条件，还是会陷入循环？
3. 硬性上限是什么？它使用的单位是否无需模型配合就能计数？
4. 谁会发现触及上限，以及他们会看到什么？
5. 对于任何长时间运行或需要付费的任务，是否设定了支出上限？是否已告知用户？

副作用

将决策（“应该发送这封邮件，内容如下”）与执行（“发送邮件”）分开。决策步骤可以安全重放；执行步骤必须具有幂等性，因为副作用发生后、检查点写入前发生崩溃，会导致恢复时重放该步骤。

请问：

1. 哪些步骤会在本次运行之外写入数据——消息、提交、PR、工单、付款或部署？
2. 每个步骤是否都带有一个稳定键，在产生副作用_之前_写入状态，并在重新执行时于开头进行检查？
3. 执行决策是否与实际操作分别记录，以便重放时只重新执行后者？
4. 是否可能有两个并行步骤写入同一个状态字段，或调用同一个受速率限制的 API？
5. 工具是否按步骤限定权限，使只应读取的步骤无法写入？

恢复与关卡

请问：

1. 人工关卡会在哪里暂停运行？审批能否在进程重启后保留，还是会随对话轮次一起消失？
2. 恢复运行时，如何识别该运行，又如何找到要从哪一步继续？
3. 是否有崩溃恢复测试——在运行过程中将其终止，重启后断言它从正确步骤恢复，且计数器正确？这是必需的集成测试，不是可选项。
4. 执行跟踪能否回答“运行了什么、按什么顺序运行、输入和输出是什么”？
5. 如何清除旧检查点，审计窗口有多长？

图的成本

推荐结构时要说明成本——这正是让该视角在普通循环场景下返回 proceed 的依据。

成本	表现
延迟	每个检查点都是一次写入，每个边界都是一个序列化周期——确实存在，但通常不可见；对于亚秒级交互式任务，这一点很重要。
协调	并行分支需要汇合点，而且每个分支都会独立失败——所需的错误处理代码比循环版本更多。
路径爆炸	三条条件路由最多会产生八条执行路径，而每条路径都需要测试。
架构设计	每个状态字段都需要类型、默认值和写入规则；设计不当，错误就会在每个步骤中暴露。
维护	重试逻辑、回退路由、错误处理程序和上限，都是循环原本不需要的新代码。

图之所以更可靠，恰恰是因为它不把编排交给模型信任。为这种可靠性付出的是工程工时。

在 design-gate 下，使用调用方的规范门禁结果。这会取代独立输出和编辑机制。将视角特有的结论放在 findings 或 review_focus 中，并使用稳定的 finding ID。在访谈中，将决策字段写入现有的决策记录。

独立输出约定

返回：

1. verdict：proceed 或 revise。
2. signals_fired：按编号列出适用的六项信号，每项附一行依据。空列表是有效且常见的结果。
3. blocking_findings：需要修改计划的关键发现（proceed 时为空）。
4. advisory_findings：值得在实现过程中保留的非阻塞观察。
5. required_changes：编号排列的计划修订项（仅在 revise 时填写）。

当此视角会改变工作时，用一行说明：

Agent architecture lens: signals [n] fire, so [mechanism owed]; [main risk], bounded by [ceiling].

注意事项

1. 不要因为设计看起来更复杂、更正式，就推荐使用图。没有信号就意味着应该使用循环。
2. 不要把并行当成高明的体现——它会扩大测试范围，而且应是最后一级，而非第一级。
3. 不要接受“Agent 会在完成后停止”作为终止条件。必须有三个退出条件。
4. 不要接受只在文字中声明重试上限。如果没有模型之外的机制统计尝试次数，就不存在上限。
5. 不要让检查点无限累积——无界的状态增长会导致缓慢的服务中断。

参考资料

按需加载，不要预先加载：

• references/failure-modes.md — 症状 → 结构性补救措施，并说明无界运行实际上会持续多久。
• references/state-and-checkpoints.md — 类型化状态架构设计、检查点频率、TTL 和清理。
• references/topologies.md — 循环、路由器、编排器-工作者、评估器-优化器，以及带汇合点的并行扇出。