从循环设计者到图架构师：13步路线图

大多数构建者仍在手动编排他们的智能体。他们编写一个函数，在内部调用下一个函数，分支时加个 if，失败时加个 try，然后直接发布。这样能工作。它能一直工作，直到某次运行在第九步崩溃。

他们中几乎没人能回答随之而来的问题：它到底需要重做哪些步骤？

没有验证，没有检查点，没有恢复，没有追踪。while 循环只有计数器和循环体。它无法告诉你哪个部分成功了，无法从中间重启，也无法在运行前检查。你只能通过观察执行过程来了解自己控制流的形态。

杠杆点已经转移了。这次不是从提示工程到循环，而是再上一层：从编写步骤到声明它们运行的形态。

这是从循环设计者到图架构师的13步路线图。并非来自某个厂商的博客：下面所有内容都在实际运行。引擎大约150行、没有框架，接近文末的终端输出是真实的，且本文中的每个代码块都是从生成它的文件中直接摘取的行。

三个层级：先判断你是否真的需要一张图，学习节点和边必须是什么，然后构建一个能自我检查的最小运行时。

层级 1 - 节点

01. 找出单个循环承担三个任务时的接缝

在你画任何东西之前，寻找那个在一个pass里同时做决策、执行和评估的函数。那个函数不是一个节点。它是三个尚未分离的节点。

线索是你描述中的“并”字。“它搜索并排序它们。”“它编写草稿并检查它。”每个“并”都是一个接缝。

按接缝拆分，而不是按文件结构。一个200行只做一件事的函数是一个节点。一个20行做两件事的函数是两个。

02. 每个节点一个任务，一个输出形态

一个节点之所以配得上这个名字，是因为可以不使用连词来描述它。

这就是整个节点。它接收一个主张并生成查询。它不搜索。它不决定下一步做什么。如果它做了其中任何一件事，图就会失去绕过它的能力。

输出形态和任务一样重要。每个节点返回相同的类型，一个State，区别仅在于它触及了哪些字段。这种统一性让运行时可以把节点视为可互换的黑盒。

03. 纯节点：状态入，状态出

第一道门。

一个读取全局变量、修改共享对象或写入磁盘的节点无法重放、无法单独测试、无法安全重试。层级3中的所有能力都依赖于此属性。

注意 frozen=True，注意每个集合都是元组。两者都是刻意为之。冻结的数据类使意外修改在发生时就成为错误，而不是三个节点后的谜团；不可变集合意味着检查点是一个真正的快照，而不是对底层不断变化内容的引用。

一个会改变的节点无法重放，一个无法重放的节点无法恢复。

04. 在第二个节点之前对状态进行版本化

在只有一个节点时就添加 version 字段。现在不费吹灰之力，以后很难添加，因为来自三个不同schema代际的检查点会堆在存储中。

这防止的失败很具体：你改了一个字段名，部署，然后一个恢复操作加载了旧代码写的检查点。没有版本字段，加载成功但产生无声的混乱。有了它，在边界处就会大声失败。

层级 2 - 边

05. 先静态边，只有在真正分支处才用条件边

一个工作图中的大多数边都是乏味的。搜索总是转到排序。排序总是转到写作。让它们静态，因为静态边是运行时无需执行任何东西就能验证的事实。

四行代码，然后你五分之四的控制流就成了机器可读的。只在决策真正依赖状态的地方保留条件边。在这个智能体中，正好有两个这样的地方。

06. 路由器是一个节点，而不是一个藏起来的if

这一步决定了路线图的其余部分对你是否可用。

藏在节点体内部的条件是不可见的。运行时看不到它，验证器无法遍历它，你给队友画的图只是猜测。把它提升出来，并让它声明自己能去哪里。

targets 参数是大家经常跳过的部分，但它正是产生回报的部分。一个路由器函数是不透明的：你无法在不针对每个状态执行它的情况下知道它的可能返回值。声明它们就把一个不透明的分支变成了一个可检查的边。

两行簿记代码。作为交换，第09步变得可行。

07. 每个循环都需要一个访问上限

第二道门。

