今日 TL;DR
状态图把“现在在哪、允许做什么、收到什么结果后去哪”变成程序能检查的规则。模型可以建议下一步,状态机仍由服务端控制;记录状态也不等于已经实现可靠恢复。
- 状态表示流程位置,证据与预算属于携带的数据,二者分开管理。
- 转换必须带条件,非法转换在工具执行前拒绝。
- 恢复要从持久检查点读取事实,并查询可能已执行的副作用。
为什么今天学这个
昨天的 ReAct 课把提出动作、授权、执行、观察与完成组织成循环;周一先区分了工作流和 Agent 的控制权。今天将同一岗位查证任务画成状态图,为周六的可审计 Agent 准备检查点。10月18日课程文件缺失,按日历继续,不把未发布课程说成已完成。
状态机是一组有限的流程位置与合法移动规则。例如“待计划→待执行→待验收→成功”。图上的边不是装饰:它要说明需要什么事件、哪些条件必须成立,以及谁有权推进。把状态藏在“messages 里好像已经搜索过”会让重试和恢复难以判断;显式状态能使异常路径成为可测试接口。
状态图适合表达分支、循环、暂停和结束,不保证规划正确,也不证明检索证据支持答案。LangGraph 的节点读取状态并返回更新,边决定后续控制流;本课用标准 Python 重现边界,不要求先安装框架。避免把“会背框架 API”当作能解释业务流程的能力。
一张图讲清楚
PLAN 只生成动作建议;进入 EXECUTE 前校验白名单与授权;VERIFY 读取真实证据;工具超时进入 RETRYABLE。图中省略了所有状态均可发生的取消与预算耗尽,生产必须补齐这两类出口。DONE 是终态,不能再回到 EXECUTE。重试边需明确次数与总时间限制。
三个核心要点
- 状态与数据分别定义。 状态回答“下一步能做什么”,数据回答“已拿到哪些证据、用了多少预算”。用枚举约束状态、结构化字段保存证据 ID 与执行次数;不能让模型自由写一个“success”字符串就结束。保存完整聊天历史无法代替最小状态与业务事实。
- 边必须能拒绝。 从计划到执行检查动作与权限,从验收到完成检查真实结果;预期外事件、过期版本和重复完成都应被拒绝或返回明确结果。固定路径用普通边,依赖观察的分支用条件边,独立并发任务还需定义状态合并规则,不能最后写入者悄悄覆盖别人。
- 持久化与副作用分别处理。 内存字典只支持本次进程内追踪。恢复要有 run_id、检查点版本和持久存储;进程在“发出写入请求、未保存回执”之间崩溃时,先按幂等键查询结果,再决定重试。检查点不能凭空保证 exactly-once(恰好一次)执行。
最小可运行示例
保存为 state_graph.py,Python 3 标准库即可。输入为正常、超时、缺证据的只读工具结果;这是教学用有限状态机,模拟工具与决策器,不冒充真实模型,也未实现跨进程持久化。
from enum import Enum
class S(str, Enum):
PLAN = "plan"
EXECUTE = "execute"
VERIFY = "verify"
RETRYABLE = "retryable"
DONE = "done"
HELP = "needs_help"
DENIED = "denied"
EDGES = {
S.PLAN: {S.EXECUTE, S.DENIED},
S.EXECUTE: {S.VERIFY, S.RETRYABLE},
S.RETRYABLE: {S.EXECUTE, S.HELP},
S.VERIFY: {S.DONE, S.HELP},
S.DONE: set(), S.HELP: set(), S.DENIED: set(),
}
def move(ctx, target):
old = ctx["state"]
if target not in EDGES[old]:
raise ValueError(f"illegal edge: {old.value}->{target.value}")
ctx["state"] = target
ctx["trace"].append((old.value, target.value))
def run(results, allowed=True, max_attempts=2):
if max_attempts < 1:
raise ValueError("max_attempts must be positive")
ctx = {"state": S.PLAN, "evidence": [], "attempts": 0,
"trace": []}
move(ctx, S.EXECUTE if allowed else S.DENIED)
if not allowed:
return ctx
for result in results:
if ctx["state"] != S.EXECUTE:
break
ctx["attempts"] += 1
if result == "timeout":
move(ctx, S.RETRYABLE)
if ctx["attempts"] >= max_attempts:
move(ctx, S.HELP)
break
move(ctx, S.EXECUTE)
continue
if result == "ok":
ctx["evidence"].append("job-source-1")
move(ctx, S.VERIFY)
move(ctx, S.DONE if ctx["evidence"] else S.HELP)
break
if ctx["state"] == S.EXECUTE:
# 输入耗尽不是成功,用可恢复状态交还控制权。
move(ctx, S.RETRYABLE)
return ctx
if __name__ == "__main__":
for inputs in [["ok"], ["timeout", "ok"], ["timeout", "timeout"], ["missing"]]:
result = run(inputs)
print(result["state"].value, result["attempts"])
completed = run(["ok"])
try:
move(completed, S.EXECUTE)
except ValueError as error:
print(error)
执行 python3 state_graph.py。预期前四行依次为 done 1、done 2、needs_help 2、needs_help 1;最后打印 illegal edge: done->execute。超时后允许一次重试,连续两次失败转帮助;缺少资料通过验收分支退出,不把空结果写成成功。运行 run(["ok"], allowed=False) 应返回 denied,执行次数为零。
此处证据非空只是可观察的教学验收条件,不能证明语义正确。真实岗位答案还应验证来源权限、新鲜度与引用支持。max_attempts 只限工具尝试,不控制模型费用和墙钟时间;生产需另加总截止时间、取消信号与预算。EDGES 只限制位置,参数 Schema、租户授权和工具幂等不能从表里自动获得。
生产环境会怎么翻车
- 终态重复执行。 症状是刷新页面再次发邮件;根因是恢复时总从起点运行,没有读取终态和幂等结果。处理:以 run_id 查询持久状态,终态直接读取产物;副作用以业务幂等键去重。
- 超时被当成没执行。 症状是重复扣费或重复建单;根因是混淆网络超时与业务失败。处理:进入待核验状态,查询外部结果,确认未执行才允许重试。本例只读工具可简化,写入操作必须扩展状态。
- 并发更新覆盖证据。 症状是两个工具都成功,最终只剩一个来源;根因是共享状态按覆盖写入。处理:定义按证据 ID 合并的规则,使用检查点版本或事务处理竞争,回放验证重复结果不会增加两份副作用。
- 状态合法但业务越权。 症状是每条边都对,仍读了别的租户;根因是把流程验证当授权。处理:身份从服务端会话取得,工具侧按主体过滤;恢复时重新检查权限,不能沿用已撤销的旧凭据。
动手练习
用15–25分钟增加 CANCELLED 终态和 cancel 事件,允许 PLAN、EXECUTE、RETRYABLE 取消,禁止 DONE 转换。给每个状态转换记录 run_id、事件名和状态版本,用普通 JSON 文件保存一次检查点;重启后只读取展示状态,不自动重放工具。完成条件:正常、超时、取消、非法转换均有独立输出;取消后没有新的工具尝试;你能解释 JSON 文件示例为什么仍不能保证并发原子性与写入恰好一次。
面试表达
30 秒回答
“我把 Agent 拆成状态、节点和带条件的边。模型只提议行动,服务端在执行前检查授权与预算,工具回执进入验收分支,成功、超时、缺资料和取消有不同出口。状态图让我能测试非法转换、保存检查点并解释恢复。但检查点不保证外部副作用恰好一次,超时后需要用幂等键查询真实结果。”
追问与 3 分钟回答
追问:为什么已经有 trace 还需要状态?
trace 是发生过什么,状态是现在允许做什么。只靠日志重建控制流可能遇到缺记录、重放歧义与重复副作用。我会保存最小状态、版本、证据 ID、预算和产物引用,完整轨迹用于排错,不把敏感原文全塞日志。节点返回更新,边用显式条件路由;未知状态、未知事件和终态后的请求都拒绝。
恢复时,先读取持久检查点,再核对该用户权限是否仍有效。如果上次停在外部写入之后、回执保存之前,先按业务幂等标识查询外部系统,结果未知就保持待核验,而非盲目从节点开头重做。并行节点通过约定的合并器合并证据,检查版本竞争与重复投递。对于不可重放的动作,保存执行意图与回执,并使用目标系统支持的幂等机制。
评测用固定任务覆盖成功、超时、空资料、取消、重复事件和过期检查点,比较任务成功率、重复副作用与恢复耗时。状态图的收益是控制边界清晰,图更复杂并不自动提高质量。简单任务仍可用普通工作流,只有实际需要动态观察与恢复时才增加编排复杂度。这些是工程建议,具体预算和门槛由业务风险决定。
今日自测
1. 基础理解
trace 与 state 分别回答什么问题?
trace说明发生过哪些事件,state说明当前流程位置和合法下一步;二者配合,不能互相替代。
2. 工程取舍
保存检查点后,是否可以保证发邮件恰好一次?
不可以。外部发送与本地检查点不是同一个原子事务;需要幂等标识、结果查询和明确的未知状态处理。
3. 场景应用
恢复旧任务时发现用户权限已撤销,应沿用旧检查点继续执行吗?
不能。检查点保存流程事实,不授予永久权限;恢复前重新授权,拒绝越权并保留审计事件。
市场雷达
本期无新增市场信号。今天实际访问的 LangGraph 官方文档用于状态、条件边与持久化机制核验;页面可访问不等于它在最近30天刚发布,不据此编造招聘要求或岗位增长数字。
权威来源
- LangGraph Graph API — 状态、节点、边及状态更新规则。
- LangGraph Persistence — 检查点、线程、恢复与持久化边界。
- Python Enum 官方文档 — 示例使用的有限枚举类型。
上述三页于2026-10-21 09:01前后(Asia/Shanghai)实际访问,均HTTP 200;示例为本课独立教学实现,不把框架功能说成此示例已经实现。
明天会用到
明天学习预算、停止与防死循环:在今天的状态边上同时加步数、时间、费用和无进展条件,区分达到目标、用户取消、预算耗尽与需要人工帮助,为周六的可审计 Agent 补齐运行边界。