第18章 代码即图:构建 Agentic 系统的新范式
TL;DR Graph 库是个错误。你的代码本身就是 graph。 代码通过类型标注获得类型安全,通过 async 获得并行执行,通过沙箱外的 Temporal 和沙箱内的 Monty 获得持久化执行。
引言
最近关于"用 graph 和循环驱动 agent,还是用 prompting"的讨论很多。有人认为 prompting 已经过时了:应该去构建 graph 和循环,让 agent 在此基础上自我构建,六个月内 graph 工程将成为严肃 agentic 系统的默认架构。
我只同意其中一半。人类手写代码的时代确实在终结,开发者的工作会变得更难也更有趣:定义问题。选好 agent 要优化的指标和必须遵守的约束,写出衡量它们的 evals,然后让 agent 能快速便捷地迭代。这比写代码本身更有价值。
另一半我认为是错的——作为一个亲手写过 graph 库的人,我这么说。大多数人熟知的 graph(把节点和边交给一个库,由它替你遍历)是个错误。唯一行得通的 graph 就是代码本身。
很长一段时间,我以为这只是因为我强烈反感 LangGraph 及其对类型安全的漠视。现在我确信不是:在节点边界实现持久化、支持节点并行执行的 graph,从根本上与类型安全不相容——而且反对 graph 的理由远不止类型安全这一条。
但当 graph 由 agent 定义、而 graph 就是代码时,问题就变成了:这份代码怎么运行?这正是我们构建 Monty 的原因——一个专门为此打造的沙箱化 Python 解释器。
我说的"代码即 graph"是这样的。reviewer 和 summarize 是两个子 agent,各自是一个返回类型化结果的 async 函数,调用它们的函数如下:
async def review_comments(comments: list[str]) -> str | None: reviews = await asyncio.gather(*(reviewer(task=c) for c in comments)) issues = [r.issues for r in reviews if r.issues] if issues: return await summarize(issues)
扇出、汇合、分支。这就是一个 graph,同时也是个 Python 函数:ty 会检查 summarize 能接受 issues,调用栈就是运行状态,模型用一次工具调用就能写出来。这是纯粹、标准的 Python,agent 很容易写出。Monty 能安全地运行它,并且可以在每次外部函数调用(此例中是 reviewer 和 summarize)处做快照和恢复。
每个 graph 都在和调用栈作对
你的程序本来就有状态:变量里的值、执行到了哪里、哪些调用在等待返回。graph 库会再引入一套对这份状态的表示,然后你得保证它和代码保持一致。
if 是分支,for 是循环,函数调用是边,except 是失败边,包住 try 的 for 是重试,await asyncio.gather(...) 是扇出加汇合。调用栈记录你在哪,stack trace 告诉你怎么到的那里。它自带调试器、profiler、类型检查器,而且每个程序员、每个模型都已经懂它。它的正式名称叫结构化控制流,其他人都叫它代码。
graph 库把这些全都重建了一遍,而且更糟。节点是你没法调用的函数,边是注册调用,状态是一个由 reducer 合并的 dict,或者一个你无法掌控其修改时机的 dataclass,而不是局部变量。"这次运行现在跑到哪了"的答案来自库自己的迭代器,而不是你可观测性工具里的 trace。
这是我们文档里的扇出示例,我特意选的:
import asyncio from dataclasses import dataclass
from pydantic_graph import GraphBuilder, StepContext, reduce_list_append
@dataclass class SimpleState: pass
async def main(): g = GraphBuilder(state_type=SimpleState, output_type=list[int])
@g.step async def generate_list(ctx: StepContext[SimpleState, None, None]) -> list[int]: return [1, 2, 3, 4, 5]
@g.step async def square(ctx: StepContext[SimpleState, None, int]) -> int: return ctx.inputs * ctx.inputs
collect = g.join(reduce_list_append, initial_factory=list[int])
g.add( g.edge_from(g.start_node).to(generate_list), g.edge_from(generate_list).map().to(square), g.edge_from(square).to(collect), g.edge_from(collect).to(g.end_node), )
graph = g.build() result = await graph.run(state=SimpleState()) print(sorted(result)) #> [1, 4, 9, 16, 25]
asyncio.run(main())
同一个程序:
import asyncio
async def square(n: int) -> int: return n * n
async def main(): squares = await asyncio.gather(*(square(n) for n in [1, 2, 3, 4, 5])) print(sorted(squares)) #> [1, 4, 9, 16, 25]
asyncio.run(main())
第二段不用加任何东西就是类型安全的,可以在里面打断点,扇出只要一行。人和模型几秒就能读懂。第一段是我去年还引以为豪的那种东西。
图表仍然有用——它是你为代码画的东西,所以 pydantic-graph 才支持渲染 Mermaid。
对 agent 来说情况更糟,因为 agent 需要的控制流很少能在运行前就确定。前面那个论点有部分是对的:工作的单位是一个带检查的循环,围绕任务来设计。由人类提前接好线的固定 graph,就是绕了一圈的 prompt。
类型安全、快照、并行:三者只能取二
graph 界也有一条 CAP 定理。做 graph agent 的人想要三样东西:
类型安全,让类型检查器发现节点 A 给了节点 B 接不住的东西; 并行执行,能扇出再汇合; graph 状态的快照,运行崩溃后从上一个节点恢复,而不是从头再来。
我没找到哪个 graph API 能三者兼得,自己试过之后也不觉得做得到。
类型安全指节点以普通对象的方式读写状态,节点的出边就是它的返回类型,类型检查器两者都能校验。并行指多个节点同时在跑。快照指在节点边界处,整个运行是一个可序列化的值,从它恢复的结果和不中断的运行完全一致。
最初的 pydantic-graph 里,快照就是 NodeSnapshot(state, next_node):状态加上当前位置。它有类型、可恢复,因为"当前位置"只是一个节点。
加入并行之后,"当前位置"变成一组在途节点和填了一半的汇合点,而这些节点还在同时改同一个状态对象。假设其中一个做了三次更新,快照写入时,三次更新完成了几次?从它恢复,第二次更新可能跑两遍,也可能一次都没跑。除非处在没有任何节点在途的 barrier 时刻,否则不存在状态是完整一致值的瞬间——节点边界就不再是运行边界。你可以只在 barrier 处做快照,但那一步内部崩溃就会丢掉这一步,而写到一半崩溃的节点已经污染了你正要保存的状态,且因为改动是原地写入,无法撤销。你也不能只重跑在途节点:runner 不知道某个节点是否碰过外部世界,重跑两次是否无害。邮件要么发了要么没发,graph 判断不了。
所以要在并行下做快照,节点必须停止直接写状态。它们返回一个变更描述,由 runtime 在提交点统一应用——这一步就牺牲了类型。两个节点的变更到达顺序不定,应用它们就必须与顺序无关,也就是说每个字段都需要一条在节点代码之外声明的合并规则。类型检查器能验证规则的签名,却验证不了规则满足交换律,也验证不了两次部分更新落地后状态的跨字段不变量依然成立。更普遍地说,并行分支的任何涉及状态的汇合都需要语义合并,而没有任何类型系统能检查语义合并。汇合输出没问题——gather 返回的是类型化的 tuple。汇合状态才是问题所在。
三角形的每条边都对应一个真实存在的系统。
并行加快照,合并就脱离了类型系统。这就是 LangGraph。节点返回更新而不是修改状态,每个 super-step 后写入一个 checkpoint。同一步里两个节点写同一个 key 时,由 Annotated 类型标注中声明的 reducer 来合并写入,没有 reducer 就直接报错。它能工作。状态可以带类型,reducer 的签名也可以,但合并本身无从校验。节点的写入本来是一条类型检查器读得懂的语句,现在成了一份数据。
类型安全加快照,就得串行。那是最初的 pydantic-graph,FullStatePersistence 保存状态和唯一的下一节点,任一时刻只有一个节点在跑。
类型安全加并行,就没有快照。这是今天的 pydantic-graph。我们花了很久寻找一个既能保持类型安全、又能支持快照的 API,但每个版本要么退化成 reducer 标注,要么需要多到没人受得了的泛型。所以 pydantic_graph.persistence 在 V2 中被移除,持久化交给了为此而生的引擎。设计 graph builder API 的 David Montague 说得好:"durable execution 是应对大多数实际终端用户挑战的实用方案。"剩下的是一个既无持久化、自身也无快照的类型化状态机。持久化来自 Temporal 在它周围重放代码,而 graph 这套机制——如果说有什么作用——不过是又多了一件必须确定性重放的东西。
Temporal 之所以能跳出这个三角,是因为它根本不为应用状态做快照。它记录每个 activity 完成时的结果,重放你的代码来重建状态,"三次更新完成了几次"的答案就是再把代码跑一遍。中途被打断的 activity 可能执行两次,而 activity 边界正是由你(而不是 runner)来声明什么触碰外部世界、重试是否安全的地方。
代码直接把整个三角形消解掉了。在代码里,状态的汇合是你亲手用语言写的:a, b = await gather(fa(), fb()),然后一行合并它们。合并是有类型、有顺序的,因为是你写的,持久化来自引擎对这段代码的重放。graph 库的问题在于它试图替你做合并,而且是通用化地做——而这恰恰是无法加上类型的部分。
Monty 是同一个答案在沙箱内的实现,那里没有 Temporal。解释器不持有任何操作系统资源:没有 socket,没有文件描述符,没有线程。脚本的每条并行分支都是沙箱正在等待的一个宿主函数,所以在它暂停的那一刻,所有在途的东西都在解释器之外,解释器本身——包括堆和调用栈——是一个几 KB 大小的完整一致值。这正是那些 graph 库找不到的 barrier,而代码免费得到它,因为唯一的状态就是局部变量,唯一跨越边界的通道就是你亲手写的那些调用。三个子 agent 的 gather 暂停为一份带三个待处理调用的快照,你把结果交回去就能恢复运行——换一个进程也行。宿主函数仍然是"什么触碰外部世界、跑两次是否安全"的裁决点,和 activity 一模一样。汇合是一行 Python,所以有类型;状态就是解释器,所以能快照。
graph 万岁
Prime Intellect 这个月把 Prime Agent 从 TypeScript 重写成了 Rust。两千多个 agent 花了两周完成这项工作,结果启动速度大约快了 14 倍。编排方式是:一个根 agent 把工作按任务的拓扑序排好,自己不写一行产品代码。每个任务经过 planner、implementer、reviewer 和 verifier,review 或验证失败就把任务退回给 implementer。他们称之为"有限状态机工厂"。看看它的形状:一个遍历任务的 for,里面每个任务套一个带 try 的 while。
问题在于 agent 用什么来写这个循环,以及你怎么运行它。如果模型要写 Python 来调用你的子 agent 和工具,你就得在没有人先审查的情况下执行它,还不能交出你的文件系统和网络。这就是 Monty 的职责:离开沙箱的唯一途径是宿主注册过的函数。不需要启动容器,不需要网络调用,所以 graph 可以每一轮都重写。
Pydantic AI Harness 的多 agent 协调已经是这么做的。每个子 agent 是一个 async 函数。编排器只有一个工具 run_workflow,由它写出整个编排:
import asyncio
reports = await asyncio.gather(
reviewer(task="Review auth.py for bugs:\n
重试和投票就是普通的 Python:一个包住 try 的 for,一个对结果做列表推导。只有最后一个值会返回到模型的上下文。脚本会先对照子 agent 的签名做类型检查,所以函数名拼错或参数类型不对,在任何子 agent 运行之前就会被拒绝。
你真正该看的 graph,是这次运行实际走过的那条,而不是事先画好的那张。子 agent 是 Pydantic AI agent,所以每次运行和每次模型调用都是编排器 trace 中的一个 OpenTelemetry span,在 Logfire 或任何其他后端里都能看到。扇出、汇合和每一次重试都按代码的写法嵌套呈现——这就是 agent 可观测性不需要 graph 可视化工具的原因:trace 本身就是那张图。
持久化和前面是同一个答案。把 Temporal(或任何其他持久化执行引擎)接到编排器以及那些模型调用应作为 activity 的子 agent 上,模型写的脚本就会对照已记录的子 agent 结果进行重放。脚本本身一行都不用改。
继续画 graph 吧
graph 要画,放进设计文档,从代码生成,事后用来解释一次运行。但不要执行它。graph 的 runtime 早就存在——就是你语言自带的那个;当 graph 的作者是模型时,给它 Monty,而不是一堆节点组成的库。Michael Pfaffenberger 用 5,276 次评分运行,实测了 code mode 相比 tool calling 带来的收益。
这个想法中属于人的部分——定义问题、搭建反馈机制,比如给每次运行打分的 evals,让模型的随机性只能往你想要的方向推——是我 10 月 28 日在阿姆斯特丹 FastAPI Conf 上的演讲主题。