Issue Station
Sign In
Tools hereToolbox

crewai - ✅(Solved) Fix [FEATURE] Agent Loop Detection Middleware — detect and break repetitive behavioral patterns [2 pull requests, 5 comments, 4 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
crewAIInc/crewAI#4682•Fetched 2026-04-08 00:40:43
View on GitHub
Comments
5
Participants
4
Timeline
14
Reactions
0
Author
sicmundusicmundu
Participants
aeoessaeoessagent-morrowagent-morrowaibenyclaude-coderaibenyclaude-codersicmundusicmundu
Timeline (top)
cross-referenced ×5commented ×4referenced ×3mentioned ×1

When agents run in autonomous loops (especially with allow_delegation=True or complex multi-step tasks), they can fall into repetitive behavioral patterns — executing the same sequence of actions, re-researching the same information, or generating similar outputs across iterations without making real progress toward the goal.

Root Cause

This is a well-known failure mode in autonomous agent systems. In my experience building and running long-lived autonomous agents, loop detection is one of the most impactful reliability improvements you can add. Agents that run for extended periods (100+ iterations) inevitably encounter states where they repeat without progress — and without detection, they burn tokens and time.

The CrewAI framework is well-positioned to solve this at the framework level rather than leaving it to individual implementations.

Fix Action

Fixed

PR fix notes

PR #4683: feat: add agent loop detection middleware (#4682)

Description (problem / solution / changelog)

feat: add agent loop detection middleware (#4682)

Summary

Implements a LoopDetector middleware that monitors agent tool calls for repetitive patterns and intervenes to break loops. Addresses #4682.

New files:

  • agents/loop_detector.py — LoopDetector class using a sliding-window deque over ToolCallRecord entries. Configurable window_size, repetition_threshold, and on_loop action ("inject_reflection", "stop", or a custom callable).
  • events/types/loop_events.py — LoopDetectedEvent for observability via the event bus.
  • tests/agents/test_loop_detector.py — 50 unit tests covering the detector, event, executor integration, and public API export.

Modified files:

  • agents/agent_builder/base_agent.py — adds optional loop_detector field to BaseAgent.
  • agents/crew_agent_executor.py — integrates loop detection into all 4 execution paths (sync/async ReAct and native tools) via new _record_and_check_loop helper. Emits LoopDetectedEvent, injects reflection prompt or stops execution when loop detected.
  • translations/en.json — adds "loop_detected" i18n string for reflection prompt.
  • __init__.py — exports LoopDetector from public API.

Usage:

from crewai import Agent, LoopDetector

agent = Agent(
    role="Researcher",
    goal="Find insights",
    loop_detector=LoopDetector(
        window_size=5,
        repetition_threshold=3,
        on_loop="inject_reflection"
    )
)

Updates since last revision

  • Fixed ReAct loop integration bug — The loop check previously accessed formatted_answer.tool after _handle_agent_action, which could return AgentFinish (causing AttributeError). Now tool name/input are captured before _handle_agent_action is called, in both sync and async ReAct paths.

Review & Testing Checklist for Human

  • Test with a real agent stuck in a loop — All 50 tests are unit tests with mocked executors. Run an agent with loop_detector=LoopDetector() that actually gets stuck repeating the same tool call 3+ times and verify:

    • The reflection prompt is injected and the agent tries a different approach
    • on_loop="stop" forces a final answer
    • A custom callable callback is invoked correctly
    • LoopDetectedEvent is emitted (check via event listener)

  • Review on_loop="stop" behavior — The stop path reuses handle_max_iterations_exceeded to force a final answer. Verify the resulting output/message makes sense to the user (it may say "max iterations exceeded" rather than "loop detected"). Consider whether a dedicated handler would be clearer.

  • Verify parallel native tool loop detection — The parallel execution path reads execution_result.get("tool_args", "") from the result dict. tool_args was added to the return value of _execute_single_native_tool_call — confirm this propagates correctly when tools run in ThreadPoolExecutor.

  • Check i18n string formatting — Verify the loop_detected translation in en.json renders correctly with {repeated_tool} and {count} placeholders in a real execution.

Notes

Session: Devin Session Requested by: João

Changed files

  • lib/crewai/src/crewai/__init__.py (modified, +2/-0)
  • lib/crewai/src/crewai/agents/agent_builder/base_agent.py (modified, +10/-0)
  • lib/crewai/src/crewai/agents/crew_agent_executor.py (modified, +134/-0)
  • lib/crewai/src/crewai/agents/loop_detector.py (added, +210/-0)
  • lib/crewai/src/crewai/events/types/loop_events.py (added, +48/-0)
  • lib/crewai/src/crewai/translations/en.json (modified, +1/-0)
  • lib/crewai/tests/agents/test_loop_detector.py (added, +523/-0)

PR #4684: feat: Add LoopDetector middleware for agent loop detection (#4682)

Description (problem / solution / changelog)

Summary

Implements a LoopDetector middleware that detects when agents get stuck in repetitive action loops and provides graceful exit strategies.

Related Issue

Addresses #4682 — [FEATURE] Agent Loop Detection

What it does

  • Tracks agent actions using a sliding window approach
  • Detects repetition patterns via similarity hashing (exact match + fuzzy n-gram)
  • Configurable thresholds: window size, similarity threshold, max consecutive repeats
  • Multiple exit strategies: raise exception, return summary, trigger callback
  • Lightweight: no external dependencies beyond Python stdlib

Key classes

  • LoopDetector — core detection engine with configurable parameters
  • ActionRecord — dataclass for tracking individual agent actions
  • LoopDetectionStrategy — enum for exit strategies (RAISE, SUMMARIZE, CALLBACK)

Tests

Includes comprehensive test suite covering:

  • No false positives with varied actions
  • Detection of exact repetition loops
  • Detection of similar (fuzzy) action loops
  • Configurable threshold behavior
  • Callback strategy execution
  • Edge cases (empty actions, single actions)

Why this matters

Agents in production frequently get stuck in repetitive loops — retrying the same failed action, oscillating between two states, or generating nearly-identical outputs. This middleware provides a clean, pluggable detection mechanism that can be integrated into CrewAI's agent execution pipeline.

Built with real-world loop detection experience. 🔄

<!-- CURSOR_SUMMARY -->

[!NOTE] Medium Risk Adds new loop-detection logic and a new test module; while largely additive, it introduces behavioral heuristics (similarity/cycle detection) and the included tests use a nonstandard import/path setup that could affect CI reliability.

Overview Introduces a new crewai.utilities.loop_detector module that records recent agent actions in a sliding window and detects looping via exact repeats, high text similarity (SequenceMatcher), and short cyclic action-type patterns, emitting loop events and optional callbacks.

Adds APIs to suggest an exit strategy (suggest_exit_strategy), report metrics (get_stats), and reset state, plus a new test file covering loop detection modes, strategy selection, stats/reset, and callback invocation.

<sup>Written by Cursor Bugbot for commit 7c8ddd97a178ffed8f51e7840d5d7cd6601f45ef. This will update automatically on new commits. Configure here.</sup>

<!-- /CURSOR_SUMMARY -->

Changed files

  • lib/crewai/src/crewai/utilities/loop_detector.py (added, +246/-0)
  • lib/crewai/tests/utilities/test_loop_detector.py (added, +154/-0)

Code Example

from crewai import Agent, Crew
from crewai.middleware import LoopDetector

loop_detector = LoopDetector(
    window_size=5,           # actions to track
    similarity_threshold=0.8, # how similar actions need to be
    on_loop="inject_reflection",  # or "stop", "callback", "escalate_to_manager"
)

agent = Agent(
    role="Researcher",
    goal="Find novel insights about X",
    middleware=[loop_detector],
)
RAW_BUFFERClick to expand / collapse

Feature Area

Core functionality / Agent behavior

Description

When agents run in autonomous loops (especially with allow_delegation=True or complex multi-step tasks), they can fall into repetitive behavioral patterns — executing the same sequence of actions, re-researching the same information, or generating similar outputs across iterations without making real progress toward the goal.

Proposed Solution: Agent Loop Detection Middleware

A lightweight middleware layer that monitors agent action history and detects repetitive patterns in real-time. When a loop is detected, the middleware could:

  1. Detect repetition — Track a sliding window of recent actions/tool calls and flag when similarity exceeds a threshold (e.g., same tool called 3+ times with similar arguments)
  2. Escalate or intervene — Automatically inject a meta-prompt like "You appear to be repeating actions. Consider a different approach" or trigger a configurable callback
  3. Log loop events — Emit structured telemetry so users can diagnose where agents get stuck

Example API sketch:

from crewai import Agent, Crew
from crewai.middleware import LoopDetector

loop_detector = LoopDetector(
    window_size=5,           # actions to track
    similarity_threshold=0.8, # how similar actions need to be
    on_loop="inject_reflection",  # or "stop", "callback", "escalate_to_manager"
)

agent = Agent(
    role="Researcher",
    goal="Find novel insights about X",
    middleware=[loop_detector],
)

Why This Matters

This is a well-known failure mode in autonomous agent systems. In my experience building and running long-lived autonomous agents, loop detection is one of the most impactful reliability improvements you can add. Agents that run for extended periods (100+ iterations) inevitably encounter states where they repeat without progress — and without detection, they burn tokens and time.

The CrewAI framework is well-positioned to solve this at the framework level rather than leaving it to individual implementations.

Additional Context

Related concepts:

  • LangGraph's cycle detection in graph-based agent flows
  • The max_iter parameter in CrewAI already provides a crude upper bound, but doesn't detect behavioral repetition
  • Research on "agent drift" and metacognitive monitoring in autonomous systems

Happy to contribute a proof-of-concept implementation if there's interest.

extent analysis

Fix Plan

To address the issue of agents falling into repetitive behavioral patterns, we will implement the proposed Agent Loop Detection Middleware. Here are the concrete steps:

  • Implement the LoopDetector class with the following methods:
    • __init__: Initialize the middleware with parameters such as window_size, similarity_threshold, and on_loop.
    • detect_repetition: Track a sliding window of recent actions and flag when similarity exceeds the threshold.
    • escalate_or_intervene: Automatically inject a meta-prompt or trigger a configurable callback when a loop is detected.
    • log_loop_events: Emit structured telemetry for diagnosis.
  • Integrate the LoopDetector middleware into the Agent class:
    • Add a middleware parameter to the Agent constructor.
    • Iterate over the middleware list and apply each middleware to the agent's actions.

Example Code

from crewai import Agent, Crew
from crewai.middleware import LoopDetector

class LoopDetector:
    def __init__(self, window_size, similarity_threshold, on_loop):
        self.window_size = window_size
        self.similarity_threshold = similarity_threshold
        self.on_loop = on_loop
        self.action_history = []

    def detect_repetition(self, action):
        # Calculate similarity between current action and recent actions
        similarity = self.calculate_similarity(action, self.action_history)
        if similarity > self.similarity_threshold:
            return True
        return False

    def escalate_or_intervene(self):
        # Inject meta-prompt or trigger callback
        if self.on_loop == "inject_reflection":
            print("You appear to be repeating actions. Consider a different approach")

    def log_loop_events(self):
        # Emit structured telemetry
        print("Loop detected")

    def calculate_similarity(self, action, action_history):
        # Calculate similarity between actions (e.g., using cosine similarity)
        pass

loop_detector = LoopDetector(
    window_size=5,
    similarity_threshold=0.8,
    on_loop="inject_reflection",
)

agent = Agent(
    role="Researcher",
    goal="Find novel insights about X",
    middleware=[loop_detector],
)

# Apply middleware to agent actions
for action in agent.actions:
    loop_detector.detect_repetition(action)
    if loop_detector.detect_repetition(action):
        loop_detector.escalate_or_intervene()
        loop_detector.log_loop_events()

Verification

To verify that the fix worked, we can test the LoopDetector middleware with a sample agent and actions. We can simulate repetitive actions and check if the middleware correctly detects the loop and intervenes.

Extra Tips

  • The calculate_similarity method can be implemented using various similarity metrics such as cosine similarity, Jaccard similarity, or Levenshtein distance.
  • The on_loop parameter can be extended to support more callback functions or meta-prom

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#permission error#memory optimization#batch processing#GPU compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING