以下数字为教学示例,不构成对任何真实系统或供应商的承诺。
上一节说停止条件必须由运行时实现,这一节回答一个前置问题:运行时怎么知道循环还在推进?“看起来在动"不等于"在进展”。一个 Agent 可以每步都调用不同的工具、输出不同的文本,但状态始终原地打转;也可以一句话不说就接近目标。要判断该不该继续,你需要一组可以计算的进展信号,而不是读日志的直觉。
这一节把进展度量拆成四个信号:状态差分、目标距离、动作指纹、状态哈希。然后演示它们如何协作,识别两类典型故障:停滞(stalled)和死循环(cycle)。
四个可计算的信号
| 信号 | 定义 | 回答的问题 |
|---|---|---|
| 状态差分 | 前后两步状态中发生变化的键数 | 这一步改变环境了吗 |
| 目标距离 | 目标键中尚未匹配的个数 | 离目标还有多远 |
| 动作指纹 | 动作名加参数的稳定哈希 | 是不是在重复同一个动作 |
| 状态哈希 | 整个状态的无序指纹 | 有没有回到之前的某个状态 |
四个信号各有侧重,也各有盲区,所以要放在一起用:
- 状态差分把"改变"和"进展"分开。改变可能是好事,也可能只是来回摆动。
- 目标距离衡量方向:改变如果让距离变大,可能是在绕远路。
- 动作指纹抓住"连续重复同一个动作"的机械行为,比如反复读同一个文件。
- 状态哈希抓住"回到旧状态",这通常意味着循环,不管动作名是否相同。
状态哈希为什么要无序
状态是一个键值映射。两个状态如果键相同、值相同,但键的插入顺序不同,在逻辑上是同一个状态。哈希必须对键顺序不敏感,否则同一个状态会因为字典的偶然顺序被当成两个不同的状态,循环检测就会失效。
实现上,做法是先把键排序再序列化,再取哈希。这也是为什么状态哈希必须用稳定的序列化(sort_keys=True),而不是把字典转成字符串直接哈希。
动作指纹:重复动作与参数
动作指纹是"动作名加参数"的指纹。参数顺序同样不应影响指纹:run_tests(suite=refund) 和 run_tests(refund=suite) 是同一次调用。把参数规范化后再指纹,才能保证同一动作产生同一指纹。
指纹有两个用途:检测连续重复(同一指纹连着出现),以及配合状态哈希判断"重复动作是不是真的没用"。读同一个文件两次,第一次可能得到新信息,第二次几乎必然没有。
最小实验:两条轨迹
下面的实验用两条确定性轨迹演示判定规则:
- repair:一条修复轨迹,先重复读文件(停滞),然后编辑、跑测试、完成。
- ping-pong:一条在
phase=a和phase=b之间来回摆动的轨迹,动作不重复,但状态反复复现。
# file: agp_lab/progress_metrics.py | write
# tier: 3
# verify: python3 -m unittest tests.test_progress_metrics
"""进展度量与死循环检测:状态差分、目标距离、动作指纹、状态哈希。
“看起来在动”不等于“在进展”。本模块把进展拆成四个可计算信号:
状态差分、目标距离、连续重复动作、状态哈希复现。用两条确定性轨迹
演示:一条有停滞但最终完成,一条在状态间来回摆动。
"""
from __future__ import annotations
import hashlib
import json
from dataclasses import dataclass, field
from typing import Mapping
State = Mapping[str, str]
def _stable_digest(payload: object) -> str:
text = json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]
def state_hash(state: State) -> str:
"""与键顺序无关的状态指纹。"""
return _stable_digest(dict(state))
def action_fingerprint(action: str, args: Mapping[str, str] | None = None) -> str:
"""动作名加参数的指纹;参数顺序不同不应产生不同指纹。"""
return _stable_digest({"action": action, "args": dict(args or {})})
def state_delta(previous: State, current: State) -> int:
"""发生了变化的键数,包含新增与删除。"""
keys = set(previous) | set(current)
return sum(1 for key in keys if previous.get(key) != current.get(key))
def goal_distance(state: State, goal: State) -> int:
"""目标键中尚未匹配的个数;缺失的键也计为不匹配。"""
return sum(1 for key, value in goal.items() if state.get(key) != value)
@dataclass(frozen=True)
class TraceStep:
state: dict[str, str]
action: str
args: dict[str, str] = field(default_factory=dict)
class LoopDetector:
"""维护状态出现次数与连续动作计数。"""
def __init__(self) -> None:
self.state_counts: dict[str, int] = {}
self.last_fingerprint: str | None = None
self.action_streak = 0
def observe(self, state: State) -> tuple[str, int]:
digest = state_hash(state)
self.state_counts[digest] = self.state_counts.get(digest, 0) + 1
return digest, self.state_counts[digest]
def act(self, action: str, args: Mapping[str, str] | None = None) -> tuple[str, int]:
fingerprint = action_fingerprint(action, args)
if fingerprint == self.last_fingerprint:
self.action_streak += 1
else:
self.last_fingerprint = fingerprint
self.action_streak = 1
return fingerprint, self.action_streak
@dataclass(frozen=True)
class StepRow:
step: int
delta: int
distance: int
action: str
action_repeated: bool
state_revisit: bool
verdict: str
def cycle_detected(trace: tuple[TraceStep, ...], min_gap: int = 2) -> bool:
"""同一状态在至少 min_gap 步后再次出现,视为循环。"""
first_seen: dict[str, int] = {}
for index, item in enumerate(trace):
digest = state_hash(item.state)
if digest in first_seen and index - first_seen[digest] >= min_gap:
return True
first_seen.setdefault(digest, index)
return False
def evaluate(trace: tuple[TraceStep, ...], goal: State) -> list[StepRow]:
detector = LoopDetector()
rows: list[StepRow] = []
previous: State | None = None
for index, item in enumerate(trace, start=1):
_, count = detector.observe(item.state)
_, streak = detector.act(item.action, item.args)
delta = 0 if previous is None else state_delta(previous, item.state)
distance = goal_distance(item.state, goal)
revisit = count > 1
repeated = streak > 1
if delta == 0 and repeated:
verdict = "stalled"
elif revisit:
verdict = "revisit"
elif delta == 0:
verdict = "no-delta"
else:
verdict = "progress"
rows.append(StepRow(index, delta, distance, item.action, repeated, revisit, verdict))
previous = item.state
return rows
@dataclass(frozen=True)
class TraceResult:
name: str
rows: tuple[StepRow, ...]
cycle: bool
no_delta: int
revisits: int
action_repeats: int
def summarize(name: str, trace: tuple[TraceStep, ...], goal: State) -> TraceResult:
rows = evaluate(trace, goal)
return TraceResult(
name=name,
rows=tuple(rows),
cycle=cycle_detected(trace),
no_delta=sum(1 for row in rows if row.delta == 0),
revisits=sum(1 for row in rows if row.state_revisit),
action_repeats=sum(1 for row in rows if row.action_repeated),
)
GOAL: State = {"test": "pass", "patch": "1"}
REPAIR_TRACE = (
TraceStep({"test": "fail", "patch": "none"}, "read_file", {"file": "test_refund"}),
TraceStep({"test": "fail", "patch": "none"}, "read_file", {"file": "test_refund"}),
TraceStep({"test": "fail", "patch": "1"}, "edit", {"file": "refund.py"}),
TraceStep({"test": "fail", "patch": "1"}, "run_tests", {"suite": "refund"}),
TraceStep({"test": "pass", "patch": "1"}, "finish", {}),
)
PINGPONG_TRACE = (
TraceStep({"phase": "a"}, "act_a", {}),
TraceStep({"phase": "b"}, "act_b", {}),
TraceStep({"phase": "a"}, "act_a", {}),
TraceStep({"phase": "b"}, "act_b", {}),
)
TRACES = (("repair", REPAIR_TRACE), ("ping-pong", PINGPONG_TRACE))
if __name__ == "__main__":
for name, trace in TRACES:
result = summarize(name, trace, GOAL)
print(f"trace={name}")
print(f" {'step':<5}{'delta':>6}{'dist':>6} {'action':<12}{'repeat':>7}{'revisit':>8} verdict")
for row in result.rows:
print(
f" {row.step:<5}{row.delta:>6}{row.distance:>6} {row.action:<12}"
f"{str(row.action_repeated):>7}{str(row.state_revisit):>8} {row.verdict}"
)
print(
f" summary cycle={result.cycle} no-delta={result.no_delta} "
f"revisits={result.revisits} action-repeats={result.action_repeats}"
)
运行:
cd private/labs/agp-lab
python3 -m agp_lab.progress_metrics
输出:
trace=repair
step delta dist action repeat revisit verdict
1 0 2 read_file False False no-delta
2 0 2 read_file True True stalled
3 1 1 edit False False progress
4 0 1 run_tests False True revisit
5 1 0 finish False False progress
summary cycle=False no-delta=3 revisits=2 action-repeats=1
trace=ping-pong
step delta dist action repeat revisit verdict
1 0 2 act_a False False no-delta
2 1 2 act_b False False progress
3 1 2 act_a False True revisit
4 1 2 act_b False True revisit
summary cycle=True no-delta=1 revisits=2 action-repeats=0
这张表说明三件事。
停滞能被自动识别。 repair 的第 1 步读文件后状态没变(no-delta);第 2 步不仅状态没变,动作指纹还和上一步相同,判定为 stalled。单看第 2 步"读了文件",你可能会觉得是合理的探查;有了上一步的状态和动作指纹,才能看出它是原地踏步。
“每个动作都不同”仍然可能循环。 ping-pong 的四个动作 act_a, act_b, act_a, act_b 各不相同,action-repeats=0;但状态 a → b → a → b 里,a 和 b 都在至少两步后再次出现,cycle=True。只检测"重复动作"会漏掉这类循环,必须依赖状态哈希。
回退与循环要分开看。 repair 里 run_tests 那步 revisit=True,但整体 cycle=False:回到"测试失败"状态是有意的(改完必须重跑确认),不是死循环。判定规则用"同一状态间隔至少 min_gap 步再出现"来避免把正常的重跑误判成循环。min_gap 是一个参数,调大减少误报,调小更早发现真循环。
信号之间的优先级
四条信号要组合出最终的判定,而不是各自独立报警。实用的组合逻辑大致是:
- 目标距离归零 → 正常完成,直接停止;
- 状态差分不为零但目标距离不变 → 可能在原地打转(revisit / 无净进展);
- 状态哈希复现且间隔足够大 → 判定死循环;
- 动作指纹连续重复且状态无差分 → 判定停滞。
优先级背后的原则是:目标达成永远优先于任何循环判断。一个 Agent 可能在完成前最后一步"重复"了一下,这不该被判为停滞。顺序错了,会把正常收尾误杀。
进展度量的边界
进展度量不是万能仪表,有三个已知盲区:
- 不可见状态。 如果 Agent 的关键状态没有进入状态哈希(比如只记录对话,不记录文件系统变化),它可能每步都在真实推进,但度量显示停滞——或者反过来。
- 度量本身的成本。 每一步都做全量状态哈希,在状态大、步骤多时会成为开销;实际系统往往只哈希关键字段。
- 合法回退。 有些任务需要临时回退才能前进(先破坏再重构);
min_gap和人工规则只能压低误报,不能消除。
第 1 点最重要:进展度量的质量等于状态表示的质量。状态模型漏了哪个键,度量就瞎哪只眼。
架构含义
进展度量对架构有三个直接约束:
- 状态必须是结构化的。 没有结构化的状态对象,就没有可哈希、可差分、可比较的进展信号。
- 哈希要稳定。 键排序、参数规范化都要固定,否则同一个状态在不同步产生不同指纹。
- 判定规则可配置。 min_gap、动作指纹是否参与、哪些键进哈希,都要能按任务调。
第 2 条是容易被忽略的坑。只要序列化顺序不稳定,同一个系统在不同运行里会给出不同的循环判定,回归测试根本无法建立。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 状态结构化 | 有可哈希的状态对象 | 只有自然语言对话 |
| 哈希稳定 | 键排序 + 参数规范化 | 直接哈希字典字符串 |
| 判定组合 | 差分/距离/指纹/哈希并用 | 只看动作名是否重复 |
| 循环有间隔 | min_gap 可配置 | 同一状态出现就算 |
| 目标优先 | 距离归零直接完成 | 先判循环后看目标 |
“哈希稳定"这一条值得在每次改动状态模型后回归:改动一个键的表示,可能让所有历史轨迹的循环判定都变化。
一个真实故障的例子
一个客服 Agent 反复调用"查订单"工具,每次都返回不同的时间戳,看起来每步都有进展。但如果它查的字段没有进入状态模型,状态哈希一直不变,动作指纹相同,判定为停滞。修复不是加停止条件,而是把订单号、状态、时间戳纳入状态,让度量能看到真实的重复。
反过来,一个代码修复 Agent 连续跑测试、连续失败,但每次失败的原因不同(先编译错、后逻辑错)。状态差分不为零,进展信号正常;此时死循环判定不该触发,该触发的是"失败原因集合是否在收敛"这类更细的指标。
小结
- 进展度量至少包括状态差分、目标距离、动作指纹、状态哈希四个信号。
- 状态哈希必须对键顺序不敏感,动作指纹必须对参数顺序不敏感。
- “每个动作都不同”仍可能死循环;只有状态哈希能抓住状态复现。
- 停滞、回退、循环要分开判定,min_gap 和优先级写死并文档化。
- 目标距离归零优先于任何循环判断,避免误杀正常收尾。
- 进展度量的质量上限是状态表示的质量:状态漏了键,度量就瞎了眼。
阅读导航:上一节:2.1 循环、步数与停止条件 · 下一节:2.3 预算、超时与强制终止 。
常见错误与边界
- 只看动作名。 动作不同也能循环;循环判定必须看状态哈希。
- 哈希不稳定。 键顺序或参数顺序影响指纹,会让同一个状态被当成两个状态。
- 把回退当循环。 有意的重跑和死循环要分开;min_gap 太小会误杀正常流程。
- 只记对话。 关键业务状态不进哈希,进展度量就看不到真实的推进或重复。
- 目标未优先。 先判循环后看目标距离,会误停将要完成的任务。
- 判定规则写死在代码里。 不同负载需要的 min_gap 不同,要可配置并可回归。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。