Skip to content

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

Usage

Terminal
pip install 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.

What counts as a loop

PatternReported whenSetting (default)
repeated_callThe 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_resultThe same tool call returned the same result each of the last this-many times it was made within window.repeated_result_threshold (3)
alternating_callsTwo different tool calls are made in turn, A-B-A-B, for this many A-B cycles.alternating_calls_threshold (3)
repeated_textThis 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 ModelRetry with the same message each time returns the same result, so a call that keeps failing the same way is a repeated_result loop.
  • 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. DetectLoops runs 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.

Polling and retries

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.

Loops within a response

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.

PatternReported whenSetting (default)
repeated_thinkingA thinking part keeps repeating the same passage.stream_detector (RepetitionDetector())
repeated_stream_textA text part keeps repeating the same passage.stream_detector
repeated_tool_argsOne tool call’s arguments keep repeating the same passage.stream_detector
repeated_parallel_callThe 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.

The default heuristic

RepetitionDetector looks at the end of each part and reports a passage repeated back to back:

SettingDefaultMeaning
min_period20The 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_period2000The longest passage that counts.
min_distinct_chars8How many different characters the passage has to use, so a row of numbers or a table rule doesn’t count.
min_repeats8How many times in a row the passage has to repeat.
min_chars2000How 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.

A model judge

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.

Your own detector

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())

Actions

action decides what happens when a loop is detected.

'nudge' (default)

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'.

'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

A handler

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 for repeated_text, repeated_thinking and repeated_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, for repeated_text) the check looked at; for a loop within a response, how many of the part’s characters, or for repeated_parallel_call how 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, or None for the other patterns. It’s the model’s own text.

Durable execution

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.

Telemetry

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.

AttributeValue
detect_loops.patternThe pattern, such as repeated_result
detect_loops.actionnudge, error, or handler
detect_loops.countDetectedLoop.count
detect_loops.windowDetectedLoop.window
detect_loops.tool_namesThe tools involved
detect_loops.fingerprintsThe hashes of the repeated calls or text, only when trace_include_content is enabled
detect_loops.passageThe 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.

Composition

  • Several DetectLoops on 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 and action='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 DetectLoops needs no second model and only acts on exact repetition; a LoopJudge adds 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.

API reference

DetectLoops

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.

Attributes

window

How many of the most recent tool calls the call-based checks look at.

Type: int Default: 10

repeated_call_threshold

Report a tool call (same tool, same arguments) made this many times within window.

Type: int | None Default: 5

repeated_result_threshold

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.

Type: int | None Default: 3

alternating_calls_threshold

Report two different tool calls made in turn (A-B-A-B) for this many A-B cycles.

Type: int | None Default: 3

repeated_text_threshold

Report this many consecutive responses without tool calls whose text is the same, ignoring case and whitespace.

Type: int | None Default: 3

stream_detector

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]()))

stream_channels

Which parts of a response stream_detector checks.

Type: Sequence[StreamChannel] Default: ('thinking', 'text', 'tool_args')

stream_check_every

Check each part every this many characters, and once more when it ends.

Type: int Default: 256

repeated_parallel_call_threshold

Report a tool call (same tool, same arguments) made this many times in one response, before any of them run.

Type: int | None Default: 5

action

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 a ModelRetry, and the nudge is request-scoped, so only that request carries it.
  • 'error': raise LoopDetectedError, ending the run.
  • a LoopHandler: call it with the run context and the DetectedLoop. For a loop within a response, the response continues when it returns; raise ModelRetry from it to stop the stream and make the request again.

Type: Literal[‘nudge’, ‘error’] | LoopHandler[AgentDepsT] Default: 'nudge'

has_wrap_run_event_stream

False, so a run isn’t made to stream for these checks: a response that isn’t streamed is checked whole.

Type: bool

Methods

get_ordering
def get_ordering() -> CapabilityOrdering

Run outermost, so the newest results are read before other capabilities, such as compaction, rewrite them.

Returns

CapabilityOrdering

for_run

@async

def for_run(ctx: RunContext[AgentDepsT]) -> DetectLoops[AgentDepsT]

Return a fresh instance, so runs don’t share what they recorded.

Returns

DetectLoops[AgentDepsT]

after_model_request

@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.

Returns

ModelResponse

before_model_request

@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.

Returns

ModelRequestContext

wrap_run_event_stream

@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.

Returns

AsyncIterable[AgentStreamEvent]

wrap_model_request

@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.

Returns

ModelResponse

DetectedLoop

A loop DetectLoops found in the run.

Passed to a LoopHandler, and carried by LoopDetectedError as loop.

Attributes

pattern

Which kind of loop it is.

Type: LoopPattern

tool_names

The tools involved: one for 'repeated_call', 'repeated_result', 'repeated_tool_args' and 'repeated_parallel_call', two for 'alternating_calls', none for the others.

Type: tuple[str, …]

count

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

window

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

fingerprints

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.

Type: tuple[str, …]

message

The explanation sent to the model as the nudge, and used as the LoopDetectedError message.

Type: str

passage

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

LoopDetectedError

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.

Attributes

loop

The loop that was detected.

Type: DetectedLoop Default: loop

LoopHandler

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]

LoopPattern

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']

LoopDetector

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.

Attributes

sample_chars

How many of a part’s most recent characters detect is given.

Type: int

Methods

detect

@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.

Returns

Repetition | None

RepetitionDetector

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.

Attributes

min_period

The shortest passage that counts, in characters.

Type: int Default: 20

max_period

The longest passage that counts, in characters.

Type: int Default: 2000

min_repeats

How many times in a row the passage has to repeat.

Type: int Default: 8

min_chars

How many characters the repeats have to cover together.

Type: int Default: 2000

min_distinct_chars

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

sample_chars

Enough characters to hold min_repeats repeats of the longest passage.

Type: int

Methods

detect

@async

def detect(ctx: RunContext[AgentDepsT], sample: StreamSample) -> Repetition | None

Find the shortest passage that the end of sample.text repeats enough times.

Returns

Repetition | None

find
def find(text: str) -> Repetition | None

Find the shortest passage that the end of text repeats enough times, without a RunContext.

Returns

Repetition | None

LoopJudge

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.

Attributes

model

The judge model. Provide this or agent, not both.

Type: Model | KnownModelName | str | None Default: None

agent

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

heuristic

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]()))

every

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

max_chars

How many of the part’s most recent characters the judge is shown.

Type: int Default: 4000

timeout

How many seconds to wait for the judge before using the heuristic’s answer.

Type: float Default: 5.0

sample_chars

Enough characters for the heuristic and the judge.

Type: int

Methods

detect

@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.

Returns

Repetition | None

StreamSample

The latest text of one response part, handed to a LoopDetector each time the part is checked.

Attributes

channel

Which kind of part the text is from.

Type: StreamChannel

text

The part’s most recent text, at most LoopDetector.sample_chars characters of it.

Type: str

total_chars

How many characters the part has had so far, including any that no longer fit in text.

Type: int

new_chars

How many of those arrived since the part was last checked.

Type: int

tool_name

The tool being called, for 'tool_args'; None otherwise.

Type: str | None

Repetition

What a LoopDetector found repeating at the end of a StreamSample.

Attributes

text

The passage that repeats.

Type: str

count

How many times it repeats.

Type: int

StreamChannel

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']