Repository navigation
Add a DetectLoops capability to interrupt repeated-action loops - #11471
Conversation
ApprovabilityVerdict: Approved at Macroscope's review found this PR approvable — Adds opt-in loop detection that can steer or stop repetitive agent runs. Existing agents remain unchanged, with per-run isolation, configurable thresholds, and content-aware telemetry safeguards limiting exposure. You can add or adjust custom eligibility rules. Learn more. |
There was a problem hiding this comment.
Reviewed at 117abba9af6ce0d294239cab4c8ff24ddfac2775.
All 22 changed files were reviewed. The two inline comments (both LOW) are the only findings that survived verification: the action docstring misdescribes the nudge's deliberate conversation scope, and result recording can mis-pair tool returns when another capability short-circuits a model request with a canned tool-call response.
Generated by 🔎 CI Review for #11471
…n loops An autonomous agent can keep making the same tool call, getting the same result, alternating between two calls, or repeating the same text until it exhausts its budget. DetectLoops checks the current run's history before each model request and nudges the model, raises LoopDetectedError, or calls a user handler. Deriving detection from history keeps it per-run and replay-safe under durable execution without a separate state store. Closes #9008
Re-deriving calls and results from history each request let compaction that drops or rewrites messages shift the reported boundary or make different calls look alike. Record each response's calls in after_model_request and its results from the request that follows, gate fingerprints behind trace_include_content, and cover DBOS, Prefect, Temporal errors, compaction, and prefix stability.
…ite them Run DetectLoops outermost so compaction cannot clear the newest results before they are recorded, read each response's results only once so a response DetectLoops never saw cannot overwrite them, and make the DBOS test exercise recovery.
117abba to
e87faa6
Compare
…prefix The new FunctionModel prefix check on main flags the two tests that pair DetectLoops with ClearToolResults and SlidingWindowCompaction; they rewrite history on purpose to show detection survives it.
There was a problem hiding this comment.
Reviewed at e87faa645e743dd9681fc663e40446a03aeed0d3.
All 22 changed files were reviewed: the capability core (detect_loops/_capability.py), its tests across the main, DBOS, Prefect, and Temporal suites, the docs page and package README twins, and the skill/navigation/parity/exports updates. The detection state machine, result-pairing fix, nudge metadata/scope, sanitization, telemetry, config validation, and documented defaults all check out; the single inline comment is a non-blocking docs completeness nitpick. No blocking findings.
Generated by 🔎 CI Review for #11471
| | `alternating_calls` | Two different tool calls are made in turn, A-B-A-B, for this many A-B cycles. | `alternating_calls_threshold` (`3`) | | ||
| | `repeated_text` | This many consecutive responses have no tool calls and the same text, ignoring case and whitespace. This happens when [output validation](../output.md#output-validator-functions) keeps asking the model to retry. | `repeated_text_threshold` (`3`) | | ||
|
|
||
| `window` (default `10`) is how many of the most recent tool calls the three call-based checks look at. Set a threshold to `None` to turn that check off. A threshold must be at least 2, and a call-based threshold has to fit in `window` (`alternating_calls_threshold` needs twice its value), so a check that could never fire raises `ValueError` when the capability is created. |
There was a problem hiding this comment.
The validation paragraph enumerates the constructor's rules but omits the one on window itself: __post_init__ rejects window < 2 even when every call-based threshold is None, so a text-only config such as DetectLoops(window=1, repeated_call_threshold=None, repeated_result_threshold=None, alternating_calls_threshold=None) raises ValueError with no hint from this page. Add it to the list:
Closes #9008
Why we make these changes
An autonomous agent can keep calling the same tool with the same arguments, get the same error back, alternate between two calls, or repeat the same text while output validation retries, until its request or token limit runs out. Nothing in core or harness notices. This adds
DetectLoopsto the harness (Control & safety), as proposed in #9008. It notices these patterns and interrupts the run before the rest of the budget is spent.New public surface
pydantic_ai_harness.DetectLoops, a capability withwindow,repeated_call_threshold,repeated_result_threshold,alternating_calls_threshold,repeated_text_threshold(eachNoneto disable), andaction('nudge','error', or a sync or async(ctx, loop)handler)pydantic_ai_harness.detect_loops:DetectedLoop,LoopDetectedError(anAgentRunError),LoopHandler, andLoopPatternUser-visible behavior
With the default
action='nudge', the request after the loop carries a conversation-scopedSystemPromptPartmarkedmetadata['origin'] == 'pydantic-ai-harness.detect_loops.nudge.v1'. Calls are recorded inafter_model_request, and their results are read from the request that follows. The capability runs outermost, so compaction can't make different calls look alike. Each detection emits aloop detectedspan.Verification
test_detect_loops.py: the four patterns, the actions, canonical arguments and results, tool call ids reused across responses,ClearToolResults/SlidingWindowCompactioncomposition,SkipModelRequest, request prefix stability over two runs, spans, and config validationtest_temporal.py,test_dbos.py,test_prefect.py: nudge and error under Temporal including history replay, DBOS crash recovery, and Prefect flowsdetect_loops/_capability.py. The examples indocs/harness/detect-loops.mdnow run intests/test_examples.pySystemPromptPartrendering and adds no new framing tagWhat changes for existing users
Nothing; the capability is opt-in.
PR decisions
2026-10-26 · Detect from run history in before_model_request, no store · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Nudge is a conversation-scoped SystemPromptPart with origin metadata · iter -
RetryPromptPartso the model can tell validation feedback from a user message #6404 is closed)DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Defaults: repeated_call 5/10, repeated_result 3, alternating 3 cycles, repeated_text 3; None disables · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Results compare as outcome + sorted-key structured content + file identifiers · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Context-window error loops, truncation, restart left out · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Telemetry: zero-duration
loop detectedspan on ctx.tracer · iter -InstrumentationSettings#6632 convention not yet decidedInstrumentationSettings#6632, which is still openDetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · Live provider probe of the nudge not run · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · pre-push review 1 of 3 at aa68cc5 · iter -
2026-10-26 · pre-push review 1 of 3 at aa68cc5 · iter -
2026-10-26 · Nudge keeps conversation scope, not request scope · iter -
DetectLoopscapability to interrupt repeated-action loops #90082026-10-26 · pre-push review 2 of 3 at 3812d53 · iter -
2026-10-26 · pre-push review 2 of 3 at 3812d53 · iter -
2026-10-26 · pre-push review 3 of 3 at 82b6a68 · iter -
2026-10-26 · pre-push review 3 of 3 at 82b6a68 · iter -
2026-10-27 · Rebased onto main to resolve System Reminders conflict · iter -
SystemReminderson request-scoped system prompts and deprecatecache_ttl#9712, keeping main wording plus the Detect Loops linkSystemReminderson request-scoped system prompts and deprecatecache_ttl#9712; tree after rebase differs only by main changes and the conflict lineDetectLoopscapability to interrupt repeated-action loops #11471Checklist