《AI Agent 技术原理与架构·决策、记忆与学习》2.2 进展度量与死循环检测

“看起来在动”不等于“在进展”。本节把进展拆成四个可计算信号:状态差分、目标距离、动作指纹与状态哈希,用两条确定性轨迹演示停滞、重复动作与状态复现的判定,说明死循环检测必须基于状态哈希而不是人类对日志的直觉,并给出进展信号与循环检测的工程判据。

以下数字为教学示例,不构成对任何真实系统或供应商的承诺。

上一节说停止条件必须由运行时实现,这一节回答一个前置问题:运行时怎么知道循环还在推进?“看起来在动"不等于"在进展”。一个 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 是一个参数,调大减少误报,调小更早发现真循环。

信号之间的优先级

四条信号要组合出最终的判定,而不是各自独立报警。实用的组合逻辑大致是:

  1. 目标距离归零 → 正常完成,直接停止;
  2. 状态差分不为零但目标距离不变 → 可能在原地打转(revisit / 无净进展);
  3. 状态哈希复现且间隔足够大 → 判定死循环;
  4. 动作指纹连续重复且状态无差分 → 判定停滞。

优先级背后的原则是:目标达成永远优先于任何循环判断。一个 Agent 可能在完成前最后一步"重复"了一下,这不该被判为停滞。顺序错了,会把正常收尾误杀。

进展度量的边界

进展度量不是万能仪表,有三个已知盲区:

  1. 不可见状态。 如果 Agent 的关键状态没有进入状态哈希(比如只记录对话,不记录文件系统变化),它可能每步都在真实推进,但度量显示停滞——或者反过来。
  2. 度量本身的成本。 每一步都做全量状态哈希,在状态大、步骤多时会成为开销;实际系统往往只哈希关键字段。
  3. 合法回退。 有些任务需要临时回退才能前进(先破坏再重构);min_gap 和人工规则只能压低误报,不能消除。

第 1 点最重要:进展度量的质量等于状态表示的质量。状态模型漏了哪个键,度量就瞎哪只眼。

架构含义

进展度量对架构有三个直接约束:

  1. 状态必须是结构化的。 没有结构化的状态对象,就没有可哈希、可差分、可比较的进展信号。
  2. 哈希要稳定。 键排序、参数规范化都要固定,否则同一个状态在不同步产生不同指纹。
  3. 判定规则可配置。 min_gap、动作指纹是否参与、哪些键进哈希,都要能按任务调。

第 2 条是容易被忽略的坑。只要序列化顺序不稳定,同一个系统在不同运行里会给出不同的循环判定,回归测试根本无法建立。

架构判据

判据合格的样子不合格的样子
状态结构化有可哈希的状态对象只有自然语言对话
哈希稳定键排序 + 参数规范化直接哈希字典字符串
判定组合差分/距离/指纹/哈希并用只看动作名是否重复
循环有间隔min_gap 可配置同一状态出现就算
目标优先距离归零直接完成先判循环后看目标

“哈希稳定"这一条值得在每次改动状态模型后回归:改动一个键的表示,可能让所有历史轨迹的循环判定都变化。

一个真实故障的例子

一个客服 Agent 反复调用"查订单"工具,每次都返回不同的时间戳,看起来每步都有进展。但如果它查的字段没有进入状态模型,状态哈希一直不变,动作指纹相同,判定为停滞。修复不是加停止条件,而是把订单号、状态、时间戳纳入状态,让度量能看到真实的重复。

反过来,一个代码修复 Agent 连续跑测试、连续失败,但每次失败的原因不同(先编译错、后逻辑错)。状态差分不为零,进展信号正常;此时死循环判定不该触发,该触发的是"失败原因集合是否在收敛"这类更细的指标。

小结

  • 进展度量至少包括状态差分、目标距离、动作指纹、状态哈希四个信号。
  • 状态哈希必须对键顺序不敏感,动作指纹必须对参数顺序不敏感。
  • “每个动作都不同”仍可能死循环;只有状态哈希能抓住状态复现。
  • 停滞、回退、循环要分开判定,min_gap 和优先级写死并文档化。
  • 目标距离归零优先于任何循环判断,避免误杀正常收尾。
  • 进展度量的质量上限是状态表示的质量:状态漏了键,度量就瞎了眼。

阅读导航:上一节:2.1 循环、步数与停止条件 · 下一节:2.3 预算、超时与强制终止 。

常见错误与边界

  1. 只看动作名。 动作不同也能循环;循环判定必须看状态哈希。
  2. 哈希不稳定。 键顺序或参数顺序影响指纹,会让同一个状态被当成两个状态。
  3. 把回退当循环。 有意的重跑和死循环要分开;min_gap 太小会误杀正常流程。
  4. 只记对话。 关键业务状态不进哈希,进展度量就看不到真实的推进或重复。
  5. 目标未优先。 先判循环后看目标距离,会误停将要完成的任务。
  6. 判定规则写死在代码里。 不同负载需要的 min_gap 不同,要可配置并可回归。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图