Loop Detection

Detect and break stuck tool-call loops automatically

Loop detection prevents agents from calling the same tool repeatedly with no progress.

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="Stop repeating the same failing tool pattern",
)

agent.start("Fix the deployment issue")

Every Agent you create has this protection on by default — no import, no flag. Polling a status endpoint that actually changes state is not flagged; a genuine stall or A -> B -> A -> B oscillation is.

Quick Start

1. It's already on

   Result-aware tool-loop detection runs on every Agent. No import, no configuration.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="assistant",
       instructions="You are a helpful assistant.",
   )
   
   # Result-aware tool-loop detection is enabled on every Agent.
   # No import, no configuration - just run the agent.
   agent.start("Read config.yaml and summarise it.")

2. Tune the thresholds

   Override the per-agent config before the first tool call.

   from praisonaiagents import Agent
   from praisonaiagents.agent.loop_detection import LoopDetectionConfig
   
   agent = Agent(instructions="Poll a job status endpoint.")
   
   agent._loop_detector_config = LoopDetectionConfig(
       enabled=True,
       warn_threshold=5,
       critical_threshold=10,
   )
   
   agent.start("Check whether job-42 finished.")

3. Turn it off

   Disable detection for deterministic replay agents that repeat identical calls on purpose.

   from praisonaiagents import Agent
   from praisonaiagents.agent.loop_detection import LoopDetectionConfig
   
   agent = Agent(instructions="Deterministic replay agent")
   agent._loop_detector_config = LoopDetectionConfig(enabled=False)

How It Works

The detector records each tool call before execution, checks three detectors, then back-fills the result hash after execution so progress breaks the streak.

A warning fires once per autonomous turn — the next iteration’s prompt is prefixed with [System: repeated <detector> detected. Try a different approach. …], giving the model one chance to change course before a critical verdict blocks execution entirely.

Detectors

Configuration Options

Common Patterns

Polling a status endpoint

Raise thresholds and keep detection on.

from praisonaiagents import Agent
from praisonaiagents.agent.loop_detection import LoopDetectionConfig

agent = Agent(instructions="Poll deployment status every second.")
agent._loop_detector_config = LoopDetectionConfig(
    enabled=True,
    warn_threshold=30,
    critical_threshold=60,
)
agent.start("Wait for deployment-42 to finish.")

Aggressive detection for short-lived agents

from praisonaiagents import Agent
from praisonaiagents.agent.loop_detection import LoopDetectionConfig

agent = Agent(instructions="Quick web scraper")
agent._loop_detector_config = LoopDetectionConfig(
    enabled=True,
    warn_threshold=3,
    critical_threshold=5,
)
agent.start("Fetch the homepage title.")

Disable a specific detector

Turn off ping_pong when two tools legitimately alternate.

from praisonaiagents import Agent
from praisonaiagents.agent.loop_detection import LoopDetectionConfig

agent = Agent(instructions="Two-tool workflow")
agent._loop_detector_config = LoopDetectionConfig(
    enabled=True,
    detectors={"generic_repeat": True, "poll_no_progress": True, "ping_pong": False},
)

User Interaction Flow

Here’s what a user sees when the detector fires during an autonomous run.

• After the warning fires, the next autonomous turn’s prompt is prefixed with [System: repeated <detector> detected. Try a different approach. <message>].
• If the agent still cannot break out of the pattern and hits critical_threshold on the same (tool, args) fingerprint, the offending call is skipped and the tool result becomes {"error": "...", "loop_blocked": True} — the model sees this on its next observation and typically self-corrects.
• The whole path is a soft-block, not an exception — trace spans, stream events, and AFTER_TOOL hooks all still fire, so telemetry stays consistent.

Relationship to Loop Guard

Loop Detection is now always-on alongside Loop Guard (docs). Loop Detection catches identical-argument / no-progress / ping-pong fingerprints at any frequency and back-fills result hashes so polling with progress is not flagged. Loop Guard counts per-turn tool calls with idempotent-vs-mutating thresholds. Both fire through the same blocked_result path, so trace spans, stream events, and AFTER_TOOL hooks stay consistent regardless of which one triggers.

Best Practices

Related