agentbelt-loop

Detect repeat, cyclic, and stagnation loops in AI agent tool-call sequences — with cross-session pattern learning. Part of the agentbelt suite.

pip install agentbelt-loop

Quickstart

from agentbelt_loop import LoopDetector, LoopPolicy, LoopDetected

detector = LoopDetector(LoopPolicy(max_exact_repeats=3))

detector.record("session-1", tool="search", args={"q": "foo"}, result=result)
try:
    detector.check("session-1")
except LoopDetected as e:
    print(e.kind, e.detail)   # "repeat" | "cycle" | "stagnation" | "known_pattern"

The differentiator: cross-session pattern learning

Once a cyclic shape (e.g. search → rephrase_query → search → rephrase_query) has been confirmed a loop in enough distinct sessions, new sessions matching that shape trip early — after 2 local repeats instead of waiting out the full threshold every time.

What did this actually catch?

print(detector.impact_report())
# 3 loop(s) detected across 5 check(s) (repeat=3)

Breaks down detections by kind, and calls out known_pattern catches specifically since those are the cross-session differentiator in action — loops caught early because another session already proved the shape.

See the suite README for the full concept and how this fits with agentbelt-budget and agentbelt-sampler.

License

MIT