Detect Loops
Notice when an agent repeats the same actions without making progress, and interrupt it before the loop uses up the run’s request, token, or cost budget. Use it on agents that run autonomously for many steps.
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
flowchart TB
accTitle: Detect Loops: interrupt an agent that repeats itself
accDescr: The model calls your tool, and the tool result and the next request pass through DetectLoops, which checks whether the same call gave the same result 3 times. If no, the request goes on to the model. If yes, with action='nudge' a system prompt joins the next request to the model, and with action='error' LoopDetectedError ends the run.
model(["model"])
tool["your tool"]
detect["DetectLoops()<br/>same call, same result,<br/>3 times?"]:::capability
nudge["system prompt joins<br/>the next request"]:::capability
error["LoopDetectedError<br/>ends the run"]:::blocked
model -->|"tool call"| tool
tool -->|"tool result, next request"| detect
detect -->|"no"| model
detect -->|"yes, action='nudge'"| nudge
nudge --> model
detect -.-x|"yes, action='error'"| error
classDef capability stroke:#E520E9,stroke-width:2px
classDef blocked stroke:#E5533D,stroke-width:2px,stroke-dasharray:4 3
pip install pydantic-ai-harness
uv add pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai_harness import DetectLoops
agent = Agent('anthropic:claude-opus-5-5', capabilities=[DetectLoops()])
DetectLoops records each model response’s tool calls and text as it arrives, and each call’s result from the request that follows it. Before each model request, it checks what the run has done so far. When it finds a loop, it adds a system prompt to that request telling the model which loop it is in and asking it to change its approach. It also checks each response on its own as it streams, for thinking, text or tool call arguments that keep repeating the same passage, and stops the stream when they do (loops within a response). The capability adds no tools or instructions, so a run without a loop sends the same requests it would without it.
| Pattern | Reported when | Setting (default) |
|---|---|---|
repeated_call | The same tool call (same tool, same arguments) is made this many times within the last window tool calls, whatever it returned. | repeated_call_threshold (5) |
repeated_result | The same tool call returned the same result each of the last this-many times it was made within window. | repeated_result_threshold (3) |
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 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. window must be at least 2, even when every call-based check is 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.
How calls and results are compared:
- Arguments are compared as canonical JSON with sorted keys, so
{"path": "a", "limit": 1}and{"limit": 1, "path": "a"}, or the same object sent as a JSON string, are the same call. - A result is the tool return’s outcome, its content as structured JSON with sorted keys, and the identifiers of any files it returned. A tool that raises
ModelRetrywith the same message each time returns the same result, so a call that keeps failing the same way is arepeated_resultloop. - Every call in a response counts, in order, including parallel calls in a response that already completes a loop.
- A result is matched to its call only within the request that follows the call’s response, so models that reuse tool call ids across responses are still compared correctly.
- Calls and results are recorded when they arrive.
DetectLoopsruns outermost among the agent’s capabilities, so it reads a call’s result before others, such as compaction, rewrite the request. Compaction that later drops old messages, or replaces old results and arguments with placeholders, doesn’t change what was recorded, so it can’t make different calls look alike. - Only function tool calls count. Calls the provider runs itself (native tools) are not compared.
At most one loop is reported per model request, checked in the order repeated_result, alternating_calls, repeated_call, repeated_text. The responses that formed it are then not counted again, so the same loop has to build up from scratch before it is reported a second time.
Only the current run’s responses are recorded. A run that continues an earlier conversation through message_history starts with nothing counted.
A tool polled until a job finishes, with arguments that don’t change, is a repeated_call loop after 5 polls within 10 calls, and a repeated_result loop after 3 polls in a row that return the same status. If your agent polls on purpose, raise those thresholds or turn the checks off, or have the tool return something that changes between polls, such as the elapsed time.
A model can also loop inside one response: going over the same reasoning in its thinking, repeating a paragraph until it runs out of output tokens, or writing the same block again and again into one tool call’s arguments, such as the body of a write_file call. DetectLoops checks each response for this as it streams, so it can stop the stream instead of waiting for the rest of it.
| Pattern | Reported when | Setting (default) |
|---|---|---|
repeated_thinking | A thinking part keeps repeating the same passage. | stream_detector (RepetitionDetector()) |
repeated_stream_text | A text part keeps repeating the same passage. | stream_detector |
repeated_tool_args | One tool call’s arguments keep repeating the same passage. | stream_detector |
repeated_parallel_call | The same tool call (same tool, same arguments) is made this many times in one response. It’s reported before any of the calls run. | repeated_parallel_call_threshold (5) |
stream_channels (default ('thinking', 'text', 'tool_args')) picks which of a response’s parts stream_detector checks, and stream_detector=None turns those checks off. Each part is checked every stream_check_every (default 256) characters as it streams, and once more when it ends. Only function tool and output tool calls are checked, not native tool calls.
A response that isn’t streamed, such as one from agent.run() without an event_stream_handler, gets the same checks once it has arrived, at the same offsets, so it reaches the same decisions. DetectLoops doesn’t make a run stream.
RepetitionDetector looks at the end of each part and reports a passage repeated back to back:
| Setting | Default | Meaning |
|---|---|---|
min_period | 20 | The shortest passage that counts, in characters. A run of a shorter unit, such as a divider line, isn’t reported, even when a longer passage made of it repeats. |
max_period | 2000 | The longest passage that counts. |
min_distinct_chars | 8 | How many different characters the passage has to use, so a row of numbers or a table rule doesn’t count. |
min_repeats | 8 | How many times in a row the passage has to repeat. |
min_chars | 2000 | How many characters the repeats have to cover together. |
It compares characters exactly, over the part’s most recent sample_chars characters: enough for min_repeats repeats of a max_period passage. That’s cheap enough to run on every check, and gives the same answer every time. It doesn’t catch a loop that changes a little on each pass, such as a counter in every sentence: a model judge can.
Output can repeat on purpose, so the defaults trade how early a loop is caught for fewer false alarms. A grid of numbers, a markdown table, or a few dozen identical rows in a file isn’t reported, and a real loop is caught once it has filled about 2,000 characters, long before a response that loops would run out of output tokens. Content that repeats more than that, such as a fixture with hundreds of identical rows, is reported. If your agent writes that kind of content, raise min_chars and min_repeats, or leave 'tool_args' out of stream_channels.
LoopJudge asks a model whether a part is looping. Use a “System 1” model for it: a small, fast, cheap model suited to a quick, intuitive read of the text, not a large reasoning model. The stream waits for each answer, and the question doesn’t need reasoning.
from pydantic_ai import Agent
from pydantic_ai_harness import DetectLoops
from pydantic_ai_harness.detect_loops import LoopJudge
agent = Agent(
'anthropic:claude-opus-5-5',
capabilities=[DetectLoops(stream_detector=LoopJudge(model='anthropic:claude-haiku-5-5', every=4_000))],
)
The judge is asked sparingly. Each check runs heuristic (a RepetitionDetector() by default) first, and the judge is asked when the heuristic suspects a loop, to confirm or overrule it, and, with every set, each time a part passes another every characters, to find loops the heuristic misses. Without every, it’s only asked on suspicion. It’s shown the part’s last max_chars (default 4000) characters, framed in a <streamed_output> tag.
If the judge raises, or doesn’t answer within timeout (default 5.0) seconds, the heuristic’s answer is used and a loop judge failed span records the error’s type, so a judge failure doesn’t break the run. Pass agent= instead of model= to use your own judge agent, with its own instructions, settings or fallback models; it’s run with the judge’s instructions added and its own output type, so it can’t have output validators. The judge’s usage is added to the run’s usage, and it runs within the run’s UsageLimits, with the run’s pending request reserved: a judge request that would exceed them raises UsageLimitExceeded and ends the run, as the run’s next request would, instead of falling back to the heuristic.
Subclass LoopDetector to use another methodology. detect is given a StreamSample: the channel, the part’s latest text (its last sample_chars characters, 8000 unless you override the property), how many characters it has had in total and since the last check, and the tool_name for tool call arguments. Return a Repetition with the passage that repeats and how many times, or None. One instance serves every run of the agent, concurrent ones included, so keep it stateless or key any state off the RunContext:
from dataclasses import dataclass
from pydantic_ai import RunContext
from pydantic_ai_harness import DetectLoops
from pydantic_ai_harness.detect_loops import LoopDetector, Repetition, StreamSample
@dataclass
class RepeatedLines(LoopDetector[object]):
"""Report the same non-empty line written `count` times in a row."""
count: int = 10
async def detect(self, ctx: RunContext[object], sample: StreamSample) -> Repetition | None:
lines = sample.text.splitlines()[-self.count :]
if len(lines) == self.count and lines[0].strip() and len(set(lines)) == 1:
return Repetition(text=lines[0], count=self.count)
return None
detect_loops = DetectLoops(stream_detector=RepeatedLines())
action decides what happens when a loop is detected.
The capability enqueues a SystemPromptPart with RunContext.enqueue, which joins the request being prepared. It keeps the default conversation scope, so like a course correction it keeps applying on later requests instead of being shown once, and later requests send it unchanged. For example:
Your last 3 calls to `read_file` used the same arguments and returned the same result, so calling it again will not change the outcome. Change your approach, or explain what is blocking you.
The text names tools using only letters, digits, and _; any other character becomes _. The real names, and the pattern, are in the part’s metadata:
{'origin': 'pydantic-ai-harness.detect_loops.nudge.v1', 'pattern': 'repeated_result', 'tool_names': ['read_file']}
Find nudges in history by that origin, not by their text (identifying system prompts). On a model without inline system prompts, Pydantic AI sends the part as <system> user text, as it does any mid-conversation system prompt.
For a loop within a response, the stream is also stopped and the request made again, with the nudge. The nudge is request-scoped there: the response that looped is gone, so it’s sent with that one request instead of staying in the conversation. The capability raises ModelRetry, so the model also sees Your previous response was rejected because it kept repeating itself. as retry feedback, and each such retry counts against the agent’s output retries: a model that keeps looping ends the run with UnexpectedModelBehavior once they run out. A streamed response that was stopped isn’t kept in history, and the tokens it used aren’t added to the run’s usage. A response that arrived whole stays in history ahead of the retry, as any rejected response does.
run_stream() can’t make a request again once the run’s output has started streaming, as output text or an output tool call. A loop found from then on ends the run with UnexpectedModelBehavior, after the output streamed so far. A loop found before that, in thinking or in a function tool call’s arguments, is retried as usual. Use agent.run() with an event_stream_handler, or agent.iter(), to have loops in the output retried too.
A nudge doesn’t stop a model that ignores it. Combine it with UsageLimits for a hard stop. A stopped stream adds no request or tokens to the run’s usage, so for a loop within a response the hard stop is the output retries, or action='error'.
The capability raises LoopDetectedError, stopping the stream first for a loop within a response. It’s a subclass of AgentRunError, which ends the run. The detected loop is on its loop attribute:
from pydantic_ai import Agent
from pydantic_ai.messages import ModelMessage, ModelResponse, ToolCallPart
from pydantic_ai.models.function import AgentInfo, FunctionModel
from pydantic_ai_harness import DetectLoops
from pydantic_ai_harness.detect_loops import LoopDetectedError
def stuck_model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
return ModelResponse(parts=[ToolCallPart('read_file', {'path': 'missing.txt'})])
agent = Agent(FunctionModel(stuck_model), capabilities=[DetectLoops(action='error')])
@agent.tool_plain
def read_file(path: str) -> str:
return 'Error: file not found'
try:
agent.run_sync('Summarize missing.txt')
except LoopDetectedError as error:
print(error.loop.pattern, error.loop.tool_names, error.loop.count)
#> repeated_result ('read_file',) 3
Pass a sync or async function to decide yourself. It’s called with the run context and a DetectedLoop: raise from it to stop the run, or call ctx.enqueue(...) to steer the model your own way. For a loop within a response, the response keeps streaming when the handler returns; raise ModelRetry from it to stop the stream and make the request again, rejecting the response as a nudge does.
import logging
from pydantic_ai import Agent, RunContext
from pydantic_ai.messages import SystemPromptPart
from pydantic_ai_harness import DetectLoops
from pydantic_ai_harness.detect_loops import DetectedLoop
logger = logging.getLogger(__name__)
async def on_loop(ctx: RunContext[object], loop: DetectedLoop) -> None:
logger.warning('Agent loop: %s %s', loop.pattern, loop.tool_names)
ctx.enqueue(SystemPromptPart('You are repeating yourself. Summarize what you know and stop.'))
agent = Agent('anthropic:claude-opus-5-5', capabilities=[DetectLoops(action=on_loop)])
A DetectedLoop has:
pattern: which of the eight patterns it is.tool_names: the tools involved, one or two (none forrepeated_text,repeated_thinkingandrepeated_stream_text).count: how many calls, cycles, or responses repeated, or how many times the passage repeated within a response.window: how many recent tool calls (responses, forrepeated_text) the check looked at; for a loop within a response, how many of the part’s characters, or forrepeated_parallel_callhow many of the response’s tool calls.fingerprints: short stable hashes of the repeated calls (tool name and canonical arguments), text, or passage. The same call has the same fingerprint in every run. They don’t contain the arguments in the clear, but a short argument, such as a user id, can be recovered by hashing candidate values.message: the text the nudge would send.passage: the passage that repeated within a response, as it appears at the end of the part, orNonefor the other patterns. It’s the model’s own text.
What a run recorded lives in memory, in the instance for_run creates for that run. Under durable execution the recording and detection hooks (after_model_request and before_model_request) run in workflow code, so when Temporal, DBOS, or Prefect replays a run, they run again in the same order over the journaled responses and reach the same decisions. A handler runs there too, so keep it deterministic and free of I/O: log through the engine’s workflow logger, or move I/O into a durable capability operation. LoopDetectedError is an AgentRunError, so under Temporal it fails the workflow rather than the workflow task.
A response streams inside the durable model request unit (activity, step or task), and the workflow only sees it whole, so the checks within a response run on the whole response, in workflow code, and the stream isn’t stopped early. LoopJudge never asks its model in workflow code, where that model call wouldn’t be checkpointed and could be repeated on replay: only its heuristic runs there, which is deterministic. A LoopDetector of your own runs in workflow code too, so keep it deterministic and free of I/O, like a handler.
Each detection emits a zero-duration loop detected span through ctx.tracer, so it shows in the run’s trace next to the model request it changed. It’s a no-op unless the agent is instrumented.
| Attribute | Value |
|---|---|
detect_loops.pattern | The pattern, such as repeated_result |
detect_loops.action | nudge, error, or handler |
detect_loops.count | DetectedLoop.count |
detect_loops.window | DetectedLoop.window |
detect_loops.tool_names | The tools involved |
detect_loops.fingerprints | The hashes of the repeated calls or text, only when trace_include_content is enabled |
detect_loops.passage | The passage that repeated within a response, only when trace_include_content is enabled |
Without trace_include_content, the span contains no arguments, results, or response text. The fingerprints are left out too, because a short argument can be recovered from its hash. Checks that find nothing emit nothing.
When a LoopJudge fails or times out, a zero-duration loop judge failed span records it, with the exception’s class name in error.type. The judge agent built from model= is not instrumented, so the output it’s shown is not recorded even when global instrumentation is on and the host agent leaves content out. A judge agent= you pass keeps its own instrumentation settings.
- Several
DetectLoopson one agent run independently. Each reports the loops its own settings describe, so you can, for example, nudge at the defaults and add a second one with higher thresholds andaction='error'to stop a run that ignores the nudge. - System Reminders re-inject guidance on a cadence or condition, and Trajectory Judge asks a second model whether the run is on track. By default
DetectLoopsneeds no second model and only acts on exact repetition; aLoopJudgeadds a small model for loops within a response that aren’t exact.
DetectLoops does not detect a run that keeps exceeding the model’s context window, and it doesn’t truncate, restart, or roll back the run: compaction and your own handler cover those.
See the source.
Bases: AbstractCapability[AgentDepsT]
Detect when an agent repeats the same actions without making progress, and interrupt it.
Each model response’s tool calls and text are recorded as it arrives, and each call’s result from the
request that follows it. Before each model request, the run so far is checked for four patterns: the
same tool call made repeated_call_threshold times within the last window tool calls, the same
tool call returning the same result repeated_result_threshold times in a row, two tool calls
alternating for alternating_calls_threshold cycles, and repeated_text_threshold consecutive
responses without tool calls whose text is the same. Set a threshold to None to turn that check off.
Each response is also checked on its own, as it streams: its thinking, its text and each tool call’s
arguments are handed to stream_detector every stream_check_every characters, to catch a model
repeating the same passage, and the same tool call made repeated_parallel_call_threshold times in the
response is reported before any of them run. A response that isn’t streamed gets the same checks when
it arrives.
On detection, action runs: 'nudge' (the default) adds a system prompt to the conversation, from
the current request on, asking the model to change its approach, and for a loop within a response
also stops the stream and makes the request again; 'error' raises LoopDetectedError; and a
LoopHandler is called with the DetectedLoop. The calls or text that formed the loop are then not
counted again, so the same loop has to build up again before it is reported a second time.
from pydantic_ai import Agent
from pydantic_ai_harness import DetectLoops
agent = Agent('anthropic:claude-opus-5-5', capabilities=[DetectLoops()])
Only the current run’s responses are recorded, so a run that continues an earlier conversation starts with nothing counted. Compaction that later drops or rewrites messages doesn’t change what was recorded.
How many of the most recent tool calls the call-based checks look at.
Type: int Default: 10
Report a tool call (same tool, same arguments) made this many times within window.
Report a tool call that returned the same result each of the last this-many times it was made
within window, with no different result in between.
Report two different tool calls made in turn (A-B-A-B) for this many A-B cycles.
Report this many consecutive responses without tool calls whose text is the same, ignoring case and whitespace.
How each response’s thinking, text and tool call arguments are checked for a repeating passage.
RepetitionDetector by default, a text heuristic. Pass LoopJudge to have a model confirm or find loops,
your own LoopDetector, or None to turn these checks off.
Type: LoopDetector[AgentDepsT] | None Default: field(default_factory=(lambda: RepetitionDetector[AgentDepsT]()))
Which parts of a response stream_detector checks.
Type: Sequence[StreamChannel] Default: ('thinking', 'text', 'tool_args')
Check each part every this many characters, and once more when it ends.
Type: int Default: 256
Report a tool call (same tool, same arguments) made this many times in one response, before any of them run.
What to do when a loop is detected.
'nudge': enqueue a system prompt telling the model which loop it is in and asking it to change its approach. It joins the current request and keeps the default conversation scope, so it keeps applying on later requests instead of being shown once. For a loop within a response, the stream is also stopped and the request made again through aModelRetry, and the nudge is request-scoped, so only that request carries it.'error': raiseLoopDetectedError, ending the run.- a
LoopHandler: call it with the run context and theDetectedLoop. For a loop within a response, the response continues when it returns; raiseModelRetryfrom it to stop the stream and make the request again.
Type: Literal[‘nudge’, ‘error’] | LoopHandler[AgentDepsT] Default: 'nudge'
False, so a run isn’t made to stream for these checks: a response that isn’t streamed is checked whole.
Type: bool
def get_ordering() -> CapabilityOrdering
Run outermost, so the newest results are read before other capabilities, such as compaction, rewrite them.
CapabilityOrdering
@async
def for_run(ctx: RunContext[AgentDepsT]) -> DetectLoops[AgentDepsT]
Return a fresh instance, so runs don’t share what they recorded.
DetectLoops[AgentDepsT]
@async
def after_model_request(
ctx: RunContext[AgentDepsT],
*,
request_context: ModelRequestContext,
response: ModelResponse,
) -> ModelResponse
Record the response’s tool calls, or its text when it has none.
@async
def before_model_request(
ctx: RunContext[AgentDepsT],
request_context: ModelRequestContext,
) -> ModelRequestContext
Record the results of the previous response’s tool calls, then act on the first loop found.
@async
def wrap_run_event_stream(
ctx: RunContext[AgentDepsT],
*,
stream: AsyncIterable[AgentStreamEvent],
) -> AsyncIterable[AgentStreamEvent]
Check the response being streamed as its events pass, holding an event that completes a loop until it’s acted on.
AsyncIterable[AgentStreamEvent]
@async
def wrap_model_request(
ctx: RunContext[AgentDepsT],
*,
request_context: ModelRequestContext,
handler: WrapModelRequestHandler,
) -> ModelResponse
Act on loops within the response: as it streams, or once it has arrived whole.
A loop DetectLoops found in the run.
Passed to a LoopHandler, and carried by LoopDetectedError as loop.
Which kind of loop it is.
Type: LoopPattern
The tools involved: one for 'repeated_call', 'repeated_result', 'repeated_tool_args' and
'repeated_parallel_call', two for 'alternating_calls', none for the others.
How many times the pattern repeated: calls for 'repeated_call', 'repeated_result' and
'repeated_parallel_call', A-B cycles for 'alternating_calls', responses for 'repeated_text', and
repeats of the passage for the other patterns within one response.
Type: int
How much the detection looked at: recent tool calls for the call patterns, responses for
'repeated_text', the response’s tool calls so far for 'repeated_parallel_call', and characters
of the part for the other patterns within one response.
Type: int
Stable hashes of what repeated.
For the call patterns, each covers a tool name and its canonical arguments: one for 'repeated_call',
'repeated_result' and 'repeated_parallel_call', two for 'alternating_calls'. For 'repeated_text',
it’s the hash of the normalized text, and for the other patterns the hash of the passage that repeated.
They don’t contain argument values or text in the clear, but a short argument such as a user id can be
recovered by hashing candidate values.
The explanation sent to the model as the nudge, and used as the LoopDetectedError message.
Type: str
The passage that repeated, for 'repeated_thinking', 'repeated_stream_text' and
'repeated_tool_args'; None for the other patterns. Unlike fingerprints, it’s the model’s own text.
Type: str | None Default: None
Bases: AgentRunError
Raised by DetectLoops(action='error') when it detects a loop.
Subclasses AgentRunError, so code that already stops on agent run errors stops on this one too.
The loop that was detected.
Type: DetectedLoop Default: loop
A sync or async function DetectLoops calls with each loop it detects.
Raise from it to stop the run, or call ctx.enqueue(...) to steer the model your own way.
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT], DetectedLoop], Awaitable[None] | None]
Which kind of loop was detected.
Across the run’s responses:
'repeated_call': one tool call (same tool, same arguments) made many times among the recent calls.'repeated_result': one tool call that returned the same result each of the last several times it was made.'alternating_calls': two different tool calls made in turn, A-B-A-B.'repeated_text': consecutive responses without tool calls whose text is the same.
Within one response, as it streams:
'repeated_thinking': a thinking part that keeps repeating the same passage.'repeated_stream_text': a text part that keeps repeating the same passage.'repeated_tool_args': one tool call’s arguments that keep repeating the same passage.'repeated_parallel_call': the same tool call (same tool, same arguments) made many times in one response.
Type: TypeAlias Default: Literal['repeated_call', 'repeated_result', 'alternating_calls', 'repeated_text', 'repeated_thinking', 'repeated_stream_text', 'repeated_tool_args', 'repeated_parallel_call']
Bases: ABC, Generic[AgentDepsT]
Decide whether the text of one model response part is looping.
DetectLoops calls detect every stream_check_every characters of each thinking part, text part and
tool call’s arguments as the response streams, and once more at the end of each part. A response that
isn’t streamed is checked the same way when it arrives, so it gets the same answers.
Subclass it to plug in your own methodology. RepetitionDetector is the default, and LoopJudge
asks a model. One instance serves every run of the agent, concurrent ones included, so keep it
stateless or key any state off the RunContext.
How many of a part’s most recent characters detect is given.
Type: int
@abstractmethod
@async
def detect(ctx: RunContext[AgentDepsT], sample: StreamSample) -> Repetition | None
Return what repeats at the end of sample.text, or None if it isn’t looping.
Repetition | None
Bases: LoopDetector[AgentDepsT]
Report text that ends in the same passage repeated back to back: the degenerate loop a model gets stuck in.
The passage has to be between min_period and max_period characters long, use at least
min_distinct_chars different characters, repeat at least min_repeats times in a row, and the
repeats have to cover at least min_chars characters. Text whose repeating unit is shorter than
min_period, such as a divider line, is not reported, even when the passage is a multiple of that
unit.
The defaults are set so that repetitive content written on purpose, such as a grid of numbers, table
rules or a few dozen identical rows, isn’t reported, at the cost of catching a real loop only after
about 2,000 characters. Content that repeats more than that, like a fixture with hundreds of identical
rows, is reported: raise the thresholds, or leave 'tool_args' out of stream_channels, if your agent
writes such content.
It compares characters exactly, so it’s cheap enough to run on every check and gives the same answer every time.
The shortest passage that counts, in characters.
Type: int Default: 20
The longest passage that counts, in characters.
Type: int Default: 2000
How many times in a row the passage has to repeat.
Type: int Default: 8
How many characters the repeats have to cover together.
Type: int Default: 2000
How many different characters the passage has to use, so a row of numbers or a table rule doesn’t count.
Type: int Default: 8
Enough characters to hold min_repeats repeats of the longest passage.
Type: int
@async
def detect(ctx: RunContext[AgentDepsT], sample: StreamSample) -> Repetition | None
Find the shortest passage that the end of sample.text repeats enough times.
Repetition | None
def find(text: str) -> Repetition | None
Find the shortest passage that the end of text repeats enough times, without a RunContext.
Repetition | None
Bases: LoopDetector[AgentDepsT]
Ask a model whether a response part is looping, on a heuristic’s suspicion and optionally on a cadence.
Each check runs heuristic first. The judge is asked only when the heuristic suspects a loop, which it
then confirms or overrules, and, with every set, each time a part passes another every characters,
so it can catch loops that don’t repeat exactly. Its answer is used in place of the heuristic’s.
Use a small, fast model: the stream waits for each answer, and the question needs a quick intuitive read of the text rather than reasoning.
If the judge fails or doesn’t answer within timeout seconds, the heuristic’s answer is used, so a
judge outage never breaks the run. Inside a durable workflow or flow (Temporal, DBOS, Prefect) the
judge is never asked, since its model calls would run in workflow code without being checkpointed:
only the heuristic runs there.
The judge model. Provide this or agent, not both.
Type: Model | KnownModelName | str | None Default: None
A judge agent, for your own instructions, settings or fallback models. Each check runs it with the judge’s
instructions added to its own and with its own output_type, so it must not have output validators.
Type: Agent[None, object] | None Default: None
The detector whose suspicion the judge confirms, and whose answer is used when the judge can’t give one.
Type: LoopDetector[AgentDepsT] Default: field(default_factory=(lambda: RepetitionDetector[AgentDepsT]()))
Also ask the judge each time a part passes another this-many characters, suspicion or not. None asks
only on suspicion.
Type: int | None Default: None
How many of the part’s most recent characters the judge is shown.
Type: int Default: 4000
How many seconds to wait for the judge before using the heuristic’s answer.
Type: float Default: 5.0
Enough characters for the heuristic and the judge.
Type: int
@async
def detect(ctx: RunContext[AgentDepsT], sample: StreamSample) -> Repetition | None
Run the heuristic, and ask the judge when it suspects a loop or the cadence is due.
Repetition | None
The latest text of one response part, handed to a LoopDetector each time the part is checked.
Which kind of part the text is from.
Type: StreamChannel
The part’s most recent text, at most LoopDetector.sample_chars characters of it.
Type: str
How many characters the part has had so far, including any that no longer fit in text.
Type: int
How many of those arrived since the part was last checked.
Type: int
The tool being called, for 'tool_args'; None otherwise.
What a LoopDetector found repeating at the end of a StreamSample.
The passage that repeats.
Type: str
How many times it repeats.
Type: int
Which part of a model response a check looks at.
'thinking': a thinking part.'text': a text part.'tool_args': the arguments of one tool call, as the JSON the model writes.
Type: TypeAlias Default: Literal['thinking', 'text', 'tool_args']