主线 · 第 7 / 12 篇
· 约 9 分钟
让循环停得下来:state、上限、stop reason、guardrail 和人工确认
模型说“完成了”只是循环结束的一种方式。其余的结束方式要由应用写出来:把一次运行写成显式的 state,在每轮开始前检查步数和预算,识别重复动作,用 guardrail 拦住不该放出去的内容,写操作停下来等人确认。每一种结束都要有一个程序能分支的 stop reason。
上一篇的三种范式,说到底都是循环。循环最容易出的问题不是做错一步,而是停不下来:反复调同一个工具,在两个动作之间来回,或者把预算花完了还在转。这一篇讲循环怎样结束,以及结束之后程序怎么知道发生了什么。
几个词先说明。state 是一次运行的全部状态:走了几轮,用了多少 token,做过什么,现在处于什么状态。上限是事先设定的边界,比如最多几轮、最多多少 token。stop reason 在这里指一次运行为什么结束,和第四篇里单次调用的停止原因不是一回事。guardrail 是在循环旁边运行的检查,发现问题就中止。人工确认(human-in-the-loop)是在某些动作之前停下来,等人决定。
停下来不能只靠模型
Anthropic 的文章说,任务通常在完成时结束,但也常常加上停止条件,比如最大迭代次数,以保持控制;它同时提醒,Agent 的自主性意味着更高的成本,以及错误逐步累积的可能。OpenAI 的 Agent 构建指南说,每种编排方式都需要“一次运行”的概念,通常实现为一个循环,直到满足退出条件;常见的退出条件包括:模型调用了专门用来交付结果的工具、给出约定格式的结构化输出、出错,或者达到最大轮数。指南还列了两种需要人介入的情形:超过失败次数的阈值,以及高风险的动作。
框架里也是这样写的。下面是两个常用的 Agent 框架,框架本身第 10 篇再讲。OpenAI Agents SDK 的循环在模型给出最终输出时结束;超过 max_turns 就抛出 MaxTurnsExceeded。LangGraph 的 recursion limit 规定一次执行最多走多少步,到了就抛出 GraphRecursionError。
所以“模型说完成了”只是结束的一种方式。其余的方式,应用要自己写出来。
把一次运行写成 state
演示脚本把一次运行写成一个数据类:轮数、token 数、历史(每一步的动作、参数和观察)、状态(运行中、完成、停止、等人)、stop reason、待批准的动作、最终回答。
把这些放进一个对象而不是散在各处,有三个好处。上限可以对着它检查。它能整个存下来,过一会儿再接着跑。它也是后面讲评估时 trace 的原料。两个框架都把这一点做成了功能:Agents SDK 的 RunState 可以序列化成 JSON 存进数据库,再恢复;LangGraph 用 checkpointer 保存状态(LangGraph 把流程写成由节点连成的图),用 thread_id 指明要恢复哪一份。
stop reason 最好是一个小的、固定的集合,而不是一段话。演示里用的是 done、max_turns、budget、repeated_action、guardrail、needs_approval。程序按这个值分支:done 就交付结果,needs_approval 就去找人,其余的记下来、报警或者交给人。
上限、重复和 guardrail
演示里的循环,每轮开头先查上限,再调模型,再看模型提了什么:
def run(state):
while True:
if state.turns >= MAX_TURNS:
return stop(state, "stopped", "max_turns", f"limit {MAX_TURNS}, no answer yet")
if state.tokens + MODEL_CALL_TOKENS > TOKEN_BUDGET:
return stop(state, "stopped", "budget", f"limit {TOKEN_BUDGET}, one tool result was too big")
kind, *rest = SCRIPTS[state.scenario](len(state.history)) # one model call
state.turns += 1
state.tokens += MODEL_CALL_TOKENS
if kind == "finish":
if SECRET.search(rest[0]): # output guardrail: the summary goes to a chat channel
return stop(state, "stopped", "guardrail", "summary blocked: matched password=")
return stop(state, "done", "done", rest[0])
name, args = rest
if state.history and state.history[-1][:2] == [name, args]:
return stop(state, "stopped", "repeated_action", f"{name} proposed twice in a row")
if name in WRITE_TOOLS:
state.pending = {"id": f"appr-{state.turns}", "action": name, "args": args}
return stop(state, "waiting_for_human", "needs_approval", f"{name}({args['service']})")
obs = run_tool(name, args)
state.tokens += len(obs) // 4
state.history.append([name, args, obs])
重复检测在这里写得很简单:同一个工具、同样的参数,连续提了两次就停。真实系统可以看更长的窗口,或者数连续失败的次数;OpenAI 指南说的失败阈值就是这一类。
guardrail 管的是内容。Agents SDK 把它分成三种:输入 guardrail 检查用户发进来的内容(只对链条里第一个 Agent 运行),输出 guardrail 检查最后交出去的回答,工具 guardrail 在受保护的工具调用前后检查;检查不通过(文档叫触发 tripwire)就抛出异常,中止运行。OpenAI 的指南把 guardrail 看作分层的防御,单独一道不够,还要配合身份验证、授权和访问控制。第五篇的那道门管“这个动作能不能做”,guardrail 管“这段内容能不能进来、能不能出去”,两者都在模型之外。
停下来等人,再接着跑
写操作的处理在第五篇讲过:先问人。放进循环里,“问人”意味着运行要暂停,而人可能过一个小时才回复。所以暂停时要把 state 存下来,人决定之后再恢复。
Agents SDK 的做法是:工具声明自己需要批准,运行到这里暂停,结果里列出待批准的调用;把结果转成 RunState,批准或拒绝,再从原处继续。存下来的 RunState 就是快照。文档提醒,反序列化时 SDK 不检查快照是否被改过、提交决定的是谁,所以快照要放在应用控制的服务端;服务端要验证审批人的身份和权限,核对提交的决定是否对应存着的待批准项,并保证同一次运行不会被并发或重放地恢复两次。
LangGraph 的 interrupt 也是保存状态、无限期等待恢复。恢复时,它会把调用 interrupt 的那个节点从头再跑一遍,所以 interrupt 之前的操作要幂等,也就是执行一次和执行两次结果相同:“把超时设为 2000ms”可以重复,“发一条告警通知”不行。
同一个循环,六种结束
下面的演示不联网,每个场景是一段写死的“模型提议”,在同一个循环里跑。token 是粗算的:每次模型调用记 200,工具结果按每 4 字节一个 token。六行各对应一种结束方式,看最后两列:stop reason 给程序分支用,detail 给人看。
scenario turns tokens status stop reason detail
done 3 614 done done timeout change at 09:12; suggest rollback
repeated 2 403 stopped repeated_action query_logs proposed twice in a row
no end 6 1230 stopped max_turns limit 6, no answer yet
huge result 1 3125 stopped budget limit 2500, one tool result was too big
secret in summary 2 414 stopped guardrail summary blocked: matched password=
needs approval 3 614 waiting_for_human needs_approval rollback_config(login-api)
saved run-1: 419 bytes, pending appr-3 rollback_config
resume run-1, appr-3 approved: done, turns 4, rolled back; p99 should recover
resume run-1, appr-3 again: rejected: appr-3 already used
no end 每轮都换一个时间窗口,参数不同,重复检测抓不到,最后靠轮数上限停下。
huge result 只走了一轮,一次日志查询就超了预算;上限是在下一次调用模型之前检查的,那份大结果已经进了上下文,更好的办法是在工具那边就限制返回的大小。
secret in summary 里,密码早在读配置时就进了上下文,输出 guardrail 只是在最后一刻拦住;更早的一道防线是工具返回前就去掉敏感字段。
needs approval 停在第 3 轮,state 存成 419 字节的 JSON;批准之后从原处继续,第 4 轮完成。同一个批准再提交一次,被拒绝:服务端记下了用过的批准编号,这就是上一节说的不能重复恢复。
容易误解的地方
“设了步数上限就够了。”上限是最后一道兜底,它能让循环停下,但停下时往往什么也没交付。重复检测、预算和失败阈值能更早地发现问题。
“上限和预算只要设得够大就行。”设大了,停下来时钱已经花了;设小了,正常任务也做不完。合适的值要从评估里看实际的轮数和用量来定。
“guardrail 能代替权限。”guardrail 检查内容,权限决定动作;OpenAI 的指南也说,guardrail 要和身份验证、授权、访问控制一起用。
“恢复就是从头再跑一遍。”恢复是读回存下的 state,从停下的地方继续;从头跑会重复已经做过的动作,写操作尤其不能这样。
日常用的编码 Agent 停下来请求确认,恢复后接着刚才的步骤做,而不是从头开始,背后就是这样一份可以存下来的 state。
参考资料
- Anthropic: Building effective agents:任务完成时结束,也常加最大迭代次数等停止条件;自主带来更高成本和错误累积。
- OpenAI: A practical guide to building agents:运行循环与退出条件,guardrail 作为分层防御,失败阈值和高风险动作需要人介入。
- OpenAI Agents SDK: Running agents:Runner 的循环、max_turns 与 MaxTurnsExceeded。
- OpenAI Agents SDK: Guardrails:输入、输出、工具三种 guardrail 的运行位置,tripwire。
- OpenAI Agents SDK: Human-in-the-loop:需要批准的工具、暂停与恢复、RunState 序列化,以及服务端审批的注意事项。
- LangGraph: Interrupts:暂停、保存状态、恢复,interrupt 之前的副作用应当幂等。
- LangGraph: Graph API overview:recursion limit 与 GraphRecursionError。
本文涉及的知识点
6 个
名称打开知识图谱中的对应条目;「另见」只计已发布文章。
本节知识点
本节知识点