采购审批暂停后,重启进程继续执行
用真实 LangGraph、SQLite checkpoint 与业务唯一键,完成跨进程审批、拒绝和崩溃重放。
知识库回答返回之后,请求就结束了;采购 Agent 却可能先建议“给测试环境增加 120 元存储”,等负责人第二天批准,再创建采购记录。等待期间进程会退出,服务也可能重启。本节把这条链路做成能在本机真实运行的程序:第一次命令保存待审批事项并退出,下一次命令从磁盘恢复,批准后才向 SQLite 业务表写入。
本节承接 服务部署与重启。如果还不熟悉状态和节点,可先看 工作流状态;下面会用一个完整例子把这些概念连起来。
谁提出建议,谁决定能不能执行
这里的采购建议只有三个字段:operation_id 是一次采购的稳定业务编号,item 是项目名称,amount_cents 是整数分。120 元写成 12000,避免浮点金额误差。模型可以从申请文字里提取这些字段,但“模型觉得应该采购”不等于“采购已被批准”。
本节用固定建议把执行层跑通,不调用付费模型。将来接模型时,只替换产生建议的上游:仍然必须通过 validate,保存原始建议及指纹,等待审批,最后由确定性程序执行 SQL。模型不拿数据库连接,也不替用户生成批准结果。
| 对象 | 保存什么 | 解决什么问题 |
|---|---|---|
thread_id | 本次工作流的标识 | 另一个进程找到同一条审批进度 |
| checkpoint | 状态、下一节点和执行信息 | 进程退出后还能恢复;不是业务写入的收据 |
| 内容指纹 | 对三个采购字段计算 SHA-256 | 审批时发现传错内容;不是身份签名 |
operation_id 唯一键 | 业务表中的采购编号 | 节点重跑时不重复创建同一笔采购 |
interrupt() 让 LangGraph 保存状态并把控制权还给调用方,不是让 Python 一直睡眠。恢复时用相同的 thread_id 和 Command(resume=...);包含中断的节点会从头执行,因此中断之前不能随手发邮件或创建订单。批准之后的执行节点也可能重跑,我们仍要给它幂等保护。
新建目录与固定依赖
使用 Python 3.13,在自己选择的项目目录下新建 durable-agent。Windows 可放到 F 盘。下面两组命令二选一;以后都在这个目录执行,保证 data 指向同一个位置。先把后面的依赖文本保存为 requirements.txt,再安装。
Windows PowerShell:
mkdir durable-agent
cd durable-agent
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -I -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -I -m pip checkmacOS / Linux:
mkdir -p durable-agent
cd durable-agent
python3.13 -m venv .venv
.venv/bin/python -I -m pip install -r requirements.txt
.venv/bin/python -I -m pip check-I 隔离宿主环境的 Python 搜索路径,避免误用全局安装的包。以下是本次安装成功后的完整依赖锁定;保存全部内容,不需要另找源码或下载资料包。
aiosqlite==0.22.1
annotated-types==0.8.0
anyio==4.16.0
certifi==2026.10.23
charset-normalizer==3.5.2
distro==1.9.0
h11==0.16.0
httpcore==1.0.9
httpcore2==2.16.0
httpx==0.28.1
httpx2==2.16.0
idna==3.20
jsonpatch==1.42
jsonpointer==3.8
langchain-core==1.7.6
langchain-protocol==0.0.20
langgraph==1.2.9
langgraph-checkpoint==4.3.1
langgraph-checkpoint-sqlite==3.1.3
langgraph-prebuilt==1.1.1
langgraph-sdk==0.4.13
langsmith==0.14.17
orjson==3.13.0
ormsgpack==1.13.0
packaging==26.3
pydantic==2.14.2
pydantic_core==2.50.2
PyYAML==6.0.3
requests==2.34.2
requests-toolbelt==1.0.0
sniffio==1.3.1
sqlite-vec==0.1.9
tenacity==9.2.1
truststore==0.10.5
typing-inspection==0.4.5
typing_extensions==4.16.0
urllib3==2.8.0
uuid_utils==0.19.0
websockets==17.4
xxhash==4.0.2
zstandard==0.25.0保存完整工作流
保存为 workflow.py。程序分成三个部分:校验建议、构建审批图、解析 CLI 命令。图只包含 approval 和 execute 两个节点,拒绝路径直接结束。status 读取 checkpoint,展示真实下一节点和当前操作的业务行。
"""本地采购审批:checkpoint 保存进度,业务唯一键阻止重复采购。"""
import argparse
from contextlib import closing
import hashlib
import json
import os
from pathlib import Path
import sqlite3
from typing import TypedDict
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class State(TypedDict, total=False):
proposal: dict
fingerprint: str
decision: str
result: str
def fingerprint(proposal):
# 稳定序列化:同一内容始终产生同一指纹,不依赖字典键顺序。
raw = json.dumps(proposal, ensure_ascii=False, sort_keys=True)
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
def validate(proposal):
# 模型或人给出的建议都先过相同的确定性校验。
if set(proposal) != {"operation_id", "item", "amount_cents"}:
raise ValueError("采购字段必须是 operation_id、item、amount_cents")
if any(not isinstance(proposal[k], str) or not proposal[k].strip()
for k in ("operation_id", "item")):
raise ValueError("操作编号和采购项目不能为空")
if type(proposal["amount_cents"]) is not int or not 0 < proposal["amount_cents"] <= 100000:
raise ValueError("金额必须是 1~100000 的整数分")
def build(saver, business_path, crash_after_write=False):
def approval(state):
# 恢复时整个节点重跑,所以 interrupt 前没有任何业务写入。
reply = interrupt({"proposal": state["proposal"],
"fingerprint": state["fingerprint"]})
if (reply.get("fingerprint") != state["fingerprint"]
or reply.get("decision") not in ("approve", "reject")):
raise ValueError("审批内容不匹配")
return {"decision": reply["decision"]}
def execute(state):
proposal = state["proposal"]
validate(proposal)
if state.get("decision") != "approve" or fingerprint(proposal) != state["fingerprint"]:
raise ValueError("没有匹配当前采购内容的审批")
# 业务提交与 checkpoint 不是同一事务,必须在业务表实现幂等。
with closing(sqlite3.connect(business_path)) as db, db:
db.execute("BEGIN IMMEDIATE")
row = db.execute("SELECT fingerprint FROM purchases WHERE operation_id=?",
(proposal["operation_id"],)).fetchone()
if row and row[0] != state["fingerprint"]:
raise ValueError("operation_id 已被不同采购内容使用")
if not row:
db.execute("INSERT INTO purchases VALUES (?, ?, ?, ?)",
(proposal["operation_id"], proposal["item"],
proposal["amount_cents"], state["fingerprint"]))
# 故障实验:业务已经 commit,但节点尚未返回给 LangGraph。
if crash_after_write:
os._exit(73)
return {"result": "already_applied" if row else "applied"}
graph = StateGraph(State)
graph.add_node("approval", approval)
graph.add_node("execute", execute)
graph.add_edge(START, "approval")
graph.add_conditional_edges("approval", lambda s: s["decision"],
{"approve": "execute", "reject": END})
graph.add_edge("execute", END)
return graph.compile(checkpointer=saver)
def run(args):
data = Path(args.data).resolve()
data.mkdir(parents=True, exist_ok=True)
business_path = data / "business.sqlite3"
with closing(sqlite3.connect(business_path)) as db, db:
db.execute("CREATE TABLE IF NOT EXISTS purchases (operation_id TEXT PRIMARY KEY, "
"item TEXT NOT NULL, amount_cents INTEGER NOT NULL, fingerprint TEXT NOT NULL)")
config = {"configurable": {"thread_id": args.thread}}
with SqliteSaver.from_conn_string(str(data / "checkpoints.sqlite3")) as saver:
graph = build(saver, business_path, args.crash_after_write)
snapshot = graph.get_state(config)
if args.action == "start":
if snapshot.values:
raise ValueError("thread 已存在,请使用 status、approve、reject 或 retry")
proposal = {"operation_id": args.operation_id, "item": args.item,
"amount_cents": args.amount_cents}
validate(proposal)
graph.invoke({"proposal": proposal, "fingerprint": fingerprint(proposal)}, config)
elif args.action in ("approve", "reject"):
# CLI 在恢复前核对指纹:输错时不向 checkpoint 写入错误的 resume 值。
if not snapshot.values or snapshot.next != ("approval",):
raise ValueError("当前 thread 没有待审批采购")
if args.fingerprint != snapshot.values["fingerprint"]:
raise ValueError("指纹不匹配,请核对 status 中的采购内容")
graph.invoke(Command(resume={"decision": args.action,
"fingerprint": args.fingerprint}), config)
elif args.action == "retry":
if not snapshot.values or snapshot.values.get("decision") != "approve":
raise ValueError("只有已经审批的采购可以重试")
graph.invoke(None, config)
snapshot = graph.get_state(config)
# 展示真实 checkpoint ID、待执行节点和本线程操作的业务写入数。
operation_id = snapshot.values.get("proposal", {}).get("operation_id")
with closing(sqlite3.connect(business_path)) as db, db:
rows = db.execute("SELECT operation_id,item,amount_cents FROM purchases "
"WHERE operation_id=?", (operation_id,)).fetchall()
return {"thread": args.thread, "checkpoint_id":
(snapshot.config or {}).get("configurable", {}).get("checkpoint_id"),
"next": list(snapshot.next), "state": snapshot.values,
"business_rows": rows, "business_count": len(rows)}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("action", choices=["start", "status", "approve", "reject", "retry"])
parser.add_argument("--data", default="data")
parser.add_argument("--thread", required=True)
parser.add_argument("--operation-id", default="purchase-001")
parser.add_argument("--item", default="测试环境存储扩容")
parser.add_argument("--amount-cents", type=int, default=12000)
parser.add_argument("--fingerprint")
parser.add_argument("--crash-after-write", action="store_true")
args = parser.parse_args()
try:
print(json.dumps(run(args), ensure_ascii=False, indent=2))
except ValueError as error:
parser.exit(2, f"拒绝执行:{error}\n")
if __name__ == "__main__":
main()读代码时重点看四处连接。SqliteSaver.from_conn_string 连接磁盘文件,再交给 compile(checkpointer=saver);单独声明一个 SQLite 路径并不会自动持久化图。graph.invoke 的 config 始终带当前 thread。审批节点只返回决定,不修改采购字段。执行节点把“查已有记录”和“首次插入”放进 BEGIN IMMEDIATE 事务,且表自身有主键约束。
closing(...) 和 with db 的作用不同:前者负责关闭连接,后者负责提交或回滚事务。在 Windows 上漏掉关闭连接,后续移动或删除实验数据库时可能遇到文件占用。
第一次命令暂停,第二次命令批准
Windows 先启动采购,再用另一条命令读状态。两条命令是两个独立 Python 进程:
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py start --thread demo-a
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py status --thread demo-amacOS / Linux 使用:
.venv/bin/python -E -X utf8 -B workflow.py start --thread demo-a
.venv/bin/python -E -X utf8 -B workflow.py status --thread demo-a默认建议是“测试环境存储扩容,12000 分,purchase-001”。输出的 next 为 ["approval"],business_count 为 0,并且两次看到相同的 checkpoint_id。此时可以关闭终端,重新打开后先用 cd 回到刚才保存 workflow.py 的 durable-agent 项目目录;不需要重新执行 start。下面的命令直接指定项目内解释器,不依赖旧终端的变量或激活状态。data/checkpoints.sqlite3 保存等待状态,data/business.sqlite3 的采购表还没有写入。
在项目目录的终端中,核对名称、金额和编号后批准。下面指纹对应这组默认字段;你修改任意字段,就应复制自己 status 输出中的新指纹。
Windows:
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py approve --thread demo-a --fingerprint 22a4e6cb08cdf97ab8c46952c189f4424abf60c10b59163c2e24f7a31d283468macOS / Linux:
.venv/bin/python -E -X utf8 -B workflow.py approve --thread demo-a --fingerprint 22a4e6cb08cdf97ab8c46952c189f4424abf60c10b59163c2e24f7a31d283468本次 Windows / Python 3.13.5 实跑输出如下。你的 checkpoint ID 会不同,金额、结果和业务行数应一致:
{
"thread": "demo-a",
"checkpoint_id": "1f1d8c42-8c9a-658e-8002-516de7e0b6d0",
"next": [],
"state": {
"proposal": {
"operation_id": "purchase-001",
"item": "测试环境存储扩容",
"amount_cents": 12000
},
"fingerprint": "22a4e6cb08cdf97ab8c46952c189f4424abf60c10b59163c2e24f7a31d283468",
"decision": "approve",
"result": "applied"
},
"business_rows": [
[
"purchase-001",
"测试环境存储扩容",
12000
]
],
"business_count": 1
}next: [] 说明图已结束,applied 说明这次插入了记录。business_count 只统计当前操作编号,不是全库行数。第二次 approve 会提示“当前 thread 没有待审批采购”;完成后 retry 不再新建采购。对不存在的 thread 执行 status 会返回空状态,它不会自动复制其他 thread 的审批。
故意在业务提交后崩溃
最容易忽略的窗口是:SQL 已经提交,checkpoint 还没记录执行完成。如果仅依赖 checkpoint,恢复时节点会再次运行,外部副作用可能重复。
在项目目录的终端中,用独立数据目录开始故障实验。这样仍可沿用默认采购编号和指纹,同时保留前一次正常实验结果。
Windows:
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py start --data crash-data --thread crash-a
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py approve --data crash-data --thread crash-a --fingerprint 22a4e6cb08cdf97ab8c46952c189f4424abf60c10b59163c2e24f7a31d283468 --crash-after-write
$LASTEXITCODE
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py status --data crash-data --thread crash-a
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py retry --data crash-data --thread crash-amacOS / Linux:
.venv/bin/python -E -X utf8 -B workflow.py start --data crash-data --thread crash-a
.venv/bin/python -E -X utf8 -B workflow.py approve --data crash-data --thread crash-a --fingerprint 22a4e6cb08cdf97ab8c46952c189f4424abf60c10b59163c2e24f7a31d283468 --crash-after-write
echo $?
.venv/bin/python -E -X utf8 -B workflow.py status --data crash-data --thread crash-a
.venv/bin/python -E -X utf8 -B workflow.py retry --data crash-data --thread crash-a批准命令以 73 退出,且不会打印完整 JSON,这是代码在业务 commit 后主动终止进程的结果。随后 status 能看到 next: ["execute"],但业务记录已经是 1。retry 后 result 为 already_applied、next 为空、记录仍是 1。这次是真正重跑 execute 节点,不只是对完成状态再查询一次。
这里用两个 SQLite 文件刻意保留这个故障窗口。给业务操作稳定编号,再由业务系统按编号去重,才能应对“外部动作成功,但 Agent 未收到成功结果”的情况。若以后换成支付或工单 API,需要下游同样支持幂等键,不能把本地 SQL 的保障直接套在远端服务上。
拒绝、传错审批和冲突编号
在项目目录的终端中,换一个 thread 和操作编号开始另一笔采购。先执行 start,核对输出中的采购内容和指纹,再执行 reject。以下指纹对应默认项目、12000分和 purchase-002;修改字段时应换成自己输出的指纹。
Windows PowerShell:
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py start --thread demo-b --operation-id purchase-002
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py reject --thread demo-b --fingerprint e974764602e46ea939ab3bd212e6f4b1c65e784f45d59ce49dc20f028631dd7b
.\.venv\Scripts\python.exe -E -X utf8 -B workflow.py status --thread demo-bmacOS / Linux:
.venv/bin/python -E -X utf8 -B workflow.py start --thread demo-b --operation-id purchase-002
.venv/bin/python -E -X utf8 -B workflow.py reject --thread demo-b --fingerprint e974764602e46ea939ab3bd212e6f4b1c65e784f45d59ce49dc20f028631dd7b
.venv/bin/python -E -X utf8 -B workflow.py status --thread demo-b这条分支直接结束,decision 为 reject、next 为空,业务记录为0。拒绝后再 approve 不会让它复活;重新提交应使用新 thread。
如果把 demo-a 的指纹传给 demo-b,CLI 会在调用 Command 之前拒绝,因此待审批状态仍然保留。同一 thread 再次 start 也会被拒绝,防止覆盖原提案。不同 thread 可以提交同一 operation_id:同内容执行返回 already_applied;改了金额却沿用同一编号,会报“operation_id 已被不同采购内容使用”。
thread 是进度隔离键,不是登录权限。这个本地 CLI 的操作者就是审批人,能访问数据目录的人也能修改文件。接成多人服务时,需要把 thread 绑定到登录身份,并在服务端验证审批权限;指纹只解决审批内容匹配,不承担签名或账号认证。
用子进程回归,而不是在内存里证明恢复
保存下面完整代码为 test_workflow.py,与 workflow.py 放在同一目录。每次 CLI 调用都新起一个进程,验证确实依赖磁盘恢复;测试使用临时目录,不碰手工实验的 data。
"""每个 CLI 都启动新进程;数据库放临时目录,绝不写进发布源码。"""
import json
from contextlib import closing
import os
from pathlib import Path
import sqlite3
import subprocess
import sys
import tempfile
import unittest
SCRIPT = Path(__file__).with_name("workflow.py")
class DurableTests(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.data = self.tmp.name
def tearDown(self):
self.tmp.cleanup()
def cli(self, action, thread="a", *extra, code=0):
# -E 屏蔽宿主 PYTHONPATH,-B 防止源码目录产生 __pycache__。
env = dict(os.environ, PYTHONIOENCODING="utf-8")
proc = subprocess.run([sys.executable, "-E", "-X", "utf8", "-B", str(SCRIPT),
action, "--data", self.data, "--thread", thread, *extra],
capture_output=True, text=True, encoding="utf-8", env=env)
self.assertEqual(proc.returncode, code, proc.stderr)
return json.loads(proc.stdout) if code == 0 else proc.stderr
def count(self):
with closing(sqlite3.connect(Path(self.data) / "business.sqlite3")) as db:
return db.execute("SELECT count(*) FROM purchases").fetchone()[0]
def test_restart_approval_and_duplicate(self):
first = self.cli("start")
self.assertEqual(first["next"], ["approval"])
self.assertEqual(self.count(), 0)
later = self.cli("status")
self.assertEqual(first["checkpoint_id"], later["checkpoint_id"])
done = self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"])
self.assertEqual(done["state"]["result"], "applied")
self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"], code=2)
self.cli("retry")
self.assertEqual(self.count(), 1)
def test_reject_and_no_approval(self):
first = self.cli("start")
self.cli("retry", code=2)
done = self.cli("reject", "a", "--fingerprint", first["state"]["fingerprint"])
self.assertEqual(done["state"]["decision"], "reject")
self.assertEqual(done["next"], [])
self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"], code=2)
self.assertEqual(self.count(), 0)
def test_wrong_fingerprint_and_thread_isolation(self):
first = self.cli("start")
second = self.cli("start", "b", "--operation-id", "purchase-002")
self.cli("approve", "b", "--fingerprint", first["state"]["fingerprint"], code=2)
self.cli("approve", "a", "--fingerprint", "tampered", code=2)
self.assertEqual(self.count(), 0)
self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"])
self.assertEqual(self.cli("status", "b")["next"], ["approval"])
self.cli("reject", "b", "--fingerprint", second["state"]["fingerprint"])
self.assertEqual(self.count(), 1)
def test_crash_after_commit_and_real_node_replay(self):
first = self.cli("start")
self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"],
"--crash-after-write", code=73)
self.assertEqual(self.count(), 1)
self.assertEqual(self.cli("status")["next"], ["execute"])
recovered = self.cli("retry")
self.assertEqual(recovered["state"]["result"], "already_applied")
self.assertEqual(recovered["next"], [])
self.assertEqual(self.count(), 1)
def test_same_operation_conflict(self):
first = self.cli("start")
self.cli("approve", "a", "--fingerprint", first["state"]["fingerprint"])
duplicate = self.cli("start", "b")
done = self.cli("approve", "b", "--fingerprint", duplicate["state"]["fingerprint"])
self.assertEqual(done["state"]["result"], "already_applied")
changed = self.cli("start", "c", "--amount-cents", "13000")
self.cli("approve", "c", "--fingerprint", changed["state"]["fingerprint"], code=2)
self.assertEqual(self.count(), 1)
def test_invalid_amount_and_restart_existing_thread(self):
self.cli("start", "a", "--amount-cents", "0", code=2)
self.cli("start")
self.cli("start", "a", "--amount-cents", "999", code=2)
self.assertEqual(self.count(), 0)
if __name__ == "__main__":
unittest.main(verbosity=2)在项目目录的终端中,Windows 执行 .\.venv\Scripts\python.exe -E -X utf8 -B test_workflow.py,macOS / Linux 执行 .venv/bin/python -E -X utf8 -B test_workflow.py。本次实际结果为 6 tests、OK,覆盖正常批准、拒绝、未批准重试、错误指纹、thread 隔离、重复批准、相同编号内容冲突和提交后崩溃恢复。这些测试在命令之间新建进程,检查状态能否从SQLite恢复。
| 看到的现象 | 先检查哪里 | 下一步 |
|---|---|---|
| status 空状态 | 工作目录、--data、--thread 是否一致 | 回到原目录或显式指定原数据路径 |
| 指纹不匹配 | 审批命令是否复制了另一笔的指纹 | 重新 status 核对内容后复制;不重新 start |
| thread 已存在 | 之前是否已经 start 成功 | 查询后 approve/reject;已批准失败则 retry |
| 同编号不同内容 | 是否把旧采购号用于新金额 | 保留旧采购,给真正的新采购分配新编号 |
| 数据库被锁 | 是否同时运行了多个本地命令 | 先等前一个命令结束,再重试;本例按单操作者顺序运行 |
课后练习展开习题收起习题
练习
1. 业务写入成功后进程退出,为什么下一次仍可能执行 execute?
业务事务与 checkpoint 保存不是一个事务。业务 commit 成功并不表示图已经保存“节点完成”;恢复会重跑未确认的节点。程序通过唯一 operation_id、同事务查重以及内容比对,使重跑返回已有结果。
2. 把 interrupt 放在 INSERT 之后,再让人工批准,是否仍然是审批流程?
不是。业务动作已经发生,拒绝无法阻止它;恢复时中断节点还会从头运行。本例把审批放在独立节点,批准边才进入 execute,同时让 execute 幂等。
3. 同一 operation_id 的金额从 12000 改成 13000,能否简单当成重复请求返回成功?
不能。重复请求必须表达同一操作内容。本例先比较指纹,不同内容会拒绝;否则调用方会误以为 13000 已执行,实际数据库仍是 12000。
4. 两个 thread 使用相同 operation_id,代表流程隔离失效了吗?
不代表。thread 隔离的是工作流状态,operation_id 去重的是业务动作。不同流程可能重试同一业务操作,所以业务唯一键跨 thread 生效。需要为两笔独立采购使用两个 operation_id。
继续阅读
官方 Interrupts 解释暂停、恢复与节点重跑规则;Persistence 区分线程 checkpoint 与其他持久化存储。结合 幂等操作 和 人工接管,可以把本节的业务去重与审批边界迁移到更完整的 Agent。