循环是构建图的全部理由。它们也是图挂起的全部原因。这个智能体中的改进边会把未验证的主张送回重新研究，这在正常情况下完全正确，直到某一天什么都不能被验证，而图无限地发现这个事实。

上限不在路由器里。它在节点上。

每个节点而非全局，因为不同节点值得不同的预算。一个改进节点可能合理地运行两次。一个入口节点运行两次意味着出了大问题。

我通过删除退出条件、用始终循环的路由器替换来测试这一点：

18个节点加上一条清晰的消息，而不是一小时后在账单页上才注意到的进程。

08. 扇出需要一个声明的合并策略

当一个节点有两条都触发的出边时，你就必须回答一个问题：它们回来时该怎么办？

明确地决定并写下来。只有少数诚实的答案。取第一个完成的并取消其余。等待所有并合并。等待法定多数。取最高分的。

失败模式是不做选择。一个未声明的合并会变成你的代码碰巧有的行为，并且它在快乐路径和重试路径上会不同。

层级 3 - 运行时

09. 在运行前验证图

第三道门，也是第06步的回报。

因为每条边都是数据，每个路由器都声明它的目标，所以整个图可以在不执行任何一个节点的情况下被遍历。

我让一条边指向一个不存在的节点，并移除另一个节点的唯一出口。验证器在不到一毫秒内、没有一次API调用就发现了这两个问题，以及由此变得不可达的四个节点。

其中的每一个都是循环会在运行时、运行中途、花钱之后才暴露的错误。

10. 在每个节点后设置检查点

运行时循环中的一行。

本能是在里程碑处设置检查点，因为检查点感觉开销大。其实并不大。状态是不可变的，所以检查点是一个引用，而不是拷贝。每个节点存一个几乎不花成本，而这正是从你所在位置恢复与从近似位置恢复的区别。

11. 从最后一个好的节点恢复

诀窍在第三行。检查点告诉你状态，但不告诉你下一步去哪，因为路由决策依赖于你刚刚获得的状态。所以你重新运行路由函数（它廉价且纯），跳过节点体（它既不是）。从检查点5恢复本次运行重放了14个节点而不是19个。在真实的智能体中，你跳过的节点是那些做了模型调用的。

12. 追踪就是重放的图

对于一个图来说，可观测性不是日志记录问题。它从运行时中免费获得，因为运行时已经知道每一步的节点名和耗时。

四个字段。它们给你的是一个按顺序访问的节点列表，这与图中经过的路径是一回事。你不需要从日志行中重建发生了什么。追踪就是路径。

13. 把失败作为边送回

最后一步是让它成为系统而非图表的步骤。

当一个节点抛出异常时，运行时不会停止。它把错误写入状态，并让图基于此路由。

失败变成了一个值，一个值可以被路由。这正是让 after_verify 可以把出错的运行直接发送到发布、而不是进入另一个会以同样方式失败的改进循环的原因。

同样的原则也适用于成功但不完整的情况。上一篇文章第12步中的未验证主张变成了这张图中的新主张：

那单个节点是闭合图的边。

结论：杠杆已经改变

但诚实的版本不是每个人都应该去构建图。大多数智能体暂时还不需要。直到控制流真正基于状态分支，直到有一个你脑子里无法把握的循环，直到一次运行中途失败比完全重启更昂贵，直到不止一个人需要理解路径。缺少其中任何一个，图就只是形式：你为描述一条直线而付费给运行时。

测试很直接。如果你能在餐巾纸上画出智能体的控制流并确信它是完整的，那你有的就是一个循环，而循环就是正确答案。如果你不能，那你就已经有一张图了。你只是没有把它写下来让运行时读取。

如果你通过了测试，那就从小处构建。一个状态schema。一个纯节点。一个声明的路由器。一个访问上限。在设置检查点之前确保节点可重放。在验证之前确保边已声明。在构建恢复之前让验证工作正常。顺序在这份路线图中比其他任何地方都重要，因为层级3中的每个能力都是层级1中做出的决策的结果。跳过去，你得到的只是一个信心十足地报告它实际上看不到的系统的运行时。

关键不在于智能体工作变得更简单了。而在于杠杆点再次移动了。画出图。保持工程师本色。