[FEATURE] Agent Loop Detection Middleware — detect and break repetitive behavioral patterns

快速结论：当 CrewAI 中的 Agent 在长时间自主循环执行任务（尤其是开启 allow_delegation=True）时，可能出现重复执行相同动作或工具调用的行为模式，导致资源浪费且任务无进展。优先排查 max_iter 参数是否设置过低（但该参数无法检测行为重复），或考虑集成循环检测中间件。

问题场景

用户在使用 CrewAI 框架构建多 Agent 系统（如 Researcher Agent）时，Agent 在自动循环中反复执行相同序列的动作（如重复调用同一个工具并传入相似参数）、重新研究相同信息或生成相似输出，但未向目标推进。此问题在使用 allow_delegation=True 或复杂多步骤任务时尤为常见。

报错原文

[FEATURE] Agent Loop Detection Middleware — detect and break repetitive behavioral patterns
// 非报错，而是功能提案。核心描述：
"agents 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."
// 循环检测逻辑示例（提案中）：
loop_info = detector.detect_loop()
// 返回示例：{"type": "exact_repeat", "period": 3, "pattern": [...]} 或 {"type": "action_clustering", "dominant_action": "search_tool", "ratio": 0.9}
// 干预消息示例："Loop detected: you've repeated this pattern {n} times. Try a different approach."

原因分析

此问题属于框架级别的已知失效模式。根本原因在于：当 Agent 运行在自主循环中（超过 100 次迭代时常见），缺乏对 行为级重复的实时检测。现有 max_iter 参数仅提供粗粒度的迭代上限，无法识别语义上的重复模式（如反复调用同一工具、循环在两种动作之间切换）。此外，跨会话的重复失败模式无法被内存中的滑动窗口检测（会话重启后窗口重置）。

环境排查

CrewAI 框架版本（建议检查是否已引入中间件或回调系统的支持）
Agent 配置中是否开启 allow_delegation=True
任务执行循环次数（推荐监控日志中工具调用序列）
是否使用 LangGraph 的循环检测机制作为对比参考

解决步骤

实现中间件集成：在 Agent 的 task pipeline 中钩入循环检测器。关键集成点：每次调用工具前 detector.record_action(tool_name, tool_input, prev_result)，调用后 loop_info = detector.detect_loop()。
代码示例（源自提案）：

from collections import deque
from hashlib import sha256

class LoopDetector:
    def __init__(self, window_size=10, similarity_threshold=0.85, max_repeats=3):
        self.window_size = window_size
        self.similarity_threshold = similarity_threshold
        self.max_repeats = max_repeats
        self.action_history = deque(maxlen=window_size*2)
        self.pattern_cache = {}
    
    def record_action(self, action_type, action_content, result_summary):
        fingerprint = self._fingerprint(action_type, action_content)
        self.action_history.append({"type": action_type, "fingerprint": fingerprint, "result_hash": sha256(result_summary.encode()).hexdigest()[:8]})
    
    def detect_loop(self):
        if len(self.action_history)  self.similarity_threshold:
                return {"type": "action_clustering", "dominant_action": action_type, "ratio": count/self.window_size}
        return None

处理循环检测结果：当 detect_loop() 返回非空时，注入系统消息，例如："Loop detected: you've repeated this pattern {n} times. Try a different approach." 或强制升级到人工/其他 Agent。参考提案中的 suggest_intervention() 方法。
持久化失败记录（可优先尝试）：为捕获跨会话重复失败，在循环检测触发时写入追加记录的持久化存储（如文件或数据库）。新会话开始时，对即将执行的动作进行关键字匹配（非 LLM 调用，避免延迟）。匹配到冲突时阻断并建议替代方案。
集成到 Agent 配置：通过中间件参数化，例如 LoopDetector(window_size=5, similarity_threshold=0.8, on_loop="inject_reflection")，适用于 CrewAI 的 Agent(middleware=[loop_detector]) 风格（提案中建议的 API）。

验证方法

通过模拟循环场景（如重复调用同一搜索工具三次以上）进行测试：
1. 检查循环检测器是否正确记录动作指纹和哈希。
2. 确认 detect_loop() 返回正确的循环类型（exact_repeat 或 action_clustering）以及周期/阈值信息。
3. 验证干预动作（如注入反思系统消息）是否确实改变了 Agent 的下一次行为，或触发了配置的回调。
4. 对于持久化方案，可在两次独立会话中触发相同失败模式，确认第二次会话时被提前拦截。